Villager deployment
Deploy lightweight service villagers through markers or Java.
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 field | Type | Default | Contract |
|---|---|---|---|
Deployment | NBT compound | Builder defaults | The settings below; when present, profession and appearance must be valid identifiers. |
Deployment.Profession | identifier string | minecraft:librarian in builder | Must resolve in the villager-profession registry before deployment. |
Deployment.Appearance | identifier string | minecraft:plains in builder | Must resolve in the villager-type registry. |
Deployment.WanderRadius | integer | 0 | 0–32 blocks; zero returns to the station. |
Deployment.RestockTicks | integer | 12000 | 0–1000000 ticks; zero disables automatic restock. |
Deployment.Protected | boolean | true in builder | Invulnerability and collision-push protection. |
YawOffset | float | 0 | Finite degrees, wrapped relative to block facing; invalid saved values become zero. |
Enabled | boolean | false | Enables deployment and ownership reconciliation. |
Resident | UUID | Absent | Runtime-owned entity identity; do not author manually. |
Origin | packed block-position long | Current position on save | Detects copied markers and clears their resident identity. |
Dimension | string | Empty | Runtime-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
| Method | Side | Contract |
|---|---|---|
VillagerAPI.deployment() | Common | Creates settings builder. |
profession, appearance | Builder | Registry IDs; registry membership checked before spawn. |
wander, restockEvery, protectedNpc | Builder | Bounds and behaviour listed above. |
VillagerAPI.spawn(world, pos, settings, yaw) | Server thread | Spawns 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.