Map scene deployment

Map scene deployment

Since 0.1.4.

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 the complete matching manifest and loaders. From 0.1.9 this includes server.lua as well as 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    (client static/removal loader)
    server.lua    (0.1.9 server-owned door loader)

The updated 0.1.9 manifest loads shared data before the separate server/client loaders (older static-only releases used a client-only manifest):

<scripts>
  <script src="map.lua" type="shared" />
  <script src="server.lua" type="server" />
  <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.

Static objects remain client-side reconstruction, not networked object physics. From 0.1.9, approved doors use separate server-owned interaction/state, while original-world removals are applied from trusted saved map data. 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.

Supported documents from 0.1.9

Available from 0.1.9. Use matching updated clients and server.

Use all three supplied scripts/manifest entries shown above. The updated loader accepts formats 1, 2 and 3: static objects retain their existing path; approved doors are registered through server setWorldDoors and are not duplicated as client static proxies; format-3 original-world removal IDs/catalog are applied by the client loader. Unsupported interactive seats, lights and ladders are rejected, not downgraded to meshes. Legacy JSON cannot represent prefabs/removals.

Door placements are reapplied at resource start, initially closed. Session open/closed state is synchronized to observers/late joiners, but is not persisted across a server/resource restart. Optional key rules are server Lua responsibilities and are not included in a plain placement export. Stopping the resource releases its door set and native removal claims. Other owners remain unaffected.

Do not deploy the same doors through map_editor LIVE and map_scene simultaneously: these are independent owning resources. Keep a backup of your exported map and use matching game/catalog data. World model removal covers identity, restoration, streaming, protected objects and the unchanged NPC obstacle map.

Available from 0.1.9. Use matching updated clients and server.

Shared placed-door path

Approved doors support server-owned placement, interaction state and late-join replay through setWorldDoors, including the updated editor/map_scene deployment workflow. Custom keys documents independent native key types, copies, drop/pickup, key access and lifecycle callbacks; World door prefab catalog lists the door-only aliases. Seats, lights and placed ladders remain outside this shared door runtime.