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

2026-09-21T20:40:41Z

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 editor =		= Map editor =
	'''~~Since~~ 0.1.4 ~~(in development; not included in public 0.1.3)~~.''' Use ~~matching~~ 0.1.4 ~~server resources and a current development~~ client~~. For the September 20 development packages, use BUILD124~~ or later and ~~updated~~ map_editor/map_scene ~~scripts for~~ the ~~object~~-cap removal; the held-key freecam fix is included~~. This documentation is not a public updater announcement~~.		'''Available since 0.1.4.''' Use the complete 0.1.4 client (BUILD133 or later) with the matching Protocol 36 server and current map_editor/map_scene resources. Both resources are included in the Windows and Linux server packages but are not auto-started. Object-cap removal and the held-key freecam fix are included.

	The Lua editor places existing game meshes in MainMap. It provides a searchable model browser, local placement preview, numeric transforms, scene list, duplicate, undo/redo, save/load and export. No separate reference Map Editor mod is needed.		The Lua editor places existing game meshes in MainMap. It provides a searchable model browser, local placement preview, numeric transforms, scene list, duplicate, undo/redo, save/load and export. No separate reference Map Editor mod is needed.

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

2026-09-20T18:37:32Z

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 1:		Line 1:
	= Map editor =		= Map editor =
	'''Since 0.1.4 (in development; not included in public 0.1.3).''' Use matching 0.1.4 server resources and a current development client. For the September 20 development packages, use ~~BUILD123~~ or later for the held-key freecam fix. This documentation is not a public updater announcement.		'''Since 0.1.4 (in development; not included in public 0.1.3).''' Use matching 0.1.4 server resources and a current development client. For the September 20 development packages, use BUILD124 or later and updated map_editor/map_scene scripts for the object-cap removal; the held-key freecam fix is included. This documentation is not a public updater announcement.

	The Lua editor places existing game meshes in MainMap. It provides a searchable model browser, local placement preview, numeric transforms, scene list, duplicate, undo/redo, save/load and export. No separate reference Map Editor mod is needed.		The Lua editor places existing game meshes in MainMap. It provides a searchable model browser, local placement preview, numeric transforms, scene list, duplicate, undo/redo, save/load and export. No separate reference Map Editor mod is needed.
Line 83:		Line 83:

	== Limits and troubleshooting ==		== Limits and troubleshooting ==
	* ~~At most 500 document objects;~~ the native client ~~has a combined 512-instance limit across all owning resources~~, ~~including previews~~/~~deployed scenes~~. Undo history holds 200 commands.		* No fixed object-count cap in the editor, legacy import, native client or map_scene loader since the BUILD124 revision of 0.1.4. Actual capacity depends on mesh complexity, RAM/VRAM, CPU and the remaining document/transport limits. Undo history still holds 200 commands.
			* The shared JSON codec accepts up to 1 MiB and 65536 table entries per document (nested fields count), while editor transfers remain bounded to 1000000 bytes. Split larger projects into separate scene resources when needed; removing the count cap does not make one file unlimited. Test representative maps in-game before deployment.
	* Position: +/-100000 metres; rotation: +/-36000 degrees; each scale axis: 0.01-100. Editor upload/download JSON is limited to 1000000 bytes. See [[World objects]] and [[Resource data storage]] for engine limits.		* Position: +/-100000 metres; rotation: +/-36000 degrees; each scale axis: 0.01-100. Editor upload/download JSON is limited to 1000000 bytes. See [[World objects]] and [[Resource data storage]] for engine limits.
	* One user holds a named-map lock until their editor session closes/expires. This prevents simultaneous conflicting saves, not a collaborative editing session.		* One user holds a named-map lock until their editor session closes/expires. This prevents simultaneous conflicting saves, not a collaborative editing session.

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

2026-09-20T18:19:24Z

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

New page

= Map editor =
'''Since 0.1.4 (in development; not included in public 0.1.3).''' Use matching 0.1.4 server resources and a current development client. For the September 20 development packages, use BUILD123 or later for the held-key freecam fix. This documentation is not a public updater announcement.

The Lua editor places existing game meshes in MainMap. It provides a searchable model browser, local placement preview, numeric transforms, scene list, duplicate, undo/redo, save/load and export. No separate reference Map Editor mod is needed.

