Combat Module

The Combat module lets recruited villagers protect themselves, protect you, attack selected targets, and use real equipment.

Combat Modes

Combat modes are separate from movement modes. A villager can be following, idling, patrolling, or farming, while combat temporarily takes over when needed.

Defend Mode

Defend mode reacts to configured trigger types:

Each trigger has:

• Enabled toggle.
• Entity whitelist.
• Entity blacklist.

Blacklist entries win over whitelist entries. Villagers never target their owner or recruited villagers with the same owner.

Aggressive Mode

Aggressive mode proactively scans nearby entities.

• The scan box is about 16 blocks around the villager.
• Entity blacklist blocks targets.
• Entity whitelist can restrict valid targets.
• Hostile mobs can be included.
• Passive mobs can be included.
• Players can be included.
• Player targeting can use a separate player whitelist.
• Owner and same-owner villagers are protected.

Flee Mode

Flee uses the same style of trigger/filter settings as defensive behavior, but the response is escape instead of attack.

• It remembers the previous combat mode when entering Flee.
• If the villager is hit while fleeing, it can exit Flee and return to the previous combat mode.
• Threat searches use a larger nearby context than Aggressive scanning.

Help Mode

Help is activated through player chat commands.

• It uses the owner's recent attacked or attacked-by target.
• If there is no exact target, villagers rally near the owner for a short window.
• Help context lasts about 30 seconds.
• Help can keep observing new owner combat events during that window.
• When Help ends, villagers return toward their previous state.

Combat Settings

Each villager has per-villager combat settings. There is also a global combat settings template.

• K opens Global Combat Settings by default.
• Saving writes the current settings.
• Sync copies the global template into a villager.
• Global updates require permission.

Settings are grouped into:

• Flee filters and triggers.
• Defend filters and triggers.
• Aggressive filters.
• AI behavior settings.

AI Settings

Loadouts

Villager Overhaul separates stored combat loadout slots from the villager's real hands.

When combat ends, the mod restores hands so other systems can use them. Farming and custom commands can temporarily equip tools for their own work.

Ranged Combat

Ranged behavior uses real ranged items.

• The main hand must be a projectile weapon.
• The offhand must contain valid supported ammo.
• Offhand ammo is required and is not consumed.
• Enchantments and item components can still matter because the mod uses item stacks rather than a fake generic projectile.
• Crossbows and bow-like weapons use their appropriate firing flow.

Melee Combat

Melee combat uses the real main-hand item.

• Strength modifies attack damage through attributes.
• Agility modifies movement speed.
• Vitality modifies max health.
• Armor modifies armor value.
• Reach is read from platform reach attributes when available; otherwise it is estimated from entity sizes.

Blocking

Villagers can block with shield-like items.

• Any item with block use animation can count.
• Blocking only works from the front cone.
• The block cone is broad, roughly a forward-facing shield arc.
• A successful block cancels damage and suppresses knockback.
• Shield durability is damaged.
• Vanilla shield block sound plays.

Eating

Villagers can eat food from their internal inventory.

• In combat, eating is considered at low health.
• Passive out-of-combat eating can happen at a higher health threshold during some controlled behaviors.
• The villager temporarily moves food into the main hand.
• The previous item is restored afterward.
• AI settings prevent the eat loop from being interrupted forever.

Patrols

Patrol is a movement mode that pairs naturally with combat.

• Villagers can follow a recorded route.
• Combat can interrupt patrol.
• After combat, the villager can return to its previous route behavior.