plugin-scene-editor in a Paper BuildSystem world. The plugin resolves the current build-world root through BuildSystem, edits a shared in-memory document, and saves scene.json at that root. Ordinary worlds and console callers are not scene-authoring targets.
Prerequisites
- A build-server image containing BuildSystem and the Paper scene editor.
- Permission to enter and edit the build world.
grounds.scene.editfor editing andgrounds.scene.savefor saving./scenehelp usesgrounds.scene; the permission catalog also allows individual command grants.- Catalogs available to the installed editor. Check
/scene catalogs status.
resourcepacks-catalog:1.0.0. New scenes use action catalog grounds:actions revision 2; existing scenes keep their serialized supported revision. Maven artifact versions and action catalog revisions are separate.
Create a navigator NPC
Choose a clear location in the build world. Creation uses your current position and yaw.1
Create or open the scene
For a world without a sidecar:In a world with an existing valid sidecar,
/scene info opens it lazily. Do not create a second scene.2
Create and label the NPC
3
Place and configure
none for a non-colliding NPC or solid to block movement without bouncing.4
Validate and save
Use the transform tool
Run/scene tool give to receive the tagged blaze rod named Scene Editor Tool. An ordinary renamed blaze rod does not count as the tool.
Components cycle through X, Y, Z, yaw, pitch, roll, and uniform scale. The action bar shows element ID, value, step, dirty state, and remaining lease time.
Tool edits and command edits use the same mutation pipeline. Preview entities are editor-owned and are not serialized into the map as NPC entities; the authoritative data is the sidecar.
Work with other builders
Selections use per-element leases. When another builder owns an element, selection/editing is refused rather than silently overwriting their work. Different elements can be edited in the shared world session.grounds.scene.lease.override can use /scene lease override navigator to take over and select it. Do not use override merely to bypass another builder’s active edit.
History belongs to the shared world session. /scene history, /scene undo, and /scene redo inspect or move that history; undo/redo also accept a step count. They are not private per-player histories.
Recover safely
Unsaved edits block reload or a map push
Unsaved edits block reload or a map push
Save first with
/scene save. /scene reload reloads a clean session. To explicitly discard edits, use /scene recovery discard-and-reload confirm; the literal confirm is required. When the scene editor is enabled and its status service reports unsaved changes, BuildSystem blocks the map push before scheduling archive/upload work. It queries SceneEditStatus.hasUnsavedChanges(worldId); an inspection exception also blocks the push.The sidecar is malformed
The sidecar is malformed
The editor keeps invalid bytes unchanged. Use
/scene recovery export for an open-session diagnostic export. When an invalid source is awaiting recovery, /scene recovery backup-and-create grounds:lobby/main Main lobby backs up those exact bytes and creates a replacement. Keep the generated backup for review.Save reports that the file changed
Save reports that the file changed
The save compares the loaded file fingerprint with the current file before replacement. Inspect external changes, export your work if needed, then reload or reconcile. Retrying without reconciliation must not overwrite another writer’s changes.