File Formats

How a project is laid out#

A Vastopia game is a folder of plain files: JSON, INI, Godot .tscn text scenes, C# scripts and a handful of small binary blobs. There is no database. The editor reads and writes these files directly, and the MCP tools edit the same files, so anything you see here can also be inspected with a text editor or kept in version control.

The project splits into two halves that ship separately:

Two folders are build products rather than source: packs/ holds intermediate PCK output, and .export_cache/ (dot-prefixed, never packed) caches converted models so the editor and the publish step do not re-convert them. See Project structure for the full tree.

Conventions that apply everywhere#

• IDs. Items, NPCs, objects, VFX and interfaces use sequential integers allocated by the editor. Skills use numeric skill_ids. Shops, prayers and tasks use string ids. Assets use 26-character ULIDs. Never invent an id: the Data Editor, the map tools and the MCP all allocate the next free one.
• Floats for ints. Godot serialises many integers as floats in client JSON ("item_id": 1.0, "row": 0.0). Every loader tolerates this. Server JSON tends to use clean integers.
• Paths. Client model and icon references are res://assets/... or assets/... project-relative paths. Server script references are project-relative, such as server/scripts/objects/Obstacle.cs. A machine-absolute path in client data breaks the game at runtime, so keep everything relative.
• Versions. Files that carry a "version" key keep it; copy the value from an existing file of the same kind.
• Coordinates. TILE_SIZE is 0.5 world units. Spawn files store world units; tile-based files store integer tile coordinates. See Coordinate system.

Project root files#

project.vastopia#

An INI file in Godot ConfigFile style: quoted string values, a blank line after each section header. Written by the project wizard and updated by the editor as you work.

[project]

name="Default"
version="1.0.0"
created="2026-08-16T18:45:08"
modified="2026-08-16T18:45:08"
description=""
data_format=1

[paths]

maps_dir="assets/maps/"
ui_dir="assets/UI/"
data_dir="assets/data/"
interface_dir="assets/interface/screens/"

[game]

starting_map=""
title="Default"

[platform]

game_id=""

[server]

project_path=""

[client]

project_path=""

game_config.json#

The metadata file the launcher and client read. Uploaded as-is with every build.

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

The Game Config editor's branding, cover, screenshot and loading-screen settings are stored in a separate INI, game_config.cfg, at the project root ([basic], [branding], [gameplay], [platform] sections). That file is editor state for the platform listing, not something the client reads.

Other root files#

Client data: assets/data/#

items.json (client)#

A JSON array, one object per item. Visual and inventory fields only.

items.json (server)#

equipment_stats keys: accuracy_melee, accuracy_ranged, accuracy_magic, strength_melee, strength_ranged, strength_magic, defence_melee, defence_ranged, defence_magic (all default 0), attack_speed (default 6), attack_distance (default 1), combat_type (0 melee, 1 ranged, 2 magic), attack_anim_id, hit_gfx_id, projectile_id (default 0). See Items.

npcs.json (client)#

npcs.json (server)#

combat fields and the server's defaults: attackable (false), aggressive (false), aggro_radius (5.0), aggro_leash (12.0), combat_level (1), hitpoints (100), max_hit (0), attack_speed (0), attack_distance (0.0), accuracy_melee/ranged/magic (75/70/65), strength_melee/ranged/magic (1), defence_melee/ranged/magic (1), respawn_ticks (0), combat_script_path (""). The editor also writes combat_type, max_hit_melee, max_hit_ranged and max_hit_magic for its own UI.

objects.json (client)#

objects.json (server)#

animations.json#

Client only. An object with version and bases[]. Each base is a shared skeleton:

{ "version": 1, "bases": [ {
  "id": "humanoid", "display_name": "humanoid",
  "skeleton_path": "assets/skeletons/humanoid_skeleton.tscn",
  "animations": [
    { "id": 1.0, "name": "idle", "length_sec": 2.0, "in_place": false,
      "resource_path": "assets/anims/humanoid/anim_1.tres", "retarget_hint": "", "tags": [] }
  ]
} ] }

