Skip to main content
A Grounds NPC belongs to a scene, a versioned document stored with a map. The scene describes placement, labels, interactions, and actions. A PackSet delivers the client assets those scenes and the Grounds UI refer to. You publish and activate maps and PackSets through separate workflows. Read Scenes, packs, and PackSets explained for definitions and examples before following the workflows.

Create an NPC

Create, place, label, and configure an NPC on a Paper build server.

Manage resource packs

Inspect PackSets and select a channel or release for Stage in the Portal.

Integrate a scene host

Implement the Minestom renderer and action contracts.

Build and publish assets

Compose contributions and publish immutable PackSet artifacts.

​
Ownership and data flow

​
Follow the right workflow

1

Author and save

Edit the scene in your build world, validate it, and run /scene save. A saved sidecar becomes part of the next map source upload.
2

Derive and publish the map

The map pipeline validates the exact catalog references and emits a canonical scene with the world bundle. Check derive status before moving a map pin.
3

Make the assets available

Build and publish the PackSet that declares the scene assets. A published PackSet does not change the active Config selection by itself.
4

Load and deliver

The lobby loads the selected scene at startup. Velocity resolves the configured PackSet in the background and offers it at login or the next backend connection.
Changing a PackSet selection does not replace a running lobby’s scene or world. Changing a map pin does not select a PackSet. Keep the asset catalog supported by the editor, derivation worker, and scene host compatible with the map you activate.

​
Current implementation scope

The lobby uses explicit renderer factories for the grounds:editor/guide NPC body and grounds:editor/marker prop. It supports authored transforms, labels, private highlights, collision, and the catalog-backed lobby navigator action. The general scene library can describe more capabilities than this host implements; unsupported capabilities fail preflight. Pack delivery is global through Velocity. Per-gamemode overlays and a Minestom delivery adapter are not implemented. The Portal selection endpoint is fixed to Stage, even when the Portal itself is served from its production URL. Start with scene authoring, scene format, map publication, or PackSet architecture.

​
Implementation sources

Verified against the main-branch source on October 14, 2026.