gg.grounds:plugin-scene-editor-common and gg.grounds:plugin-scene-editor-paper. common is Bukkit-free; paper adapts BuildSystem worlds, player input, scheduling, preview entities, and permission checks. Do not build a runtime host against the Paper editor API.
Command reference
kind below is prop or npc. Element IDs are local lowercase IDs. Parameters in angle brackets are values you supply, not literal command text.
Trigger command values are case-insensitive names of the six SceneTrigger variants. Numeric arguments must be finite. The command UI supports props and NPCs; the format’s composite model and all general-purpose binding parameters are not exposed as additional commands.
The action command installs an unconditioned, zero-cooldown/zero-debounce application binding for the selected trigger. It replaces existing simple bindings of that shape and preserves more complex bindings. It does not add a main-hand condition or hover highlights automatically; use the typed scene model for those bindings.
Permission mapping
grounds.scene defaults to operator and grants edit, save, recovery, catalog status, and lease override as children. Save/recovery/override are distinct from an edit-only grant. Consult the existing in-game permission system when assigning these capabilities.
Common session API
ConstructEditorSessionService(catalogs, clock, eventErrorHandler) with the host’s SceneCatalogBinding. The service serializes state transitions and exposes immutable snapshots.
SceneMutations creates typed operations; mutate returns MutationOutcome with an accepted flag and structured rejection where applicable. Failed operations do not install a partial document. Event listener failures are passed to the configured error handler.
Implementations integrating map uploads should depend on SceneEditStatus, whose single method is hasUnsavedChanges(worldId: UUID): Boolean. They do not need to read editor internals or capture the preview entities.
Persistence API
WorldSceneRepository(root) owns only the root sidecar and returns structured SceneLoadResult / SceneSaveResult. SceneFingerprint.Absent represents a truly absent base; a loaded file carries its exact fingerprint. Save uses canonical bytes, a compare-before-replace check, and the atomic file-store boundary. A conflict is not permission to retry an overwrite.
Session reload uses a prepared snapshot so an edit accepted during asynchronous I/O cannot be discarded by a stale reload completion. Paper performs file work asynchronously and installs results on its main thread. Save/reload reservations prevent overlapping state changes from pretending to have persisted newer edits.
For adapter implementations, inspect the linked source signatures for the complete structured result variants; handle all variants explicitly rather than treating every nonexceptional return as success.