Kzeroko KTM2

Villager deployment

Deploy lightweight service villagers through markers or Java.

Updated Oct 25, 2026 4 min read

VillagerAPI deploys a vanilla-derived merchant with a small station controller. It retains existing villager dialogue and trade integration, while omitting village schedules, POI sensors, gossip, raids and breeding AI.

Entry point

Use net.kzeroko.isekaiexpansion.api.VillagerAPI. The returned deployment settings and resident entity are internal implementation types. Entity ID is isekaiexpansion:resident_villager; the authoring block and item are isekaiexpansion:villager_anchor.

Common tasks

Spawn a stationary merchant

var settings = VillagerAPI.deployment()
        .profession(new Identifier("minecraft", "cleric"))
        .appearance(new Identifier("minecraft", "plains"))
        .wander(0).restockEvery(12000).protectedNpc(true).build();
var resident = VillagerAPI.spawn(world, position, settings, 90);

The world must be a server world and position a block position. A null result means invalid registry settings, yaw, unloaded terrain, world bounds, block collision or failed entity insertion. Direct deployments do not require a marker.

Place merchants with a landmark

Obtain the marker with /ise dev npc villagerMarker. A Creative operator can use its editor to choose profession, appearance, wander radius, restock interval, yaw offset and enabled/protected state. New hand-placed markers start disabled. Save the configured marker inside a structure and use processor list isekaiexpansion:villager_anchors; guild receptionist processing also includes it. Placement enables the marker and removes copied resident identity. Block facing rotates with the structure; mirroring negates the yaw offset.

Saved fieldTypeDefaultContract
DeploymentNBT compoundBuilder defaultsThe settings below; when present, profession and appearance must be valid identifiers.
Deployment.Professionidentifier stringminecraft:librarian in builderMust resolve in the villager-profession registry before deployment.
Deployment.Appearanceidentifier stringminecraft:plains in builderMust resolve in the villager-type registry.
Deployment.WanderRadiusinteger00–32 blocks; zero returns to the station.
Deployment.RestockTicksinteger120000–1000000 ticks; zero disables automatic restock.
Deployment.Protectedbooleantrue in builderInvulnerability and collision-push protection.
YawOffsetfloat0Finite degrees, wrapped relative to block facing; invalid saved values become zero.
EnabledbooleanfalseEnables deployment and ownership reconciliation.
ResidentUUIDAbsentRuntime-owned entity identity; do not author manually.
Originpacked block-position longCurrent position on saveDetects copied markers and clears their resident identity.
DimensionstringEmptyRuntime-owned dimension guard.

NBT numeric/boolean fields absent inside an explicitly supplied Deployment compound read as zero/false. Use the builder or editor to produce a complete compound. Invalid identifier syntax and numeric bounds reject settings; unknown registry IDs prevent deployment.

Reference

MethodSideContract
VillagerAPI.deployment()CommonCreates settings builder.
profession, appearanceBuilderRegistry IDs; registry membership checked before spawn.
wander, restockEvery, protectedNpcBuilderBounds and behaviour listed above.
VillagerAPI.spawn(world, pos, settings, yaw)Server threadSpawns and configures a resident, or returns null.

Threading and lifecycle

Spawn and marker edits belong on the server thread. Markers check for deployment every 40 ticks, staggered by position. A saved UUID reserves its slot through chunk unloading; an unloaded entity never causes a duplicate spawn. Destructive removal releases the slot. A loaded resident reconciles marker ownership every 20 ticks and is discarded if its marker is gone or disabled.

Residents retain vanilla merchant data at profession level 5. Changing profession resets offers. Dialogue or trading stops navigation and postpones restocking; movement destinations are chosen every 40–79 ticks and only inside loaded terrain. There is no brain sensor/task loop. Ordinary navigation and look controls still run. Lightning conversion, breeding, item gathering and dimension transfer are disabled.

Idle residents keep looking at a visible player within 6 blocks. Target searches and visibility checks run every 10 ticks (0.5 seconds), while the active gaze refreshes every tick independently of movement planning. Dead, spectator, distant or departed targets are released; dialogue and trade partners take priority.

Native landmark/editor fresh placement now uses the same activation policy as VillagerAnchorProcessor: enable the post and remove source Resident, Origin and Dimension. Profession, appearance, restocking, protection, wandering radius and yaw are preserved. The immutable outpost capture contains 17 disabled posts; runtime tests pass every one through real proto-chunk placement and compare the ordinary processor output. This is a placement initialization rule, not a chunk-load respawn rule.