# MonsterAIRule

Defines conditional rules that can **temporarily override** a monster's AI Unit based on time, date, or server events. This allows monsters to change their entire behavior pattern during specific periods.

## File Location

`GameServer/Data/Monster/MonsterAIRule.xml`

## Dependencies

| Depends On                                                                                               | Purpose                                         |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [MonsterAIUnit.xml](https://gitlab.com/axiom-emu/docs/-/blob/main/gameserver/monster/monsteraiunit.md)   | Rules override monsters with different AI Units |
| [MonsterAIGroup.xml](https://gitlab.com/axiom-emu/docs/-/blob/main/gameserver/monster/monsteraigroup.md) | Defines monsters' default AI Units              |

| Used By           | Purpose                                           |
| ----------------- | ------------------------------------------------- |
| Monster AI System | Evaluated every AI tick to check for active rules |

## How It Works

MonsterAIRule allows you to **temporarily replace** a monster's AI Unit based on conditions:

1. **Normal behavior**: Monster uses its `BasicAI` (from MonsterAIGroup.xml)
2. **Rule activates**: When a rule's condition is met, the monster switches to the rule's `Unit`
3. **Behavior changes**: The monster now uses a completely different AI personality
4. **Rule expires**: After `WaitTime + ContinuanceTime`, monster reverts to `BasicAI`

{% hint style="info" %}
This is an **AI Unit override system**, not a stat modifier. Rules completely replace the monster's behavior pattern (Automata, Elements, timing) for the duration of the rule.
{% endhint %}

## Rule Evaluation

Rules are evaluated every AI tick (`MonsterAIProc`) for every active monster:

1. Check if rule condition is valid (date/time/event match)
2. Check if `WaitTime` has elapsed since condition became valid
3. Check if we're still within `WaitTime + ContinuanceTime`
4. If all checks pass, override the monster's `CurrentAI` with the rule's `Unit`

## Current Status

{% hint style="warning" %}
The default configuration file is **empty** (no active rules). The system is fully functional and loaded at server startup, but requires you to define rules to use it.
{% endhint %}

```xml
<?xml version="1.0" ?>
<MonsterAIRule/>
```

## Configuration Structure

### Rule Attributes

| Attribute         | Type       | Required    | Description                                                               |
| ----------------- | ---------- | ----------- | ------------------------------------------------------------------------- |
| `Number`          | int        | Yes         | Unique rule identifier                                                    |
| `Class`           | int        | Yes         | Monster class ID to apply rule to (all monsters of this class)            |
| `Description`     | string     | No          | Human-readable rule description                                           |
| `Unit`            | int        | Yes         | AI Unit to override with (from MonsterAIUnit.xml)                         |
| `Condition`       | int        | Yes         | Condition type: `1` = Date/Time, `71` = Crywolf Start, `72` = Crywolf End |
| `WaitTime`        | int        | Yes         | Seconds to wait after condition becomes true before activating            |
| `ContinuanceTime` | int        | Yes         | Seconds the rule stays active after WaitTime expires                      |
| `Month`           | int/string | Conditional | Month (1-12) or `*` for any month                                         |
| `Day`             | int/string | Conditional | Day (1-31) or `*` for any day                                             |
| `WeekDay`         | int/string | Conditional | Weekday (0=Sunday, 6=Saturday) or `*` for any day                         |
| `Hour`            | int/string | Conditional | Hour (0-23) or `*` for any hour                                           |
| `Minute`          | int/string | Conditional | Minute (0-59) or `*` for any minute                                       |

{% hint style="info" %}
**Wildcard `*`**: Use `*` to ignore a date/time field. For example, `Hour="*"` matches all hours.
{% endhint %}

### Condition Types

| Condition | Description         | Date/Time Fields Used                  |
| --------- | ------------------- | -------------------------------------- |
| `1`       | Specific Date/Time  | All date/time attributes apply         |
| `71`      | Crywolf Event Start | Not implemented (always returns false) |
| `72`      | Crywolf Event End   | Not implemented (always returns false) |

{% hint style="warning" %}
Crywolf conditions (71, 72) are **not implemented** in the current version. Use Condition `1` (Date/Time) for functional rules.
{% endhint %}

## Important Behavior

### Timing Logic

The rule activation follows this timeline:

```
Condition becomes TRUE → Wait [WaitTime] seconds → Rule ACTIVE for [ContinuanceTime] seconds → Rule EXPIRES
```

**Example**: Halloween rule with `WaitTime="10"` and `ContinuanceTime="3600"`

* October 31, 00:00:00 → Condition becomes true
* October 31, 00:00:10 → Rule activates (10 second wait)
* October 31, 01:00:10 → Rule expires (3600 second duration)

### Date/Time Matching

* **All specified fields must match**: If you set `Month="10"` and `Hour="20"`, the rule only activates on October at 8 PM
* **Wildcards ignore fields**: `Month="*"` means the rule ignores the month completely
* **ValidRange calculation**: The `WaitTime + ContinuanceTime` defines how long the condition can remain true
* **Minute-precision**: Time matching is precise to the minute

### Multiple Rules Per Monster

If multiple rules target the same monster class:

* The **last valid rule** in the array takes precedence
* Rules are evaluated in order from first to last
* Only one AI Unit override can be active at a time

### Performance Impact

Rules are evaluated **every AI tick** for **every active monster**. Keep the number of rules reasonable (under 50) to avoid performance issues.

## Examples

{% tabs %}
{% tab title="Halloween Night Bosses" %}
Make Golden Goblins (class 8) super aggressive on Halloween night:

```xml
<MonsterAIRule>
  <!-- Halloween: Golden Goblins become aggressive hunters -->
  <Rule
    Number="1"
    Class="8"
    Description="Halloween aggressive Golden Goblin"
    Unit="101"
    Condition="1"
    WaitTime="0"
    ContinuanceTime="86400"
    Month="10"
    Day="31"
    WeekDay="*"
    Hour="*"
    Minute="*"
  />
</MonsterAIRule>
```

* Activates on October 31 at midnight
* Switches Golden Goblins to AI Unit 101 (aggressive hunter behavior)
* Lasts for 86400 seconds (24 hours)
* All Golden Goblins on the server are affected
  {% endtab %}

{% tab title="Weekend Night Events" %}
Make White Wizards (class 20) use special event AI every Saturday night:

```xml
<MonsterAIRule>
  <!-- Saturday night special behavior -->
  <Rule
    Number="2"
    Class="20"
    Description="Saturday night White Wizard event"
    Unit="205"
    Condition="1"
    WaitTime="0"
    ContinuanceTime="14400"
    Month="*"
    Day="*"
    WeekDay="6"
    Hour="20"
    Minute="0"
  />
</MonsterAIRule>
```

* Activates every Saturday at 8:00 PM
* Switches White Wizards to AI Unit 205 (event behavior)
* Lasts for 14400 seconds (4 hours, until midnight)
  {% endtab %}

{% tab title="Rush Hour Aggression" %}
Make all Budge Dragons (class 3) more aggressive during evening peak hours:

```xml
<MonsterAIRule>
  <!-- Evening rush hour aggression (6 PM - 10 PM daily) -->
  <Rule
    Number="3"
    Class="3"
    Description="Evening peak aggression"
    Unit="150"
    Condition="1"
    WaitTime="0"
    ContinuanceTime="14400"
    Month="*"
    Day="*"
    WeekDay="*"
    Hour="18"
    Minute="0"
  />
</MonsterAIRule>
```

* Activates every day at 6:00 PM
* Switches Budge Dragons to AI Unit 150 (high aggression)
* Lasts for 14400 seconds (4 hours)
  {% endtab %}

{% tab title="Delayed Event Start" %}
Start a Christmas event AI 1 hour after midnight:

```xml
<MonsterAIRule>
  <!-- Christmas event with 1 hour warmup period -->
  <Rule
    Number="4"
    Class="50"
    Description="Christmas Elf event (delayed start)"
    Unit="300"
    Condition="1"
    WaitTime="3600"
    ContinuanceTime="82800"
    Month="12"
    Day="25"
    WeekDay="*"
    Hour="0"
    Minute="0"
  />
</MonsterAIRule>
```

* Condition becomes true at December 25, 00:00
* Rule activates at 01:00 (3600 second wait)
* Lasts until 24:00 (82800 seconds = 23 hours)
  {% endtab %}
  {% endtabs %}

## Common Issues

{% hint style="danger" %}
**Rule Not Activating**: Check that:

* The `Unit` exists in MonsterAIUnit.xml
* The `Class` matches monsters in MonsterAIGroup.xml
* Date/time fields are correct (0-based WeekDay: Sunday=0)
* `Condition` is `1` (not 71 or 72, which don't work)
  {% endhint %}

{% hint style="warning" %}
**Rules Expire Too Quickly**: The `ContinuanceTime` is in **seconds**, not minutes. Common mistake: setting `ContinuanceTime="60"` for 60 minutes (actually only 1 minute). Use `ContinuanceTime="3600"` for 1 hour.
{% endhint %}

{% hint style="warning" %}
**Wrong Time Zone**: Server time is based on system clock. Ensure your server's system time and timezone are correct.
{% endhint %}

## Use Cases

### Time-Based Events

* **Night aggression**: Make monsters more aggressive at night (Unit with lower DelayTime, aggressive Automata)
* **Weekend bosses**: Spawn event bosses only on weekends
* **Hourly rotations**: Rotate monster behavior every few hours

### Seasonal Events

* **Halloween**: Spooky behavior on October 31
* **Christmas**: Festive monster patterns in December
* **Anniversary**: Special AI during server anniversary dates

### Dynamic Difficulty

* **Peak hour challenge**: Harder AI during peak player hours
* **Off-peak relaxation**: Easier AI during low-population times
* **Weekly cycles**: Escalating difficulty through the week

## When NOT to Use MonsterAIRule

MonsterAIRule is powerful but not always the right tool:

| Need                       | Better Solution                                    |
| -------------------------- | -------------------------------------------------- |
| Permanent behavior changes | Modify MonsterAIGroup.xml directly                 |
| HP-based skill triggers    | Use MonsterSkill.xml                               |
| Timed spawns/despawns      | Use MonsterSetBase.xml Type 3 (event-based spawns) |
| Event-specific monsters    | Create event-specific monster classes              |
| Simple stat changes        | Modify Monster.xml stats directly                  |

## Related Systems

For comprehensive monster control:

* [MonsterAIUnit.xml](https://gitlab.com/axiom-emu/docs/-/blob/main/gameserver/monster/monsteraiunit.md) - AI Unit definitions that rules override to
* [MonsterAIGroup.xml](https://gitlab.com/axiom-emu/docs/-/blob/main/gameserver/monster/monsteraigroup.md) - Default AI Unit assignments (BasicAI)
* [Monster.xml](https://axiomemu.gitbook.io/docs/gameserver/monster/monster) - Stats, aggression (ViewRange), movement patterns
* [MonsterSkill.xml](https://axiomemu.gitbook.io/docs/gameserver/monster/monsterskill) - Skills with conditional triggers (HP-based)
* [MonsterSetBase.xml](https://axiomemu.gitbook.io/docs/gameserver/monster/monstersetbase) - Spawn timing and locations
