Skip to main content

Villages

Faction villages are controlled through a totem. A faction can capture a village (the totem's controllingFaction changes), raid it and has guards, a task master and a banner. FactionApi provides the totem implementation (TotemBlockEntity); the API gives you the hooks.

Configuring a faction​

All village settings are FactionProperties calls that set data components on the faction:

FactionProperties callData component (FactionDataComponents)Meaning
totem(fragile, crafted)VILLAGE_TOTEM (TotemPair)totem top blocks: world-generated (fragile) and crafted
banner(VillageBanner)VILLAGE_BANNERominous-banner look that carries the bad omen
badOmen(Holder<MobEffect>)VILLAGE_BAD_OMENeffect that can trigger a raid of this faction
villageGuards(TagKey<EntityType>)VILLAGE_GUARDSentity types that guard the faction's villages
taskMaster(Holder<EntityType>)TASK_MASTER (also enables tasks)task master entity for the faction

Whether a faction may start a capture or a (random) raid is controlled by the can_raid and has_random_raid faction tags.

Types​

  • ITotem – implemented by the totem block entity. getCapturingFaction() (nullable), getControllingFaction(), getVillageArea(), getVillageAreaReduced(), getTileLevel(), position(), isRaidTriggeredByBadOmen(), getVampireForestLocation() (empty by default). It is the first parameter of every FactionVillageEvent.
  • TotemPair(fragile, crafted) – record of two Holder<Block>; get(boolean crafted); TotemPair.DEFAULT uses FactionBlockAccess.TOTEM_TOP / TOTEM_TOP_CRAFTED (factionapi:totem_top and factionapi:totem_top_crafted).
  • VillageBanner(base, layers) – base banner item plus (ResourceKey<BannerPattern>, DyeColor) layers. createBanner(HolderLookup.Provider) builds the stack named "Ominous Banner" and marks it with the IS_FACTION_BANNER component.
  • IFactionVillage / IFactionVillageBuilder – older accessor/builder interface for the same data (badOmenEffect(), createBanner(...), getVillageGuardTypes(), getTaskMasterEntity(), getTotemTopBlock(boolean crafted); builder: badOmenEffect, banner, guardTypes, taskMaster, totem, build). Prefer the FactionProperties calls above in new code.

Entity interfaces​

InterfacePurpose
IVillageCaptureEntityEntities that attack/defend villages during a capture: attackVillage(ICaptureAttributes), defendVillage(...), getCaptureInfo(), getTargetVillageArea(), isAttackingVillage(), isDefendingVillage(), stopVillageAttackDefense().
ICaptureAttributesHanded to those entities: getAttackingFaction(), getDefendingFaction(), getPosition(), getVillageArea(), shouldForceTargets() (AI should target the opposing factions without line-of-sight restrictions; default false).
ICaptureStrengthProviderfloat getCaptureStrength() – an entity's weight when the totem computes the strength ratio.
ICaptureIgnoreMarker: the totem ignores these entities when counting capture participants.
IEntityLeaderLeader of followers: getFollowingCount(), getMaxFollowerCount(), increaseFollowerCount() (returns whether more are allowed), decreaseFollowerCount().
IEntityWithHomeExtends the vanilla home system with an AABB home: getHome(), setHome(AABB), getHomePosition(), isWithinHomeDistance(...), setHomeArea(pos, radius).
IFactionMobMarker for non-player faction entities (extends IFactionEntity).
ITaskMasterEntityMarker for task masters (extends IEntityWithHome); returned by the faction's TASK_MASTER type.

Village data components​

The village related keys of FactionDataComponents are village_totem, village_banner, village_bad_omen, village_guards, task_master and the item marker is_faction_banner; see the full table in Misc.

Hooking into captures​

Use the FactionVillageEvent subclasses, e.g.:

NeoForge.EVENT_BUS.addListener((FactionVillageEvent.InitiateCapture e) -> {
if (e.getTotem().getControllingFaction().is(MY_PROTECTED_FACTION)) {
e.setMessage("message.mymod.village_protected");
e.disallowCapture();
}
});