Project Structure

What a project is#

A Vastopia project is a plain folder on your disk. Everything that makes up your game lives inside it as ordinary files: JSON data, Godot scenes, 3D models, C# scripts and a handful of binary map files. There is no database and no hidden state; you can copy, zip, back up or put the folder under version control like any other directory.

The folder is identified by one file at its root, project.vastopia. The editor treats any directory that contains that file as a project, and refuses to open or delete a folder without it.

Two things make the layout worth understanding:

• The folder is split into a client half (assets/) and a server half (server/). When you push a build, the client half is packed into a PCK that players download, and the server half is zipped and sent to the game server. A definition such as an item exists in both halves with different fields, and the editors keep the two copies in sync for you. See Data Editor overview for the split per data type.
• Several directories are derived output or caches that the editor regenerates. They are never uploaded and are safe to delete.

Folder layout#

A project created from the bundled starter looks like this (asset folders such as audio/ appear the first time you import that kind of file):

my-game/
├── project.vastopia          # Project identity and settings (INI)
├── game_config.json          # Player-facing metadata (title, description, starting map)
├── prop_library.json         # The map editor's prop library
├── interface_library.json    # Folder assignments for the GUI editor's interface list
│
├── assets/                   # CLIENT SIDE - packed into the PCK
│   ├── AssetLibrary.json     # Asset registry (every imported asset, keyed by ULID)
│   ├── maps/<map_name>/      # One directory per map
│   ├── data/                 # Client data JSON (items.json, npcs.json, objects.json, ...)
│   ├── interface/screens/    # Interface scenes (.tscn), incl. tabs/ and templates/
│   ├── models/               # 3D models, one folder per asset
│   ├── sprites/  textures/  audio/  anims/  skeletons/  icons/  vfx/
│   ├── branding/             # Game icon, cover, screenshots, loading screens
│   ├── images/  UI/  characters/   # HUD art, interface art, player character assets
│
├── server/                   # SERVER SIDE - zipped and uploaded with every build
│   ├── data/                 # Server data JSON + per-map spawn and collision files
│   ├── modules/              # C# gameplay modules
│   ├── scripts/              # C# scripts (commands, interfaces, npcs, objects, ...)
│   └── schemas/              # Script API schemas and schema-backed data
│
├── packs/                    # Build output (.pck files) - regenerated, never uploaded
├── .export_cache/            # Converted-model cache for fast exports - safe to delete
└── .vastopia_upload/         # Spool for assets queued for the cloud library

The client half: assets/#

Everything under assets/ is content the player's game client needs. When a build is exported, the editor packs it into four categories:

assets/AssetLibrary.json is the registry the Asset Manager maintains: every imported asset gets a ULID, a type and a path here.

The server half: server/#

The server never sees assets/. When you push a build, the editor zips exactly four subfolders of server/ - data, modules, scripts and schemas - into the server package.

The server folder also carries VastopiaScripts.csproj, Directory.Build.props and a generated global-usings file. Those exist so an IDE can compile-check your scripts; see IDE setup.

Derived output and caches#

Anything dot-prefixed at the project root is treated as a cache: it is skipped by Save Project to Cloud and Export as Template, and the exporter never packs it.

project.vastopia#

project.vastopia is an INI file in Godot ConfigFile style: quoted string values, a blank line after each section header. The editor writes it; you rarely need to edit it by hand, but it is useful to know what each section controls.

The [server] and [client] paths describe your machine, not your game. They are left alone in cloud saves and templates, and re-stamped with the local checkouts whenever a project is downloaded or created.

game_config.json#

game_config.json is the small, player-facing metadata file. It is shipped inside the data pack and uploaded alongside every build. Every value is a string except tags (an array) and the spawn tile (integers):

{
	"description": "",
	"developer": "",
	"genre": "Adventure",
	"starting_map": "",
	"tags": [],
	"title": "Default",
	"version": "1.0.0",
	"website": ""
}

The New Project wizard fills title, description, developer, website, genre and tags. The Game Settings editor adds start_x and start_z and keeps starting_map current. See Game configuration for where each field is edited.

Where projects are kept#

• Default location: the New Project wizard proposes a folder under your Documents directory (Documents/VastopiaProjects/), and projects downloaded from the cloud land there too. You can choose any writable location with Browse....
• Recent projects: the editor remembers the last ten projects you opened. The list is pruned automatically when a folder disappears. Remove from Recent on a project card only forgets the entry; Delete Project... removes the folder from disk after a confirmation.
• Game link: opening a project whose [platform] game_id is set records the game-to-folder mapping on this machine, so the hub can tell which of your account's games already live here.

Version control#

Because a project is plain files, git works well. Commit everything except the derived folders above. If you create a project with the MCP server, it initialises a repository for you with a .gitignore covering packs/, *.pck, server_data.zip, .vastopia_backups/, audit_log.jsonl, terrain_work/, *.bak, *.tmp-*, .godot/, .import/ and *.uid. The same list is a good starting point for a project you created in the editor.

With AI (MCP)#

• get_project_summary - name, version, starting map, game id, maps and entity counts.
• get_project_config - every section of project.vastopia as an object.
• set_project_paths - change [paths] entries without touching the rest of the file.
• validate_project - report entities that exist on only one side of the dual export, placements pointing at deleted definitions, dangling script bindings and leftover temp files.
• list_projects, select_project, get_active_project, create_project - manage several projects in one workspace.