Unique NPC deployment
Place named characters and apply live placement edits without replacing their own logic.
The unique NPC marker deploys a character once and applies explicit placement edits through existing NPC setters. The implementation is internal: UniqueNpcDeployment, UniqueNpcDeploymentIndex and UniqueNpcAnchorBlockEntity do not define a public facade.
What it does
Use /ise dev npc uniqueMarker to obtain isekaiexpansion:unique_npc_anchor. A Creative level-two operator can open its editor. Choose isekaiexpansion:mahoutsukai_evelina or isekaiexpansion:goddess_selene, an existing outfit, default behaviour, home policy, optional city residence and duty route, facing offset and optional idle facing. New markers start disabled. The developer marker shows an arrow along block facing plus offset, with an arc for the enabled idle look range; saved edits synchronise this geometry to clients.
The entity class still supplies its preset, gender, appearance foundation, combat configuration, personality, dialogue and relationships. The editor does not accept arbitrary entity NBT or replacement presets. Normal spawns do not acquire a marker binding.
Runtime model
Enabled markers without a successful deployment retry every 40 ticks (2 seconds), staggered by position. Spawning uses NpcSpawningUtil: create, initialize, configure, assign home and behaviour, then insert into the world. Unknown outfits, unloaded chunks, world bounds, block collisions and failed insertion prevent deployment.
The marker stores a successful-deployment flag and a binding token. UniqueNpcDeploymentBinding carries that token, duty position, duty mode, original assigned home and idle facing in entity NBT and revival snapshots. UniqueNpcDeploymentState stores active tokens in data/isekaiexpansion/npc/deployments_v1.dat; revoked tokens are removed. ServerEntityEvents maintains a lookup only for bound unique NPCs and discards a cancelled entity when it loads. Unload and server stop clear references. A revived entity can have a new UUID and still receive live edits through its token. Multiple loaded entities with the same token make live lookup fail instead of choosing one.
Marker ticks refresh duty settings and gaze metadata without moving an existing character or overwriting a reassigned home. Unloading and death retain the slot while the marker remains enabled, and death uses normal revival. Disabling or breaking the marker revokes its token, discards every loaded bound NPC across dimensions and removes that deployment’s pending grave. Unloaded entities are discarded on their next load, even after a restart or while the marker chunk is unloaded. Cancellation does not run death drops or create a grave. Re-enabling starts a fresh slot and NPC; an old saved entity cannot claim it. Separate markers remain independent.
NpcStayTask supplies idle facing only after its ordinary look search finds no target and no other LOOK_TARGET memory remains. Its existing movement guards exclude dialogue, emotes, rest, combat and modes other than STAY; the gaze controller also yields during navigation, motion, riding and flight. It samples a heading inside the configured range every 40–100 ticks (2–5 seconds), turning gradually through the existing look and movement controls. A visible nearby player or NPC takes priority. Ordinary spawns keep their existing behaviour. The entity stores UniqueNpcIdleLook.Facing separately from marker ownership: binding changes derive that preference, while session-owned story actors can set it directly without registering a deployment token. tickIdleLook uses the same controller for both paths.
Contracts
Saving edits requires Creative operator permission, a loaded editable block inside the world border, and distance at most 8 blocks. Live edits to an enabled deployment require its bound NPC to be alive and loaded in the same dimension. Disabling does not require the NPC to be loaded. Character type stays fixed while a deployment is active; disable it before choosing a different character. Invalid requests leave the marker settings unchanged.
Only changed fields are applied. Editing a city reference does not restore the original outfit or home. Changing behaviour updates the default and, without an active follower assignment, the current mode and marker stay anchor. Active FOLLOW and waiting STAY assignments retain ownership, position and their captured return mode. Facing edits update the idle preference without snapping the current rotation or interrupting FOLLOW. Live edits do not teleport the character, stop its brain, reset emotion, alter inventory or change marriage/favor state.
| Saved field | Type | Default | Contract |
|---|---|---|---|
Deployment | compound | Editor defaults | Missing or malformed saved settings disable deployment. Unknown extra keys are ignored. |
Deployment.Character | identifier | isekaiexpansion:mahoutsukai_evelina in editor | Required in NBT; one of the two supported character IDs. |
Deployment.Outfit | string | default in editor | Required, nonblank, at most 64 characters; must resolve in that character’s wardrobe before spawning or editing. |
Deployment.Mode | string | WANDER_BY_RADIUS in editor | Required: STAY, WANDER, WANDER_BY_RADIUS; FOLLOW is rejected. Wander radius remains the character’s config. |
Deployment.Home | string | NEAREST_BED in editor | Required: NEAREST_BED, ANCHOR, NONE. Bed search uses 16 blocks; no free bed leaves home unset. |
Deployment.IdleFacing | boolean | false in editor | Required in NBT; enables preferred facing during idle STAY only. |
Deployment.IdleYawRange | float | 30 in editor | Required, finite 0–180 degrees on each side of the centre. Zero fixes the preferred heading; out-of-range or nonfinite values reject settings. |
Deployment.Encounter | identifier | Absent | Optional personal story encounter ID; invalid identifier rejects settings. An absent value leaves ordinary dialogue routing. |
Deployment.CityBinding | compound | Absent | Optional residence and duty reference; malformed compound rejects settings. |
Deployment.CityBinding.City | identifier | Required when present | City ID, resolved by the existing city runtime. |
Deployment.CityBinding.Residence | string | Required when present | Lowercased local ID, 1–96 characters; letters, digits, underscore, hyphen, dot and slash. |
Deployment.CityBinding.Route | string | Absent | Optional local ID with the same rules; blank becomes absent. |
YawOffset | float | 0 | Finite degrees relative to block facing, wrapped; nonfinite saved value becomes zero. |
Enabled | boolean | false | Enables initial deployment retries; disabling cancels and removes the bound NPC. |
Deployed | boolean | false | Runtime success receipt; retained after death and unloading. |
Binding | UUID | Fresh token | Runtime link to the bound NPC, independent of its current entity UUID; replaced on cancellation. |
Origin | long | Current packed position on save | A copied position resets the receipt and binding. |
Dimension | string | Empty | A changed dimension resets the receipt and binding. |
Save markers in structures with processor list isekaiexpansion:unique_npc_anchors. Its isekaiexpansion:unique_npc_anchor_processor enables them, removes copied runtime identity and negates the yaw offset for mirrored placement. Block facing handles rotation. Do not include the already deployed NPC in the saved structure.
Entity and world-state fields below are runtime save data, not authoring settings. Missing or malformed entity binding fields produce no binding. The deployment settings require the current fields; no legacy command-tag reader or migration path is provided.
| NBT key | Type | Default | Meaning |
|---|---|---|---|
DeploymentBinding | compound | Absent | Opt-in entity binding, also saved in revival snapshots. |
DeploymentBinding.Token | UUID | Required when bound | Must be in the active-token ledger when the entity loads. |
DeploymentBinding.Yaw | float | Required when bound | Finite absolute world yaw in degrees, wrapped. |
DeploymentBinding.IdleFacing | boolean | Required when bound | Whether the idle gaze is enabled. |
DeploymentBinding.YawRange | float | Required when bound | Finite 0–180 degrees per side. |
DeploymentBinding.DutyAnchor | compound | Required when bound | Saved deployment world and position; invalid codec data rejects the binding. |
DeploymentBinding.DutyAnchor.dimension | identifier | Required | World registry key. |
DeploymentBinding.DutyAnchor.pos | int array | Required | Exactly 3 block coordinates: X, Y, Z. |
DeploymentBinding.DutyMode | string | Required when bound | STAY, WANDER or WANDER_BY_RADIUS; other values reject the binding. |
DeploymentBinding.AssignedHome | compound | Absent | Home assigned at deployment; equality with current home permits duty return. Same dimension and pos fields as DutyAnchor; malformed data rejects the binding. |
Active | list<compound> | Empty | World ledger of active deployments. |
Active[].Token | UUID | Required per entry | Entries without a UUID are ignored; duplicates collapse to one token. |
Extending it
UniqueNpcDeployment.CHARACTERS is the explicit character catalog. Add a concrete UniqueNpcEntity type there to offer it in the editor. Presets and NpcConfig remain in the character class.
var settings = new UniqueNpcDeployment(characterId, "default",
BaseNpcEntity.NpcMode.WANDER_BY_RADIUS,
UniqueNpcDeployment.Home.NEAREST_BED, null, false, 30, null);
var spawned = settings.spawn(world, position, 90);
Call on the server thread. Direct use does not bind a marker or enable deployment gaze. The overload taking a configuration consumer runs that hook before insertion; the marker uses it to attach the typed binding after reserving its active token. Failed insertion releases the token. NpcSpawningUtil.SpawnBuilder.outfit(id) is also opt-in and rejects unknown outfits; builders that omit it retain their existing flow.
Residents retain deployment identity while following. Wander returns them to the saved duty position and exact mode, including deployments with no home. A home changed after deployment takes precedence; return resolves the latest destination again while waiting for chunk loading. Binding saves require DutyAnchor and DutyMode; missing fields are rejected without a compatibility reader or migration. See NPC followers.
Verifying
Compile with ./gradlew.bat compileJava. Run ./gradlew.bat -I tools/npc/verify.gradle checkDeployment for binding validation, save/reload and cancellation persistence checks. In game, deploy each character, edit one field while preserving the others, unload/reload the NPC, restart the server and test death followed by revival. Confirm no replacement appears during absence while enabled. Disable and break markers with loaded, unloaded, cross-dimension and dead NPCs; cancelled entities and graves must not return after re-enabling.
Check arrow and arc orientation for each placement direction, yaw offset, rotation and mirror. Enable idle facing in STAY, test zero and maximum range, then introduce and remove a visible player or NPC. Test FOLLOW, wandering, dialogue, combat, rest and emotes; none may be overridden by idle gaze. Repeat with an ordinary spawn: it must have no deployment binding or marker-driven changes.
Personal story encounters
Deployment.Encounter is an optional identifier, absent by default. Malformed values reject settings. The editor exposes it as a separate field. On spawn or an edited assignment, it writes the isekai_story: entity tag with that identifier; changing the assignment removes the previous tag. Ordinary entity saving and revival retain it. Deployment identity, location and idle gaze stay separate from personal story facts.
internal.story.npc.NpcStoryResources loads NPC story encounter data. NpcStoryEncounters runs after the opening/mainstory routes and before ordinary introductions or menus. It stores the exact Blabber session and actor UUID. Only a natural close at an authored terminal state, with unchanged selection and valid requirements, records the IsekaiCore milestone. Forced closure, distance over 12 blocks, actor loss and reload do not award progress. Completion is personal; team membership and another player’s conversation do not complete it.
UniqueNpcAnchorProcessor and native fresh placement share DeploymentAnchorNbt.fresh. A new placement enables the anchor and clears Deployed, Binding, Origin and Dimension; it retains Deployment, including the optional encounter and idle-gaze settings. Loading an existing saved post does not run this initializer, so an unloaded actor still reserves its original slot.
Unique-NPC markers initialise their characters through the authored NPC builder with SpawnReason.EVENT. This keeps an enabled Evelina or Selene deployment eligible inside protected garden and landmark bounds. The marker still validates its settings, wardrobe, chunk, border, height and block collision; Enabled alone is not a successful deployment. Failed insertion does not consume the slot and the existing server ticker retries.