'''Three different workflows:''' Save/Open keeps an editable project; Export Lua deploys a static scene through [[Map scene deployment|map_scene]]; legacy JSON exchanges layouts with the reference editor. Saving alone does not make objects appear for other players.

== Start the editor ==
# Install the complete <code>map_editor</code> resource in the running server's <code>resources</code> directory, including its client, server, shared and UI files.
# In the '''server console''', run <code>refresh</code>, then <code>start map_editor</code>.
# Use a client supporting these 0.1.4 APIs. If scripts were replaced while connected, reconnect to obtain the current client resource files.
# With the supplied <code>gothic_rp</code> gamemode running, log in, finish spawning and use <code>/mapeditor</code>. Your account needs <code>admin.world</code> permission.

The editor is not autostarted. Its server authorization bridge currently trusts the <code>gothic_rp</code> resource by name. Other gamemodes need an equivalent server-side permission bridge '''and''' an intentional update to the trusted-source check in <code>map_editor/server/storage.lua</code>; merely sending an open event from another resource is not sufficient. Never authorize editing using client-supplied permission claims.

== Place your first object ==
# Type a model name or part of its asset path in Models. Use Previous/Next to page through results (40 per page).
# Click a model to create a local preview. Move the pointer over the central world viewport: the placement ray follows the world surface.
# Use the wheel to adjust preview height. Click the viewport to place the object and wait for confirmation.
# Choose '''Cancel preview''' or Escape before selecting an existing object. You can select it in the world or in the bottom Scene list.
# In Inspector, edit position, rotation, scale or name and click '''Apply transform / name'''. Position is in metres; rotation is in degrees; scale is a multiplier.

The Scene list supports name/ID search and 30 rows per page. <code>[H]</code> means hidden, <code>[L]</code> locked, and <code>[!]</code> failed to render. Use this list for hidden or non-colliding objects that a world ray cannot select. Hide, Lock and Collision are saved properties. Preview collision is disabled.

== Controls ==
{| class="wikitable"
! Control !! Action
|-
| W / E / R outside text inputs || Select Move / Rotate / Scale mode for axis-step editing.
|-
| X/Y/Z minus and plus buttons || Apply the current transform mode on that axis. Rotation X/Y/Z corresponds to roll/pitch/yaw; scale steps are 0.1.
|-
| Grid / Angle || Position step in metres / rotation step in degrees. Zero disables placement snapping; axis buttons still use a fallback step (0.1 m or 1 degree). Numeric input retains exact values.
|-
| Delete; Ctrl+C / Ctrl+V / Ctrl+D || Delete; copy / paste / duplicate.
|-
| Ctrl+Z / Ctrl+Y || Undo / redo confirmed create, delete and property/transform changes.
|-
| F || Focus the camera on the selected object.
|-
| Escape || Cancel preview, or deselect when no preview is active.
|}

'''Freecam:''' hold the right mouse button over the world viewport, or click Fly camera. Move the mouse to look around. W/S flies along the full view direction, including up/down pitch; A/D strafes horizontally; Q/E moves vertically; Shift is faster. Release RMB or press Tab/Escape to return to GUI interaction. Speed sets flight speed; the viewport wheel adjusts it when no placement preview is active. W/E/R are transform shortcuts outside fly mode, not during flight. Closing the editor releases its camera and input ownership.

There are no mesh thumbnails or draggable 3D axis gizmos in this implementation: use the live preview, Inspector fields and axis buttons. Selection requests custom-depth rendering, but a visible world outline depends on the game's post-processing; the selected hierarchy row is also highlighted.

== Save, reopen and export ==
Use the name field at the top. Names contain 1-48 ASCII letters, digits, underscores or hyphens, '''without a file extension'''. Example: <code>untitled</code> or <code>old_camp_rocks</code>.

'''Save / Save As:''' click once, then click the same action again within six seconds to confirm saving/overwriting. Wait for <code>Saved atomically on server (.storage).</code> before exporting or leaving. For Save As, first change the name field; it uses the same save mechanism. <code>*</code> marks unsaved changes. There is no automatic save on closing or stopping the resource.

