Village Defenders

Village Defenders is a Fabric project that allows ordinary villagers to respond to danger as a coordinated settlement. Instead of making every villager permanently aggressive, it evaluates each incident and activates temporary defensive responsibilities when they are needed.

A small, manageable group of hostile mobs may only alert nearby defenders. Larger groups, active raids, overwhelming threats or a player attacking a villager can mobilize the settlement, move civilians toward safety, coordinate with iron golems and eventually begin an organized recovery.

The goal is to preserve the familiar Minecraft village experience while making emergencies more visible, structured and believable.

Dynamic Village Defense

Each settlement moves through a staged defense system:

Normal: Villagers continue ordinary village life. Monitoring runs at a lower frequency, and a limited morning Armorer patrol may visit a registered Guard Post.
Local Alert: A possible or limited threat has been detected. Nearby villagers become alert without immediately disrupting the entire settlement.
Local Skirmish: Eligible defenders handle a threat that the village’s current defensive capacity considers manageable.
Full Defence: The settlement mobilizes defenders, activates civilian and child protection, coordinates iron golems and uses registered defensive infrastructure.
Withdrawal: If the threat substantially exceeds available defensive capacity, villagers stop unsafe pursuit and regroup near shelter or golem support.
Recovery: After danger has remained clear for a configurable cooldown, the village attempts equipment return, approved repairs, cleanup and restoration of normal routines.

Escalation is contextual. Threat size, proximity, health, equipment, eligible defenders, children at risk, nearby golems, raids and player aggression all affect the response. A nearby zombie does not automatically turn the entire village into an army.

The decision model also contains a failed-containment escalation signal for compatibility extensions. The current built-in runtime primarily escalates through raid status, confirmed attacks, and threat-versus-capacity scoring.

Threat Detection and Escalation

Village Defenders responds to several verified threat sources:

direct attacks against villagers;
active raids;
raid participants that damage villagers;
nearby vanilla hostile mobs and raiders;
larger hostile groups whose combined score exceeds village capacity;
compatible entities added to the defensivemod:aggressors tag;
high-threat entities identified through a separate data tag;
local distress events submitted through the Villager Identity compatibility API;
changes in available defender health, equipment, and golem support;
players who directly attack villagers.

The included aggressor data covers common threats such as zombies, skeletons, witches, pillagers, vindicators, evokers, ravagers and vexes. Datapacks can extend the aggressor, high-threat, ignored and allied entity tags.

Player aggression

A player who attacks a villager is treated as an extreme threat and can immediately force the affected settlement into full defence.

Hostility is attached to the exact attacking player UUID. Peaceful players standing nearby are not automatically copied into the hostile-player set. Hostility expires after a configurable cooldown once the encounter is no longer nearby.

Profession-Based Defenders

Village Defenders uses existing professions and does not add a permanent Guard profession.

The default mappings are:

Armorer — Protector: Prioritizes shields, defensive weapons, Guard Posts, entrances and protected positions.
Weaponsmith — Melee Defender: Engages assigned aggressors with available tagged weapons.
Cleric — Support: Remains near front-line defenders and can consume real support supplies to assist a wounded defender.

Only living adult villagers above the configured health threshold are eligible. Children never receive combat roles. Combat assignments are temporary and do not replace professions, trades or workstations.

Role mappings are configurable. Additional professions can be assigned implemented roles such as ranged or reserve defense, but they are not enabled by default.

Defensive Equipment

The Armory Rack provides a physical 27-slot inventory for village defense equipment.

During an emergency, eligible villagers can borrow:

tagged swords, axes, or tridents;
shields;
bows or crossbows for configured ranged roles.

Each borrowed stack is physically removed from the rack and receives a unique reservation identifier. The rack records the villager, original slot, item, and borrowing time. Only the matching physical stack can complete that return.

During recovery, villagers attempt to return borrowed items. Missing or lost equipment is recorded rather than recreated. Breaking an Armory Rack drops its remaining inventory but does not duplicate equipment currently held elsewhere.

Ranged defenders consume tagged arrows when physical ammunition is enabled. Cleric support actions similarly consume real tagged supplies such as bread, potions, splash potions, or golden apples. Village Defenders does not create unlimited ammunition, healing supplies, weapons, or armor.

No custom weapon or armor tiers are included.

Civilian Safety and Shelter

Villagers without defensive assignments seek safety during a local skirmish or full village defense.

The current shelter order is:

