MonsterAIUnit.xml

AI personality glue. Each Unit picks one Automata (state machine) and maps each of the 8 AI states to an Element (the action to perform). Groups and rules reference Units by Number.

File Location#

Data/Monster/MonsterAIUnit.xml

Loaded at GameServer startup. /reload monster (or reload.monster in the Server Manager) reloads it without a restart. That command reloads every monster file and removes and respawns all monsters and NPCs on the server.

Dependencies#

Depends OnPurpose
MonsterAIAutomata.xmlSupplies the state machine referenced by Automata
MonsterAIElement.xmlSupplies the per-state actions referenced by Element*
Used ByPurpose
MonsterAIGroup.xmlAssigns Units to monsters via StartAI / AI01 / AI02 / AI03
MonsterAIRule.xmlTemporarily overrides a monster class's Unit on a schedule

Role in the AI Hierarchy#

MonsterAIGroup.xml  (BasicAI per monster)
         |
         v
MonsterAIUnit.xml   <-- this file (picks Automata + maps states -> Elements)
         |
         +-> MonsterAIAutomata.xml  (state machine)
         +-> MonsterAIElement.xml   (actions)

Attributes#

<Unit Number="..." Name="..." DelayTime="..."
      Automata="..."
      ElementNormal="..." ElementMove="..." ElementAttack="..." ElementHeal="..."
      ElementAvoid="..." ElementHelp="..." ElementSpecial="..." ElementEvent="..." />
AttributeTypeEffect
NumberintUnique Unit ID. Valid range 0-99. Used as the storage index, so duplicates overwrite each other
NamestringHuman-readable label. Truncated at 49 characters
DelayTimemsMinimum delay between AI dispatcher runs for monsters using this Unit. Lower = more reactive
AutomataintNumber from MonsterAIAutomata.xml. Required - a Unit with no Automata never ticks
ElementNormalint or *Element for state 0 (NORMAL)
ElementMoveint or *Element for state 1 (MOVE)
ElementAttackint or *Element for state 2 (ATTACK)
ElementHealint or *Element for state 3 (HEAL)
ElementAvoidint or *Element for state 4 (AVOID)
ElementHelpint or *Element for state 5 (HELP)
ElementSpecialint or *Element for state 6 (SPECIAL)
ElementEventint or *Element for state 7 (EVENT)

All Element references resolve against the Number attribute in MonsterAIElement.xml. Using * or omitting an Element attribute leaves that state unwired - if the Automata transitions to that state, no action runs and the tick no-ops.

State-to-Element Mapping#

State IDStateUnit attribute
0NORMALElementNormal
1MOVEElementMove
2ATTACKElementAttack
3HEALElementHeal
4AVOIDElementAvoid
5HELPElementHelp
6SPECIALElementSpecial
7EVENTElementEvent

Each tick the Automata picks a transition; the Element bound to that transition's next state runs. The engine does not validate that the Element's declared class matches the state - an ElementAttack can point at a HEAL-class Element and the engine will still execute it, just as the wrong thing.

Tick Timing#

Two delays gate every AI tick for a monster:

  • The Unit's DelayTime (this file) caps how often the Automata is consulted.
  • The Element returned by the Automata can set its own per-element delay on the monster, applied before the next Automata run.

Both are in milliseconds. Lower values increase CPU load for the class.

Cross-File References#

AttributeResolved Against
NumberMonsterAIGroup.xml StartAI / AI01 / AI02 / AI03, and MonsterAIRule.xml Unit
AutomataMonsterAIAutomata.xml Number
Element*MonsterAIElement.xml Number

Common Issues#

  • Monster idle forever - ElementNormal is wired but the Automata never transitions to any other state, so the non-idle Elements never run.
  • Wrong action in the wrong state - Element class does not match the slot. The engine executes whatever it is bound to.
  • DelayTime too low - the dispatcher runs faster than the monster's animation or path can complete, producing jerky behaviour.
  • AI change event does nothing - ElementEvent is missing or set to *; state 7 transitions fire but no action runs.
  • Duplicate Number - the later entry overwrites the earlier one silently.
  • Number outside 0-99 - entry is dropped silently at load.

Last updated October 1, 2026