'''Open an existing project:''' enter its name (for example <code>untitled</code>) and click '''Open'''. If there are unsaved changes, the second click confirms discarding them. Open replaces the editor scene; it does not merge another map into it. A successful load reports the object count and failed render count. You do not need either export file to reopen a saved project.

'''New:''' clears the working scene after confirmation; it does not delete saved files. Save under a new name to avoid overwriting a previous project. Undo/redo history is session-local and resets on load.

The following files live on the '''server''', not in your client's Downloads directory:
{| class="wikitable"
! Path relative to the running server !! Purpose
|-
| <code>resources/map_editor/.storage/data-map_untitled.json</code> || Working project: Save creates it; Open reads it.
|-
| <code>resources/map_editor/.storage/data-map_untitled.json.bak</code> || Previous overwritten save, if one existed. One backup generation, not unlimited history.
|-
| <code>resources/map_editor/.storage/data-export_untitled.lua</code> || Export Lua output for map_scene deployment.
|-
| <code>resources/map_editor/.storage/data-export_legacy_untitled.json</code> || Export legacy JSON output; not the ordinary Open format.
|-
| <code>resources/map_editor/.storage/data-legacy_untitled.json</code> || Input filename read by Import legacy.
|}

Exports use the last acknowledged save for the current name. Save again after editing, wait for the confirmation, then export again. Back up <code>.storage</code> before replacing server/resource folders. To move an editable project to another server, copy its <code>data-map_NAME.json</code> into that server's map_editor storage, then Open <code>NAME</code>; the target must have a compatible model catalog.

== Make objects visible to players ==
Follow [[Map scene deployment]]: Export Lua, copy the output as <code>resources/map_scene/map.lua</code> alongside the supplied loader and manifest, close the editor, then start/restart map_scene. This is the supported static scene workflow with reconstruction for late joiners. The editor's private live preview is not multiplayer collaborative editing.

== Legacy JSON import ==
# Copy a compatible legacy JSON layout to <code>resources/map_editor/.storage/data-legacy_NAME.json</code>.
# Enter <code>NAME</code> in the editor and click '''Import legacy'''. Confirm discarding unsaved changes if prompted.
# Save the converted project, then use ordinary Open for future editing.

Legacy entries contain <code>mesh, x, y, z, yaw, scale</code>. Coordinates are centimetres and are converted to metres. The working project and Lua export already use metres: '''do not feed them to the legacy importer'''. Legacy Lua import is not supported. Export legacy JSON rejects pitch/roll, non-uniform scale, hidden/locked objects or disabled collision instead of silently losing those properties.

== Limits and troubleshooting ==
* At most 500 document objects; the native client has a combined 512-instance limit across all owning resources, including previews/deployed scenes. Undo history holds 200 commands.
* Position: +/-100000 metres; rotation: +/-36000 degrees; each scale axis: 0.01-100. Editor upload/download JSON is limited to 1000000 bytes. See [[World objects]] and [[Resource data storage]] for engine limits.
* One user holds a named-map lock until their editor session closes/expires. This prevents simultaneous conflicting saves, not a collaborative editing session.
* <code>Start map_editor in the server console first</code>: check that map_editor is running and the compatible GothicRP bridge is installed.
* Export refuses: save the current name, confirm with the second click and wait for the save response. Do not change the name between Save and Export.
* <code>[!]</code> / failed render: inspect the reported asset failure. The document retains that object's record so another save does not silently lose it. Unknown catalog entries fail validation before the old scene is cleared.
* <code>Native state uncertain</code>: reload the saved map before further editing; blindly retrying a timed-out mutation can create an inconsistent scene.
* A first load of a large mesh can hitch. The catalog is an index, not a guarantee every mesh/material/collision behaves suitably in gameplay.
* Restarting the resource or closing/disconnecting removes the preview and unsaved editor state. Save first. For deployed objects, keep map_scene running.

== Lua developers ==
Use [[WorldObjects.request]] and its two result/reset events for generic resource-owned meshes. [[MapEditor helpers]] documents the four convenience functions inside the editor only. [[Resource data storage]] documents the three new server persistence functions. [[Mouse capture]] includes the new optional exclusive-input mode; [[UpdateCameraPose]] streams the editor's camera.
[[Category:Lua API]]
[[Category:Lua Examples]]

Map editor - Revision history

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

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

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