an owned home supplied by Villager Identity;
the nearest registered Shelter Marker with available capacity and no obvious aggressor conflict;
the villager’s vanilla home memory or assigned bed;
the settlement anchor as an emergency fallback.

Shelter Marker capacity is configurable. The settlement tracks occupancy during each shelter assignment pass so one marker is not assigned beyond its configured capacity.

A route-safety check rejects destinations where a nearby aggressor appears to stand between the villager and the destination. Final movement is performed through an optional Villager AI adapter or vanilla navigation fallback, so complex terrain can still affect practical route success.

Guardian and Child Protection

Children are always civilians and never receive weapons or defender roles.

During an emergency, a child attempts to find protection in this order:

a known guardian supplied by Villager Identity;
a trusted adult supplied by Villager Identity;
the nearest available adult who is not assigned as a defender;
a valid shelter when no adult fallback is available.

When an adult is selected, the child moves toward that adult while the adult guides the pair toward a shared shelter destination. Guardian and escort poses make the emergency response visible, but the project does not implement literal synchronized hand-holding.

Without Villager Identity, nearby adult and shelter fallbacks remain available.

Iron Golem Coordination

Iron golems remain a central part of village defense rather than being replaced.

Nearby living golems contribute to the settlement’s estimated defensive capacity and can receive the nearest confirmed aggressor as a target. During withdrawal, villagers prefer to regroup near an available nearby golem; if no golem is available, they withdraw toward shelter or the settlement fallback position.

Current runtime golem selection is proximity-based. It does not guarantee that every nearby golem can cross complex terrain, so vanilla navigation and optional Villager AI route handling still matter.

Defensive Village Blocks and Tools

Village Defenders adds four craftable, localized pieces of player-facing content.

Guard Post

A Guard Post registers a defensive position within its settlement.

Protectors can hold near the nearest post rather than chasing an aggressor away from the position. During normal village life, a small configurable number of awake adult Armorers may perform a limited morning patrol to registered Guard Posts.

Using the block displays its infrastructure type, settlement state, and settlement identifier.

Shelter Marker

A Shelter Marker registers an emergency destination for civilians, guardians, and children.

Each marker uses the configured shelter capacity and is considered alongside owned and vanilla homes. Using it displays the associated settlement information.

Armory Rack

The Armory Rack is a 27-slot container for defensive weapons, shields, ranged equipment, ammunition, support supplies, and repair materials.

It manages physical equipment loans and persists both inventory and active loan records across saves.

Defense Ledger

The Defense Ledger opens a read-only settlement summary for the nearest settlement.

It displays:

current state and transition reason;
active aggressor and hostile-player counts;
assigned defender count;
registered Guard Posts, Shelter Markers, and Armory Racks;
nearby golem count;
unresolved repairs;
settlement scan and path-request statistics.

If the client cannot receive the custom ledger payload, a reduced chat summary is used instead.

Patrols and Guard Positions

Registered Guard Posts influence protector positioning during active defense.

A limited normal-state patrol also exists for Armorers during the beginning of the Minecraft day. Patrol size is configurable and defaults to no more than two villagers per settlement. Children and sleeping villagers are excluded.

This is intentionally a small defensive routine, not a permanent armed patrol army, military formation system, or replacement for ordinary village schedules.

Danger Memory and Recovery

Direct attacks and compatible local distress events create bounded danger records containing the aggressor, type, approximate position, incident time, severity, victim count, and outcome reason.

Danger memory is:

stored per settlement;
persisted across saves;
limited to 64 entries by default;
expired after 6,000 ticks by default.

The current danger records provide durable incident history but are not yet fed back into future threat scoring as permanent danger zones.

After threats disappear, villagers do not instantly return to normal. A configurable all-clear cooldown must pass before recovery begins. Recovery attempts to:

stop temporary combat targeting;
return borrowed equipment;
mark long-missing equipment as lost rather than duplicating it;
process approved repair records;
clear temporary defensive assignments;
return the settlement to normal behavior.

Approved repairs

Village Defenders does not let villagers freely construct buildings or fortifications.

During active danger, changes to approved tagged blocks can be recorded for later restoration. Recovery repair only proceeds when:

repair is enabled;
the mobGriefing game rule permits it;
the original block type is in the repairable-block tag;
the block was not recorded as a player-initiated break;
the target still matches the observed damaged state;
the required replacement item exists in an Armory Rack.

Toolsmiths are preferred for repair work, with another living adult used as a fallback. Repair work is bounded, and a target changed by a player or another project is aborted rather than overwritten.

