Map scene deployment

Map scene deployment

Since 0.1.4 (in development; not available in public 0.1.3).

Use this workflow to display objects exported by Map editor for players, including late joiners. Save/Open is an editor project workflow; Export Lua + map_scene is deployment.

Example: deploy untitled

1. In the editor, save untitled (confirm the second click) and wait for the successful save message.
2. Click Export Lua. The server writes resources/map_editor/.storage/data-export_untitled.lua.
3. Close the editor to remove its private preview copies. If map_scene is already running, stop it before replacing its map file. Back up the previous map.lua if needed.
4. Install the complete supplied map_scene resource. Its source example is examples/resources/map_scene; server packages include it as resources/map_scene.
5. Copy the exported file to resources/map_scene/map.lua, replacing the placeholder. Keep client.lua and scripts.xml; do not merely copy the export into an arbitrary resource folder.
6. In the server console:

refresh
start map_scene

If the resource is already running and you did not stop it first, use restart map_scene after replacing the file. Clients that already downloaded older resource files may need to reconnect; reconnect after a map update to verify the current resource catalog. The normal resource startup/download lifecycle delivers the map to joining clients.

Expected layout:

resources/
  map_scene/
    scripts.xml
    map.lua       (your exported MapScene data)
    client.lua    (the supplied loader)

The supplied manifest loads data before the loader:

<scripts>
  <script src="map.lua" type="client" />
  <script src="client.lua" type="client" />
</scripts>

Keep map_scene in your normal server resource startup configuration if it should return after every server restart. Starting it manually does not modify that configuration. You do not need to keep map_editor running for a deployed map.

What the loader does

• Reads the MapScene table, validates format/version/units/world and objects, then creates them sequentially using WorldObjects.request.
• Waits/retries when gameplay or native dependencies are not ready, including before a joining player's spawn.
• Handles onClientWorldObjectsReset by rebuilding after the client world/session resets.
• Logs non-retryable object failures instead of claiming they loaded. Check client debug output for [Map Scene].
• Resource stop/disconnect removes only its own native instances. stop map_scene unloads the deployed scene without deleting its saved source files.

This is static scene reconstruction on each client, not server-authoritative dynamic object replication. There is no live collaborative editor or networked object physics in this feature. A successful editor preview does not by itself prove another client's asset loading or a late-join test; verify with a second player and a fresh join.

Updating, removing and splitting maps

Reopen the saved editor project, make changes, save and export again; replace map_scene/map.lua and restart/reconnect as above. Export is a snapshot, not a live link to the editor save. Stop map_scene while editing the same scene to avoid overlapping local copies.

For several separately managed static scenes, copy the complete map_scene template to differently named resources and put each export in its own map.lua. Resource names must follow server naming rules. Each owns its instances. BUILD124 and updated resource scripts remove the fixed 500/512 object-count caps; at most 16 owning resources are still supported. Splitting documents avoids a single large editor JSON file, not the game's memory/performance constraints. Objects are still created sequentially rather than all in one frame.

Collision and boundaries

Meshes use their own collision data when collision=true. They do not modify the original packaged map, server navigation/NPC pathfinding or the authoritative anti-cheat world model. Validate movement on custom floors, walls and platforms before using them in gameplay. The loader is not a replacement for server-side gameplay validation. No OBJ files are uploaded or imported: mesh paths refer to assets already installed with the game.