Animation ids are what idle_animation_id, NPC animations and weapon_animation_overrides reference. See Animations.

vfx_database.json#

Client only: { "vfx": [ { "vfx_id": 1, "name": "fire", "scene_path": "res://assets/vfx/fire.tscn", "scalex": 1.0, "scaley": 1.0, "scalez": 1.0 } ] }. The effect itself is the self-contained scene at assets/vfx/<name>.tscn. See VFX.

tab_config.json#

The client's tab bar. Two rows of up to six tabs each, twelve tabs maximum.

{
	"version": 1,
	"layout": {
		"rows": [
			{ "tab_width": 48, "spacing": 2 },
			{ "tab_width": 48, "spacing": 2 }
		]
	},
	"tabs": [
		{ "index": 0, "name": "Combat", "icon": "1.png", "interface_name": "combat",
		  "interface_id": 13, "enabled": true, "row": 0 }
	]
}

A legacy flat layout: {tab_width, spacing} still loads and applies to both rows. See Tabs.

map_area_config.json#

The HUD stat orbs and the up to two map buttons next to the minimap.

{
	"version": 1,
	"progress_bars": [
		{ "name": "HealthBar", "stat_key": "health", "icon": "1.png",
		  "fill_color": [1.0, 0.0, 0.0, 1.0], "default_value": 50.0 }
	],
	"bottom_buttons": []
}

Position and size are computed by the client; only the fields above are read. See Game screen and HUD.

skills_config.json#

Present in both assets/data/ and server/data/ with slightly different rows.

The client builds its skills panel from this file, so the skills you define really appear in game. See Skills.

interface_database.json#

Both sides, ids must match: { "interfaces": [ { "id": 1, "name": "Shop", "path": "res://assets/interfaces/screens/Shop.tscn", "type": "gamescreen" } ] } with type one of gamescreen, tab, chatbox. The editor regenerates it by scanning assets/interface/screens/ on save and export; the server opens interfaces by these integer ids. See Custom interfaces.

locations.json, wisdom_config.json#

locations.json is the same on both sides: { "locations": [ { "name": "Wilderness", "script_path": "" } ] }. wisdom_config.json (prayers/buffs) is on both sides but with a different row on each. Server: { "version": 1, "drain_interval_ticks": 4, "prayers": [ { "prayer_id", "name", "category", "level_required", "drain_rate", "effect_type", "effect_value", "overhead_icon", "conflicts_with": [] } ] }. Client: { "version": 1, "categories": ["overheads", "combat", "utility", "misc"], "prayers": [ { "prayer_id", "name", "category", "level_required", "icon_asset_id", "ordinal" } ] } — display fields only, no drain or effect data. prayer_id is a string and joins the two.

Server-only data: server/data/#

systems.json#

Written whenever you create a project or change systems in Game Config. The server honours it at module-load time, which matters because some template modules also exist as pre-compiled platform copies that deleting a file cannot remove.

{
	"version": 1,
	"enabled_systems": ["dialogue", "quests", "tasks", "skills_xp", "wisdom", "crafting", "shops",
		"banking", "trading", "social", "combat", "aggro", "specials", "buffs", "bosses", "drops"],
	"disabled_systems": [],
	"disabled_modules": []
}

enabled_systems mirrors [systems] enabled in project.vastopia; disabled_modules lists the module ids the server must refuse to load. See Templates and gameplay systems.

property_manifests.json#

Declares the custom typed properties available under each entity's properties block. type is bool, int, float or string.

{ "items":   [ {"name": "value", "type": "int", "default": 0}, {"name": "weight", "type": "float", "default": 0} ],
  "npcs":    [ {"name": "attackable", "type": "bool", "default": false} ],
  "objects": [ {"name": "interactable", "type": "bool", "default": false},
               {"name": "render_on_minimap", "type": "bool", "default": true} ] }

script_bindings.json#