This system restores approved damage; it does not redesign villages or build new defenses.

Animations, Sounds, and Presentation

Village Defenders includes a synchronized defensive-pose system.

During active poses, the client replaces the usual combined villager arms with independent left and right arms and renders the villager’s actual held items. Implemented presentation covers situations such as:

alert and guard stances;
shield-ready and melee-ready poses;
melee attacks;
bow and crossbow aiming or firing;
ranged repositioning and retreat;
child danger and guardian escort;
shelter entry;
withdrawal and golem regrouping;
support actions;
equipment return;
damage inspection and repair.

Animations have server-selected priorities and durations, while rendering remains client-side. Distant villagers use reduced motion.

State changes use restrained vanilla sounds and particles, including villager reactions, a bell-like full-defense cue, angry-villager alarm particles, support hearts, and happy-villager all-clear particles. Because these are vanilla sound events, their existing subtitles remain available. No custom sound files are currently included.

The independent-arm renderer currently uses the villager base texture. Profession-clothing coverage on those custom arms still requires final visual approval.

Configuration

Village Defenders creates:

config/defensivemod.json

The configuration is server-owned, validated, and reloadable with an operator command. Unsafe or malformed configuration falls back to safe defaults with a warning. Valid reloads retune existing settlements while preserving their current state and still-valid memory.

Important configurable areas include:

local-alert and full-defense thresholds;
player and raid threat values;
child-risk contribution;
defender health and withdrawal thresholds;
golem capacity;
all-clear cooldown;
danger-memory lifetime and size;
settlement, guardian, and golem search radii;
pursuit boundaries;
normal and active scan intervals;
settlement and entity processing budgets;
hostile-player cooldown;
Shelter Marker capacity;
patrol limits;
profession-to-role mappings;
ranged distances, cooldown, and physical ammunition;
support cooldown and healing amount;
approved repair enablement;
Identity, Villager AI, and Villager Types integration switches;
vanilla navigation fallback.

Entity, item, and repair eligibility can also be extended through datapack tags.

A debugLogging field exists in the current configuration but is reserved and does not yet act as a complete logging-control system.

Commands and Debugging

The following commands are registered under /defensivemod.

Player-readable diagnostics:

/defensivemod status
/defensivemod aggressors
/defensivemod assignments
/defensivemod performance

These report the nearest settlement’s state, transition reason, active aggressors, hostile players, temporary role assignments, scan count, classified-entity count, and path requests.

Operator commands requiring permission level 2:

/defensivemod validate
/defensivemod reload
/defensivemod force_full
/defensivemod clear

validate reports registered infrastructure and hostile-player records. reload validates and reapplies configuration. force_full and clear provide explicit administrative state controls.

There are currently no dedicated commands for simulating alarms, inspecting individual equipment reservations, or listing shelters separately.

Compatibility

Companion projects are optional and listed as suggestions rather than required dependencies. Village Defenders uses an explicit versioned adapter API and does not attempt to load guessed companion classes reflectively.

Installing a companion project alone is not enough unless that project registers the corresponding Village Defenders adapter.

Villager AI

Villager AI owns general navigation reliability, panic-safe movement, stuck recovery, and route correction.

A registered navigation adapter can receive defensive movement requests for:

engagement and ranged positioning;
Guard Post defense;
guardian and child movement;
shelter entry;
golem regrouping;
withdrawal;
patrols;
Armory Rack and repair destinations;
return to routine.

The adapter reports whether a route was accepted, completed, failed, unreachable, or not handled. When configured, failed or unhandled requests fall back to vanilla navigation.

Village Defenders does not take ownership of general navigation recovery outside defensive situations.

Villager Identity

Villager Identity owns personality, personal trust, dialogue, gifts, homes, family relationships, guardian relationships, and local social context.

Through a registered Identity adapter, Village Defenders can currently consume:

local distress signals;
a known guardian for a child;
trusted-adult fallback identifiers;
an owned home position;
defense lifecycle callbacks.

Village Defenders does not currently read arbitrary player-trust scores through this adapter. Villager Identity may determine relationships and raise a local alarm, but Village Defenders decides whether that incident becomes a local response, full defence, or withdrawal.

Villager Identity does not make villagers attack.

Villager Types

Villager Types owns custom villager types, homeland or culture metadata and biome-themed village generation.

The compatibility API can expose villager type and culture identifiers, but the current first-beta behavior does not use them to create biome-specific armies, formations, or tactics.

Village Defenders does not generate custom villages or own cultural identity.

