Ashen Legion

 

Mod Concept and Summary

 

Ashen Legion is a combination API + content mod that adds the titular Ashen Legion encounter, as well as zombie encounters on other situations instead. You can define your own data packs to add your own encounters of mobs to spawn en masse during a night, so that players may either stumble upon them, or they find the player themselves. 

If you are an operator, you can use /legion spawn {encounter-name} to spawn your desired encounter. Encounters spawn up to three nodes of mobs near your location, all of which belong to the same legion. If they are programmed to do special behavior using the API (as the titular Ashen Legion is), they will behave with custom behavior depending on the state of the legion. Otherwise, they will behave as normal, but will generally try to move towards threats. 

 

Technical Details

 

Core Legion Group AI

 

The heart of the mod is a group-level state machine that runs every 10 ticks, coordinating every mob in a legion as a single tactical unit rather than a collection of individuals. The legion aggregates threat from all of its members and transitions through five states:

• WANDER — mobs drift aimlessly using a smooth directional wander goal that slowly rotates heading over time rather than snapping between random waypoints
• ALERT — a threat source has been noticed; mobs stalk slowly toward the target and hold at distance, sizing up the situation
• APPROACH — the target is confirmed; the group sprints toward it
• ENGAGE — the target is within engagement range; melee mobs attack, ranged mobs hold position and fire
• REGROUP — casualty losses have exceeded a threshold; mobs pull back and consolidate before re-engaging

State transitions use hysteresis timers (~3 seconds) on all downward transitions so brief threat fluctuations do not cause jitter between states. The APPROACH→ENGAGE transition only requires the target to be within range — it does not impose a secondary threat gate — so mobs don't stall mid-chase waiting for a score they can't reach through proximity alone.

Threat System

 

