Modules
Shared NPC lifecycle
Requests use
NpcSpawnRequest.builder(instance, model, transform). Optional settings configure
meshes, sound callbacks, publication guards and render policy. toBuilder() creates an
independent builder. The default sound callbacks are silent.
Command failures arrive through their stages. Operational failures use NpcOperationException
and retain their cause. Keep and observe cleanup even if readiness or publication fails.
Animation and units
playClip(id) starts at zero. Shared clips need a host clock. Personal clips use their own
monotonic clock. stopClip() selects rest; stopClipIfPlaying(id) stops only a matching request.
NpcRenderConfig.builder().protectSoundPlayback(true) enables shared audible-gesture
protection. canStartClip(id) is advisory; use reserveClip(id) when a start and a host-clock
reset must be coordinated. Close every returned reservation, including after queueing its start.
A model’s optional NpcClipSound.durationMillis describes effective cue duration; zero means
unknown. Do not infer complete sound duration from a short animation alone.
Per-player state
NpcViewerState supplies scale and highlight. Scale is finite and in (0, 16].
preparePresentation(options) prepares a private copy for a concrete player connection.
Private clip and head-look channels can follow or override shared state independently.
Root movement and viewer scale still follow the parent.
Handles, live entities and player references stay on their owning backend. Reconnects and
cross-proxy/backend transfers require fresh local ownership.
Import options
The CLI acceptsvalidate and compile. Important options are:
Generic Blockbench 5.0 and legacy 4.10 models support cube geometry, bone hierarchy, pivots,
per-face UVs, embedded/relative PNGs and numeric position/rotation/scale animation. Supported
interpolation is
linear, step, catmullrom; loop modes are once, loop, hold.
Use the CLI’s diagnostics for unsupported expressions or source features.
A relative path such as town/merchant.bbmodel becomes my_server:npc/town/merchant.
Use models in your import configuration to override that mapping. Sound bindings name an
existing model and clip, with either a local OGG file or an external event:
import.json
--config models/import.json. Local sound paths and model-mapping paths are
relative to the input directory. Namespace/path conflicts are errors; the compiler does not
silently replace unrelated assets.
Numeric definitions and limits
NpcModelJson.decode(bytes, limits) returns Success or a nonempty Failure.problems list.
Problems contain a code and field path. Manual constructors validate the same model invariants.
Schema 1 permits at most 256 bones, 1024 parts, 128 clips, 4096 keys per channel and 300 seconds
per clip. NpcDecodeLimits can lower these budgets. Parent bones precede their children.
Package names group model, animation, math, I/O and validation types under
gg.grounds.npc.core. Minestom rendering, configuration, transforms, viewer state, callbacks
and presentations live under gg.grounds.npc.minestom. Packages named internal are implementation
details. The matching source checkout’s dokkaGenerate task generates the complete KDoc reference.