Standalone Operation

Village Defenders works without companion adapters.

Standalone fallbacks include:

vanilla villager home memories;
registered Shelter Markers;
nearby adult guardian fallback;
vanilla navigation;
vanilla professions and entity classifications.

Missing companion projects do not prevent startup.

Multiplayer and Server Support

Defense decisions, persistent settlement state, equipment loans, hostile-player records, repairs and commands are controlled by the logical server.

Clients receive read-only ledger snapshots and temporary animation payloads. There are no client packets that can assign roles, mark aggressors, create equipment, repair blocks or force state transitions.

Settlement state is persisted separately per dimension and supports multiple settlement records. Animation state is sent to players tracking the relevant villager and is periodically resent while the villager is being processed.

The code separates client rendering from common server behavior and is structured for multiplayer and dedicated-server use. However, the current development documentation still requires manual dedicated-server, two-client synchronization, and late-join acceptance testing before release sign-off.

Performance

Village Defenders is designed around settlement-level work rather than giving every villager an independent wide hostile scan.

The current implementation includes:

one shared bounded scan per processed settlement;
a default limit of four settlements per world tick;
a default limit of 64 classified entities per settlement scan;
80-tick normal scans and 10-tick active scans;
raid settlements prioritized ahead of ordinary settlements;
loaded-entity queries without intentional chunk force-loading;
bounded danger memory and transition history;
staggered repeated combat path requests;
target distribution to reduce unnecessary stacking;
limited patrol and repair work;
event deduplication for repeated attacks;
animation packets sent on change or periodic refresh;
exact equipment reservations that avoid duplicate operations.

The Defense Ledger and /defensivemod performance command expose scan and path-request statistics.

Village Defenders is designed to remain practical for active villages and multiplayer servers, although performance may vary with settlement size, terrain, entity count, pathfinding load, and other installed projects. Crowded-village profiling is still part of the documented pre-release acceptance work.

What This Project Does Not Add

Village Defenders does not include:

a permanent Guard profession;
custom weapon or armor tiers;
a Defense Horn;
fortified-town progression;
biome-specific military systems;
culture-specific formations or tactics;
a large villager magic system;
villager-built fortifications;
siege engines;
hunting systems;
literal synchronized guardian-child hand-holding.

It is also not:

a chatbot system;
a personality, trust, dialogue, or gift project;
a custom village-generation project;
a general navigation overhaul;
a complete replacement for vanilla village logic.

Recommended For

Village Defenders is intended for players and modpacks that want:

raids and hostile encounters to produce a visible village response;
small incidents to remain local when defenders are prepared;
villagers to protect themselves without permanently abandoning normal life;
civilians and children to move away from combat;
existing professions to matter during emergencies;
iron golems to remain relevant to settlement defense;
defensive equipment and village infrastructure to have practical uses;
configurable threat and performance limits;
optional integration with a broader villager ecosystem.

Current Status and Limitations

The current project version is 1.0.0, documented in the changelog as Development.

The current repository has:

29 passing automated tests across 10 test suites;
a successful clean Fabric build;
a successful Fabric client/datagen startup check;
regression coverage for threat escalation, withdrawal stability, persistence, equipment reservations, shelter selection, repairs and state transitions.

Important remaining limitations:

full dedicated-server and multi-client acceptance testing is still pending;
late-join animation synchronization still requires manual validation;
independent defensive arms need visual review with biome and profession clothing;
complex terrain may affect vanilla defensive movement;
nearby golem selection is currently proximity-based rather than a full cached reachability analysis;
heavily modified raids or hostile entities may need datapack tags or a compatibility adapter;
companion projects must register the provided API adapters to activate integration;
compatibility may vary with projects that substantially replace villager rendering, combat, brain behavior or navigation;
crowded-settlement performance profiling remains incomplete;
balance values may evolve through continued gameplay testing and feedback.

Reporting Problems

Please include the following with a problem report:

Village Defenders version;
Minecraft version;
Fabric Loader version;
Fabric API version;
complete logs and crash reports;
relevant defensivemod.json configuration;
world seed;
dimension and coordinates;
settlement state and transition reason, if available;
installed project list;
datapacks that modify aggressor or equipment tags;
clear reproduction steps.

The /defensivemod status, /defensivemod aggressors, /defensivemod assignments and /defensivemod performance outputs are especially useful for diagnosing settlement behavior.

Villagers should not become permanent soldiers, but when their settlement is threatened, they should be capable of protecting one another.