Each legion member maintains its own local threat table that maps entity UUIDs to float scores. The legion aggregates these per-member tables every update cycle using diminishing returns (each additional member contributes 90% of the previous one's weight) to prevent a pile-on from inflating threat beyond what a single target realistically poses.

Threat events that accumulate score:

Event Base score Damage taken 15× damage amount Ally killed 200 flat Proximity tick Up to 0.8 per cycle, distance-scaled Ranged attack detected 30 Flanking detected 40 Healing observed 25

Each EngageBehavior role modifies these weights — BRACE mobs weigh proximity 2×, RALLY mobs weigh ally deaths 2×, ATTACK_RANGED mobs weigh being approached 1.4×, and so on.

Decay runs every 10 ticks after 5 seconds of no direct hits, but is distance-aware:

• Entity ≤ 24 blocks away: no decay — still an active threat
• Entity 24–48 blocks away: 0.92× per cycle
• Entity beyond follow range or not in world: 0.80× per cycle (clears quickly)

Dead and despawned entity UUIDs are pruned unconditionally every 10 ticks regardless of goal state, preventing ghost scores from stranding the group in APPROACH with no reachable target.

Universal MobEntity Compatibility

 

Any vanilla or modded mob can be inducted into a legion without code changes. A mixin on MobEntity injects a LegionMobData composition object into every mob in the game and makes them implement LegionMob. A second mixin on LivingEntity hooks onDeath and damage to automatically broadcast AllyKilled and DamageDealt threat events to the rest of the group.

Each mob also participates in:

• Stale member sweeps — the legion prunes dead or discarded members at the top of every update cycle, keeping casualty ratios accurate even when mobs are removed by external means
• NBT persistence — each mob saves its legion UUID on world save and reconnects to its legion on chunk load via LegionManager.getOrRestore()
• Goal switching — when the legion transitions state, each member's goal selector is updated via onLegionGoalChanged so AI behaviour matches the group intent

Custom Legion Entities

Two fully-featured entity implementations ship with the mod, both built on direct LegionMob ownership rather than the mixin path, giving them compile-time interface satisfaction and full control over per-state behaviour:

LegionMeleeEntity

 

A melee fighter with distinct AI per state:

State Behaviour WANDER LegionWanderGoal — smooth directional drift, far-ranging ALERT Slow cautious stalk toward target, stops at 8 blocks APPROACH Full-speed sprint, closes to melee range ENGAGE Vanilla MeleeAttackGoal REGROUP Two-phase: flees directly away if threat is within 8 blocks (FLEE animation), then navigates toward the group centre (REGROUP_WALK animation). Max 8-second duration.

LegionBowEntity

 

A ranged archer with bow-specific AI:

State Behaviour WANDER Same smooth drift as melee ALERT Approaches to 18-block stand-off, faster than melee APPROACH Sprints to 10-block effective firing range ENGAGE Holds position, shoots every 1.5 seconds with staggered fire timers; strafes sideways (with slight backward bias, switching direction randomly) if target closes within 8 blocks REGROUP Flees directly away from the primary target only — no regrouping with team. Max 8-second duration.

Both entities broadcast AllyKilled and DamageDealt events to their legion on death and when hit, and sync a DataTracker animation byte to all tracking clients so the renderer can select the correct animation clip per state: IDLE, WALK, ALERT_WALK, RUN, ATTACK, BOW_DRAW, REGROUP_WALK, FLEE.

Regroup & Casualty System

 

When a legion's casualty ratio reaches 60% of its original size, it automatically triggers a REGROUP. The regroup ends when either 80% of surviving members have moved within 8 blocks of the group centre, or an 8-second timeout elapses. On exit, originalMobCount is reset to the current survivor count so the same losses cannot immediately re-trigger another regroup cycle.

Straggler Despawn

 

When a legion is reduced to 2 or fewer members and those members have had no direct combat interaction for 20 seconds, they are silently removed from the world with an end-portal particle burst and an Enderman teleport sound — giving the impression they've slipped away rather than just vanishing.

Data-Driven Encounter Registration

 

Encounters can be defined entirely in JSON at data/<namespace>/legion_encounter/<name>.json:

{ "mobs": [ { "type": "minecraft:zombie", "weight": 3 }, { "type": "minecraft:husk", "weight": 1 } ], "min_size": 6, "max_size": 10, "weight": 2 }

• mobs — weighted pool; a mob type is rolled proportionally at each spawn slot
• min_size / max_size — group size is rolled randomly in this range at spawn time
• weight — relative probability for nightly encounter selection; a weight-3 encounter appears three times as often as a weight-1 encounter

Datapack encounters are cleared and rebuilt on every /reload. If a datapack entry shares an ID with a built-in encounter, the datapack wins. Mod code can also register encounters programmatically via LegionSpawner.register(encounter) — these survive reloads permanently.

Nightly Spawning System

 

Every night (at approximately tick 13000), the spawner schedules one encounter per roughly every two online players (1 player → 1 encounter, 3 players → 2, 5 players → 3, etc.). Encounters are staggered to random points across the 10,000-tick night window so they don't all land at dusk. Each pending spawn is tagged with its world's RegistryKey so cross-dimensional contamination is impossible.

Difficulty scaling:

• Peaceful: no spawns
• Easy: spawn count halved (minimum 1)
• Normal/Hard: full rate

Spawn Safeguards

 

Every spawn attempt checks all of the following before placing any mobs:

Safeguard Threshold Global mob cap No spawn if 120+ legion members already exist Villager proximity Cluster anchors within 16 blocks of a villager are rejected Legion proximity Cluster anchors within 64 blocks of another active legion's centre are rejected Unloaded chunks Anchor candidates in unloaded chunks are skipped (heightmap queries on unloaded chunks return garbage) Queue cap At most 8 pending spawns queued at any time; excess are discarded Solid ground Each mob position requires solid non-fluid ground below and two-block air clearance above

Mobs are distributed across 3–4 tight clusters positioned 24–80 blocks from a randomly chosen anchor player, using uniform disc sampling (radius × √rand) so clusters are truly tight rather than ring-shaped.

Persistence

 

LegionManager extends Minecraft's PersistentState and serialises to the world's data directory. Each legion saves its UUID, current goal state, original/current member counts, and primary target. Individual member entities save their legion UUID in their own NBT. On chunk load, members reconnect to their legion via getOrRestore(), which creates a shell legion if the world file was loaded before the entity NBT was processed, then fills it in as members arrive.

Op Command

 

/legion spawn <id> /legion spawn <id> <min> <max>  

Requires operator permission level 2. Spawns the named encounter centred on the executor's position with an optional custom size range. Tab-completes all registered encounter IDs (datapack entries listed first). On success, broadcasts a count of placed mobs to all operators.

Client-Side Rendering

 

The renderer (AzLegionRenderer) uses AzureLib and selects both model and texture per entity instance:

• Every other entity (by network ID parity: id % 4 >= 2) uses a _rust texture variant, giving visual variety within a group without requiring separate entity types
• Headless model variant (_headless.geo.json) is similarly distributed by ID parity
• The render layer is resolved per entity from its resolved texture identifier so variant textures bind to the correct GPU draw call rather than always falling back to the base texture