Map Files and Export

Where maps live#

Every map is a folder under assets/maps/ in your project, named after the map. Saving a map with Ctrl+S (or the Save button) writes the folder in one pass: the terrain scene and its data, the placed elements, props and water, and then the derived server files under server/data/. You never edit these files by hand for normal work; this page explains what they are so you can recognise them, back them up, and understand what reaches the client and the server.

The standard map is centered on the origin and covers tiles -64 to 63 on both axes, with one tile being 0.5 world units. See the Map Editor overview for the grid and region model, and the coordinate system reference for how tiles map to world units.

Map folder contents#

A typical map called home looks like this on disk:

assets/maps/home/
├── home_region.tscn        # the map scene (Terrain3D node, environment, objects)
├── data/                   # Terrain3D region data, one file per active region
│   ├── terrain3d_00_00.res
│   ├── terrain3d-01_00.res
│   └── ...
├── regions.json            # NPC spawners, interactable objects, trigger zones, locations
├── props.bin               # decorative props and painted meshes (binary, version 2)
├── props_meta.json         # surface-follow metadata for props (only when used)
├── height_layers.terrain   # elevated floors and their per-tile heights (binary)
├── terrain_data.json       # playable bounds and blocked tiles, in world units
├── water.json              # water plane settings
├── dungeon.json            # dungeon maps only: carved tiles
└── thumbnail.png           # preview captured on every save

What the client receives#

When you build the game, the exporter packs each map folder into the client package at res://assets/maps/<name>/, lowercasing the folder and file names. Only genuine map data is packed: files with the extensions .tscn, .scn, .tres, .res, .json, .terrain, .bin, .png, .webp, .jpg and .jpeg. Backups (.bak), temporary files and anything else in the folder are skipped and logged during export.

The client loads <name>_region.tscn, the Terrain3D data next to it, props.bin, height_layers.terrain and water.json. It never places NPCs or objects from regions.json; those arrive from the server at runtime.

Server export#

Saving a map also re-derives the files the server needs. They are written under server/data/ in your project and ship with every build as part of the server data archive (see Builds and versions). Dev Test starts the local server inside your project's server/ folder, so a saved map is immediately testable.

A few details worth knowing:

• Positions are world units, so x = 6.0 is tile 12. Spawns carry no Y coordinate; objects record which height layer they sit on instead.
• Object footprints (tile_width, tile_depth) are deliberately absent from spawn files. The server reads them from server/data/objects.json, which is why changing an object's footprint in the Data Editor affects every map that uses it. See Objects.
• The walkability mask has one bit per height layer: bit 0 is the ground, bit 1 the first elevated layer, and so on. On dungeon maps every un-carved tile is written as blocked on the ground layer.
• The server keeps loading maps whose walkability file is the older version 1 (bounds-based), but the editor always writes version 2.

Each spawn file is a JSON object with version, map_name and a spawns array:

{
  "version": 1,
  "map_name": "home",
  "spawns": [
    {
      "spawn_id": 300,
      "object_id": 3,
      "x": 6.0,
      "z": -1.0,
      "height_layer_id": 0,
      "rotation_y": 0.0,
      "scale": 4.0,
      "interaction_type": "use",
      "interaction_radius": 2.0,
      "is_persistent": true,
      "script_on_interact": "",
      "custom_properties": {}
    }
  ]
}

Renaming, duplicating and deleting maps#

Right-click a map card in the map browser for Rename, Duplicate and Delete.

• Rename renames the folder and the <map>_region.tscn inside it. The server files keep the old name until you open and save the map again, which writes a fresh set under the new name.
• Duplicate copies the whole folder under the new name. Save the copy once to generate its server files.
• Delete removes the folder and every server file that was exported for that map, so nothing is left behind.

Setting the starting map#

The map players enter when they first log in is configured in two places that the editor keeps for you:

1. Open Game Settings from the top bar.
2. Under World, pick a map from the Starting map dropdown. Press Refresh if a map you just created is not listed.
3. There is no save button - the status line at the bottom reads "Changes are saved automatically", and every edit writes game_config.json and mirrors [game] starting_map into project.vastopia.

See Game config for everything else the Game Settings editor controls.

With AI (MCP)#

• create_map scaffolds a new map folder (regions.json, terrain_data.json, water.json, height_layers.terrain, <map>_region.tscn and an empty data/) together with its flag_data/<map>.terrain, centered on the origin and 128 tiles square by default.
• list_maps lists the maps in the project and flags the starting map.
• set_starting_map validates that the map exists, writes [game] starting_map in project.vastopia and keeps game_config.json in sync. It supports dryRun.
• get_map_layout reports the map's extent and what is already placed, reading terrain_data.json and the spawn files.

See the MCP tools reference for the full list. Both the editor and the MCP write the same files, so a map authored one way can always be opened and continued the other way; the MCP refuses to write any file that an unsaved map tab in the editor would overwrite on save, so the two never collide.