Map scene deployment - Revision history

QCherry: Release 0.1.4 BUILD133 / Protocol 36 and document authenticated event origin

2026-09-21T20:40:42Z

Release 0.1.4 BUILD133 / Protocol 36 and document authenticated event origin

← Older revision		Revision as of 20:40, 21 September 2026
Line 1:		Line 1:
	= Map scene deployment =		= Map scene deployment =
	'''Since 0.1.4 ~~(in development; not available in public 0.1.3)~~.'''		'''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'''.		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'''.

QCherry: 0.1.4 BUILD124: remove fixed world-object count and request caps; document remaining data/transport bounds

2026-09-20T18:37:33Z

0.1.4 BUILD124: remove fixed world-object count and request caps; document remaining data/transport bounds

← Older revision		Revision as of 18:37, 20 September 2026
Line 45:		Line 45:
	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.		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; ~~all still share native client limits (512 instances and~~ 16 owning resources). Splitting a ~~scene does~~ not ~~bypass these limits~~.		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 ==		== Collision and boundaries ==

QCherry: Document Map Editor, saved maps, static scene deployment and Lua APIs since 0.1.4

2026-09-20T18:19:25Z

Document Map Editor, saved maps, static scene deployment and Lua APIs since 0.1.4

New page

= 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 ==
# In the editor, save <code>untitled</code> (confirm the second click) and wait for the successful save message.
# Click '''Export Lua'''. The server writes <code>resources/map_editor/.storage/data-export_untitled.lua</code>.
# 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 <code>map.lua</code> if needed.
# Install the complete supplied <code>map_scene</code> resource. Its source example is <code>examples/resources/map_scene</code>; server packages include it as <code>resources/map_scene</code>.
# Copy the exported file to <code>resources/map_scene/map.lua</code>, replacing the placeholder. Keep <code>client.lua</code> and <code>scripts.xml</code>; do not merely copy the export into an arbitrary resource folder.
# In the '''server console''':
<pre>refresh
start map_scene</pre>

If the resource is already running and you did not stop it first, use <code>restart map_scene</code> 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:
<pre>resources/
map_scene/
scripts.xml
map.lua (your exported MapScene data)
client.lua (the supplied loader)</pre>

The supplied manifest loads data before the loader:
<syntaxhighlight lang="xml">
<scripts>
<script src="map.lua" type="client" />
<script src="client.lua" type="client" />
</scripts>
</syntaxhighlight>

Keep <code>map_scene</code> 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 <code>MapScene</code> 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 <code>[Map Scene]</code>.
* Resource stop/disconnect removes only its own native instances. <code>stop map_scene</code> 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; all still share native client limits (512 instances and 16 owning resources). Splitting a scene does not bypass these limits.

== Collision and boundaries ==
Meshes use their own collision data when <code>collision=true</code>. 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.

[[Category:Lua API]]
[[Category:Lua Examples]]