Entity id to script path, rebuilt from the script_path fields when a definition that binds a script is saved: { "items": {}, "equipment": {}, "npcs": {}, "npc_combat": {}, "objects": {"3": "server/scripts/objects/Obstacle.cs"} }.

world_settings.json#

Engine defaults for respawn and death rules; every key is the engine default, so deleting the file changes nothing. Keys: respawn_region, respawn_x, respawn_y, respawn_z, drop_items_on_death, drop_equipment_on_death. Keys starting with _ are comments.

Schema-backed content: server/schemas/#

Shops, recipes, tasks, loot tables, dialogue, bosses, buffs and combat formulas are not in server/data/. Each lives as a pair under server/schemas/<Category>/<name>/: <name>.json (the schema the Script Editor uses for autocomplete and table editing) and <name>_data.json (the rows). Drop tables, for example, are server/schemas/Drops/npc_drops/npc_drops_data.json, with npc_table_drops, npc_wheel_drops and the item_*, object_* and misc_* variants alongside. The Game Tools pages document each: Loot tables, Shops, Recipes, Tasks, Dialogue.

Map files: assets/maps/<map>/#

Saving a map writes the files below into its folder and re-derives the server exports in the same pass.

regions.json#

One object with version, next_id and four arrays. Every element has id, name and type.

Model paths, scale and footprint are never stored here; they come from the NPC and object definitions, so changing a definition changes every map that uses it. See Regions and elements.

props.bin#

Little-endian binary. Version 2 is the only version the client and the MCP accept, which is why editor-only metadata lives in the sidecar instead.

magic        "PROP" (4 bytes)
version      u8  = 2
model_count  u32
per model:
  flags        u8   bit0 = batched (multimesh), bit1 = has scale
  path_len     u16
  path         UTF-8, project-relative, e.g. assets/models/<ULID>_tree/tree.scn
  inst_count   u32
  per instance:
    position   3 x f32  (world units)
    rotation   3 x f32  (radians)
    scale      3 x f32  only when the model's has-scale flag is set

The has-scale flag is per model: if any instance of a model is scaled, every instance of that model writes three scale floats. The same path may appear twice, once batched and once as individual props.

props_meta.json#

{ "version": 1, "models": { "<path>": [ {...}, null, ... ] } }. Keys are the same model paths as props.bin, with #mm appended for the batched entry; each array runs parallel to that model's instances. A record may hold follow (re-seat on terrain edits; on a batched entry it only ever appears as false, the single opt-out, carried in by batching a Fixed prop), surface (terrain or layer), layer (1-based height layer id), offset (height above the surface), align (tilt to the surface normal) and normal. An empty record means "fixed" for an individual prop and "sit exactly on the surface" for a batched copy. If the sidecar is missing or the counts no longer match, that model's metadata is ignored and its instances are treated as fixed. See Props and model painting.

height_layers.terrain#

magic            "HTLR" (4 bytes)
version          u8  = 3
layer_count      u8
active_layer     u8
tile_size        f32  (0.5)
tiles_per_region u16  (64 for a standard region)
region_count     u16
regions          region_count x (x: i16, z: i16)
per layer:
  layer_id       u8
  name_len       u8, then name bytes (UTF-8)
  color          4 bytes r, g, b, a (0-255)
  default_height f32
  per region:    tiles_per_region^2 x f32 height offsets above the terrain (0.0 = on the ground), row by row

Only active terrain regions are stored, so the file stays small on sparse maps. See Height layers.

water.json#

{ "version": 1, "enabled": false, "level": -0.01, "water_color": [r, g, b, a], "deep_color": [r, g, b, a], "highlight_color": [r, g, b, a], "fresnel_power": 3.0, "highlight_strength": 0.2, "roughness": 0.3, "metallic": 0.0 }. The default level sits just under zero so the surface never z-fights terrain standing at exactly height 0.

terrain_data.json#

{ "bounds": { "min_x", "min_z", "max_x", "max_z" }, "blocked_tiles": [[world_x, world_z], ...], "height_levels": [] } with bounds and blocked tiles in world units. It is a convenience export; the server reads the binary flag file instead.

