Kzeroko KTM2

Unique NPC deployment

Place named characters and apply live placement edits without replacing their own logic.

Updated Oct 29, 2026 10 min read

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 fieldTypeDefaultContract
DeploymentcompoundEditor defaultsMissing or malformed saved settings disable deployment. Unknown extra keys are ignored.
Deployment.Characteridentifierisekaiexpansion:mahoutsukai_evelina in editorRequired in NBT; one of the two supported character IDs.
Deployment.Outfitstringdefault in editorRequired, nonblank, at most 64 characters; must resolve in that character’s wardrobe before spawning or editing.
Deployment.ModestringWANDER_BY_RADIUS in editorRequired: STAY, WANDER, WANDER_BY_RADIUS; FOLLOW is rejected. Wander radius remains the character’s config.
Deployment.HomestringNEAREST_BED in editorRequired: NEAREST_BED, ANCHOR, NONE. Bed search uses 16 blocks; no free bed leaves home unset.
Deployment.IdleFacingbooleanfalse in editorRequired in NBT; enables preferred facing during idle STAY only.
Deployment.IdleYawRangefloat30 in editorRequired, finite 0–180 degrees on each side of the centre. Zero fixes the preferred heading; out-of-range or nonfinite values reject settings.
Deployment.EncounteridentifierAbsentOptional personal story encounter ID; invalid identifier rejects settings. An absent value leaves ordinary dialogue routing.
Deployment.CityBindingcompoundAbsentOptional residence and duty reference; malformed compound rejects settings.
Deployment.CityBinding.CityidentifierRequired when presentCity ID, resolved by the existing city runtime.
Deployment.CityBinding.ResidencestringRequired when presentLowercased local ID, 1–96 characters; letters, digits, underscore, hyphen, dot and slash.
Deployment.CityBinding.RoutestringAbsentOptional local ID with the same rules; blank becomes absent.
YawOffsetfloat0Finite degrees relative to block facing, wrapped; nonfinite saved value becomes zero.
EnabledbooleanfalseEnables initial deployment retries; disabling cancels and removes the bound NPC.
DeployedbooleanfalseRuntime success receipt; retained after death and unloading.
BindingUUIDFresh tokenRuntime link to the bound NPC, independent of its current entity UUID; replaced on cancellation.
OriginlongCurrent packed position on saveA copied position resets the receipt and binding.
DimensionstringEmptyA 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 keyTypeDefaultMeaning
DeploymentBindingcompoundAbsentOpt-in entity binding, also saved in revival snapshots.
DeploymentBinding.TokenUUIDRequired when boundMust be in the active-token ledger when the entity loads.
DeploymentBinding.YawfloatRequired when boundFinite absolute world yaw in degrees, wrapped.
DeploymentBinding.IdleFacingbooleanRequired when boundWhether the idle gaze is enabled.
DeploymentBinding.YawRangefloatRequired when boundFinite 0–180 degrees per side.
DeploymentBinding.DutyAnchorcompoundRequired when boundSaved deployment world and position; invalid codec data rejects the binding.
DeploymentBinding.DutyAnchor.dimensionidentifierRequiredWorld registry key.
DeploymentBinding.DutyAnchor.posint arrayRequiredExactly 3 block coordinates: X, Y, Z.
DeploymentBinding.DutyModestringRequired when boundSTAY, WANDER or WANDER_BY_RADIUS; other values reject the binding.
DeploymentBinding.AssignedHomecompoundAbsentHome assigned at deployment; equality with current home permits duty return. Same dimension and pos fields as DutyAnchor; malformed data rejects the binding.
Activelist<compound>EmptyWorld ledger of active deployments.
Active[].TokenUUIDRequired per entryEntries 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.