> For the complete documentation index, see [llms.txt](https://axiomemu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiomemu.gitbook.io/docs/data/monster/monsteraiautomata.md). # MonsterAIAutomata Defines the state transition rules that drive monster behavior. Each Automata is a state machine: "when in state X and condition Y, go to state Z". Each automata number holds up to 30 rules per state, evaluated in Priority order. ## File Location ``` Data/Monster/MonsterAIAutomata.xml ``` Loaded once at GameServer startup. Changes require a restart. ## AI Hierarchy The monster AI system layers four files: ``` MonsterAIGroup.xml -> which monsters spawn where, with what AI | v MonsterAIUnit.xml -> AI personality (Automata + Element mappings) | +-> MonsterAIAutomata.xml <-- this file (transition rules) +-> MonsterAIElement.xml (the actual actions) ``` ## AI States | State | Name | Meaning | | ----- | ------- | ----------------------------------------------------------------- | | `0` | NORMAL | Idle / general | | `1` | MOVE | Chasing target or patrolling | | `2` | ATTACK | Attacking target | | `3` | HEAL | Self or group healing | | `4` | AVOID | Fleeing danger | | `5` | HELP | Supporting allies (heal, buff) | | `6` | SPECIAL | Summon, invisibility, immunity, teleport, skill attack, AI change | | `7` | EVENT | Reserved for event-class actions | Each state uses the Element slot with the matching index in `MonsterAIUnit.xml` (ElementNormal, ElementMove, ElementAttack, ElementHeal, ElementAvoid, ElementHelp, ElementSpecial, ElementEvent). ## Transition Types | Type | Name | Triggered when | | ---- | ------------- | ------------------------------------------------------------------------------------- | | `0` | NO\_ENEMY | No enemy currently targeted (or target left viewport) | | `1` | IN\_ENEMY | Target is within the monster's AttackRange | | `2` | OUT\_ENEMY | Target is at or beyond AttackRange (out of attack range) | | `3` | DIE\_ENEMY | Current target died. TODO: verify (declared in enum, not handled in evaluator switch) | | `4` | DEC\_HP | Monster's current HP is less than or equal to `TransitionValue` (absolute HP) | | `5` | DEC\_HP\_PER | Monster's current HP is at or below `TransitionValue` percent of max HP | | `6` | IMMEDIATELY | Rolls `TransitionRate` unconditionally | | `7` | AGRO\_UP | Aggro on current target is at or above `TransitionValue` | | `8` | AGRO\_DOWN | Aggro on current target is at or below `TransitionValue` | | `10` | GROUP\_SUMMON | A dead group member is available to re-summon | | `11` | GROUP\_HEAL | A group member within 6 tiles has HP below `TransitionValue` percent | | `12` | SUPPORT\_HEAL | An allied monster within 6 tiles has HP below `TransitionValue` percent | ## Attributes ```xml ``` | Attribute | Type | Effect | | --------------------- | ---------- | ------------------------------------------------------------------------------------------------------- | | `Number` | 0-299 | Automata group ID. Referenced by `MonsterAIUnit.Automata`. | | `Description` | string | Human-readable label. Stored but not used for logic. | | `Priority` | 0-29 | Check order within the CurrentState bucket. Lower fires first. | | `CurrentState` | 0-7 | State this rule applies FROM. | | `NextState` | 0-7 | State to transition TO on success. | | `TransitionType` | enum | Condition type (see table above). | | `TransitionRate` | 0-100 | Probability the transition fires when the condition matches (random 0-99 is compared against the rate). | | `TransitionValueType` | int or `*` | `*` is stored as -1. Currently unused by the evaluator. | | `TransitionValue` | int or `*` | Condition parameter (HP amount, HP percent, aggro threshold). `*` is stored as -1. | | `DelayTime` | ms | Applied as `LastAutomataDelay` when the rule fires; controls the wait before the next transition check. | ## How a Tick Works 1. Monster spawns in State 0 (NORMAL) with the Unit referenced by `StartAI`. 2. Each AI tick iterates rules whose `CurrentState` equals the monster's current state, ordered by insertion (effectively by Priority 0, 1, 2 ...). 3. For each rule, the evaluator checks the `TransitionType` condition. If the condition holds, it rolls a random 0-99 against `TransitionRate`. 4. The first rule that passes returns immediately. The monster moves to `NextState`, its `LastAutomataDelay` is set to `DelayTime`, and the matching Element from the AI Unit executes. 5. If no rule passes, the monster stays in the current state. ## Cross-File Dependencies | Attribute | Related in | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `Number` | Referenced by `MonsterAIUnit.Automata` in [MonsterAIUnit.xml](/docs/data/monster/monsteraiunit.md) | | `NextState` mapping | Action defined by the matching Element in [MonsterAIElement.xml](/docs/data/monster/monsteraielement.md) via the AI Unit | | AttackRange used by Types 1 and 2 | See [Monster.xml](/docs/data/monster/monster.md) and [MonsterAIRule.xml](/docs/data/monster/monsterairule.md) | ## Common Issues * **Monster never attacks** - no transition from state 0 (NORMAL) to state 2 (ATTACK) with a matching `TransitionType`. * **Monster goes passive after a hit** - transition from 2 (ATTACK) to 0 (NORMAL) firing too easily; raise `Priority` of the stay-in-combat rule or lower the NORMAL rule's `TransitionRate`. * **Boss phases never advance** - no transition to state 6 or 7 with `DEC_HP_PER` and a `NextState` Element of Type 68 (AI Change). * **Monster heals forever** - transition into state 3 (HEAL) fires but no transition out; add a rule from state 3 with Type 6 (IMMEDIATELY) back to NORMAL/MOVE/ATTACK. * **Group summon never fires** - group members still alive, or monster is not assigned a valid `GroupNumber`.