Server map exports: server/data/maps/#

Saving a map writes four per-map files here. They are derived, so edit the map rather than these files.

npc_spawns/<map>.json#

{ "version": 1, "map_name": "home", "spawns": [
  { "spawn_id": 275, "npc_id": 1, "x": -0.5, "z": 7.0, "rotation_y": 0.0,
    "spawn_radius": 1.0, "spawn_count": 1, "respawn_time": 0, "behavior": "idle",
    "wander_intensity": 1, "patrol_path": [], "spawn_condition": "" } ] }

x and z are world units (tile times 0.5); the server derives height from the terrain. patrol_path entries are {x, y, z} objects.

object_spawns/<map>.json#

{ "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": 1.0, "interaction_type": "use", "interaction_radius": 2.0,
    "is_persistent": true, "script_on_interact": "", "custom_properties": {} } ] }

Footprint is deliberately absent: the server reads tile_width and tile_depth from the object definition.

location_bounds/<map>.json#

{ "version": 2, "map_name", "locations": [ { "location_id", "name", "tiles": [[tx, tz], ...], "audio": { "ambient_track", "music_path", "enter_sound", "leave_sound" }, "environment": { "fog_enabled", "fog_color", "fog_density", "ambient_color", "ambient_energy", "sun_color", "sun_energy" }, "weather_type", "difficulty_modifier", "script_path" } ] }.

flag_data/<map>.terrain#

The walkability file the server loads. Little-endian, sparse version 2:

magic            "REGN" (4 bytes)
version          u8  = 2
layer_count      u8
tile_size        f32  (0.5)
tiles_per_region u16
region_count     u16
regions          region_count x (x: i16, z: i16)   active region grid cells
blocked_count    u32
blocked tiles    blocked_count x (tile_x: i16, tile_z: i16, layer_mask: u8)

layer_mask is a bitfield: bit N set means the tile is blocked on height layer N. Only tiles inside an active region are walkable at all, so activating regions in the Map Editor is what defines the playable area. Version 1 files (bounds-based: tile_size, min_x, min_z, max_x, max_z instead of the region list) still load. On dungeon maps every un-carved tile is written as blocked on the ground layer. See Map files and export.

Other project files#

assets/data/building_prefabs.json#

{ "version": 1, "prefabs": [ { "name", "width", "depth", "floors", "pieces": [...] } ] }. width, depth and floors describe the plot; stamping reads only name and pieces. Each piece has dx, dz (tile offset from the plot's south-west corner), rotation_y, height_layer_id (the floor) and optional off_x, off_z for free-placed pieces, then either:

• a model piece: kind: "prop", prop_id, model_path, name, tile_width, tile_depth, stamped as a plain prop; or
• an interactable object: object_id, interaction_type: "use", interaction_radius: 2.0, script_on_interact, is_persistent: true, custom_properties: {}, stamped as a region element.

See Building prefabs.

assets/AssetLibrary.json#

The registry of every imported asset, keyed by ULID.

{ "version": 1, "assets": [
  { "id": "01KY39MGW5AJAXFWX4Q2836T4N", "name": "humanoid_skeleton", "type": 7,
    "path": "skeletons/humanoid_skeleton.tscn", "original_filename": "humanoid_skeleton.tscn",
    "import_date": "2026-07-21T17:34:44", "tags": [], "metadata": {},
    "cloud_id": 0, "sha256": "" } ] }

Type folders under assets/: sprites in sprites/, models in models/<ULID>_<name>/ (converted to a self-contained .scn on import), SFX in audio/sfx/, music in audio/music/, textures in textures/, animations in anims/<base>/, UI scenes in UI/, skeletons in skeletons/, anything else in misc/. Recognised import extensions: .png .jpg .jpeg .webp .svg (sprites), .glb .gltf .obj .fbx (models), .wav .ogg (SFX), .mp3 (music). See Asset manager.

Quick index#