Factions - MarkusBordihn/BOs-Easy-NPC GitHub Wiki

Factions 🚩

Factions are a global, per-world registry that lets NPCs identify friends and foes. Each faction has a name, an optional color, and a list of factions it is hostile towards. NPCs assigned to hostile factions can target and fight each other without any player interaction.

Concept

  • Factions are stored globally per world (saved data easy_npc_factions), not per NPC.
  • Each NPC can be assigned to exactly one faction (Attributes > Misc).
  • Hostility is directed: if faction A is hostile towards B, NPCs of A will attack NPCs of B, but not the other way around. For mutual combat, both directions must be set (the faction editor offers a "mutual" checkbox for this).
  • Assigning a faction also places the NPC in a scoreboard team with the same name, so faction members are considered allies and never attack each other.
  • Players can join a faction through the matching scoreboard team (/team join <faction>). They are then targeted by NPCs of hostile factions and — if the target NPC has Attackable by Factions enabled — can damage those NPCs even while they are invulnerable.

Required Setup for Faction Combat ⚔️

For two NPCs to fight each other, the following switches are needed:

  1. Faction assigned to both NPCs (Attributes > Misc, or /easy_npc faction set ...).
  2. Hostile relation between the factions (faction editor or /easy_npc faction hostile add <faction> <hostile_faction>). Remember: relations are directed.
  3. Attack Hostile Factions enabled on the attacking NPC (Objectives > Target).
  4. An attack objective (e.g. Melee Attack) enabled on the attacking NPC (Objectives > Attack). A warning icon on the Target tab reminds you if a target is set without any attack objective.
  5. Attackable by Factions enabled on the NPC that should take damage (Attributes > Combat). This allows members of hostile factions (NPCs and players in a matching faction team) to bypass the Invulnerable protection, while other players and monsters are handled by their own Attackable by ... switches. This gives you full control over who can damage the NPC instead of an all-or-nothing toggle.

Faction Editors 🖊️

  • Attributes > Misc: select the NPC's faction from the selection box (- = no faction, applied immediately). The pencil button opens the editor for the selected faction; the New button opens the faction manager to create a new faction.
  • Faction Manager: a table of all factions with the columns Faction, Attacks factions and Attacked by. Long faction lists are shortened with ... and shown in full on mouse-over. Click a faction name to edit it or create a new one with the text field at the bottom.
  • Faction Editor: reachable via the breadcrumb Factions > <name> — clicking Factions always returns to the manager. Change the faction color with the color picker (limited to the 16 team colors), manage the scrollable Attacks factions list via the selection box (with an optional mutual checkbox), or delete the faction entirely. Incoming hostilities are managed from the attacking faction and are visible in the manager's Attacked by column. The small ? icons explain each section in-game.

Faction management is gated by the FACTION_MANAGEMENT feature (default role: creative player), since factions are global server data. See Permissions for details.

Commands 📜

  • /easy_npc faction create <name> - Create a new faction
  • /easy_npc faction delete <name> - Delete a faction and all relations pointing to it
  • /easy_npc faction list - List all known factions
  • /easy_npc faction color <name> <color> - Set the faction color
  • /easy_npc faction hostile add <faction> <hostile_faction> - Add a directed hostile relation
  • /easy_npc faction hostile remove <faction> <hostile_faction> - Remove a hostile relation
  • /easy_npc faction hostile list <faction> - Show the factions a faction is hostile towards
  • /easy_npc faction set <target> <faction> - Assign a faction to an NPC
  • /easy_npc faction get <target> - Show the faction of an NPC
  • /easy_npc faction clear <target> - Remove the faction from an NPC

Beyond Combat 🔮

The faction assignment is a general grouping mechanism. Besides targeting, it is planned to be usable for conditions and other faction-aware behaviors, which is why it lives under Attributes > Misc instead of the objectives screens.

⚠️ **GitHub.com Fallback** ⚠️