# ai-system

> Develops intention-based AI for summons, NPCs, and combat behavior.
Use when: implementing NPC behaviors, modifying summon/pet AI, creating custom monster AI scripts, debugging AI state transitions, or adding new AI intentions/events

- Author: valeriybaranyshyn-pixel
- Repository: valeriybaranyshyn-pixel/Tales-of-Aden
- Version: 20260202145225
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/valeriybaranyshyn-pixel/Tales-of-Aden
- Web: https://mule.run/skillshub/@@valeriybaranyshyn-pixel/Tales-of-Aden~ai-system:20260202145225

---

---
name: ai-system
description: |
  Develops intention-based AI for summons, NPCs, and combat behavior.
  Use when: implementing NPC behaviors, modifying summon/pet AI, creating custom monster AI scripts, debugging AI state transitions, or adding new AI intentions/events
allowed-tools: Read, Edit, Write, Glob, Grep, Bash
---

# AI System Skill

The L2J AI system is a hierarchical intention-based state machine where **intentions** represent goals and **events** represent triggers. Understanding this duality is essential: intentions are persistent ("attack this target") while events are momentary reactions ("I was stunned").

## Quick Start

### Setting an AI Intention

```java
// Set attack intention - AI will pursue this goal until changed
creature.getAI().setIntention(CtrlIntention.ATTACK, target);

// Set follow intention with target
summon.getAI().setIntention(CtrlIntention.FOLLOW, owner);

// Set idle - detaches AI from NPCs when no players nearby
npc.getAI().setIntention(CtrlIntention.IDLE);
```

### Notifying AI Events

```java
// Notify that creature was attacked - may trigger aggro
creature.getAI().notifyEvent(CtrlEvent.EVT_ATTACKED, attacker);

// Notify aggression with hate value
creature.getAI().notifyEvent(CtrlEvent.EVT_AGGRESSION, target, 100);

// Trigger think cycle manually
creature.getAI().notifyEvent(CtrlEvent.EVT_THINK);
```

## Key Concepts

| Concept | Usage | Example |
|---------|-------|---------|
| `CtrlIntention` | AI goal states | `IDLE`, `ACTIVE`, `ATTACK`, `CAST`, `FOLLOW` |
| `CtrlEvent` | AI triggers | `EVT_THINK`, `EVT_ATTACKED`, `EVT_ARRIVED` |
| `thinkX()` methods | Decision logic per intention | `thinkAttack()`, `thinkCast()`, `thinkActive()` |
| `onIntentionX()` | Handlers when intention is set | `onIntentionAttack(target)` |
| `onEvtX()` | Handlers when event fires | `onEvtAttacked(attacker)` |

## AI Class Hierarchy

| Class | Purpose | Use Case |
|-------|---------|----------|
| `AbstractAI` | Base AI, movement, follow tasks | Never instantiate directly |
| `L2CharacterAI` | Generic character behaviors | Base for custom AI |
| `L2SummonAI` | Pet/summon AI with avoid behavior | Extends for custom pets |
| `L2AttackableAI` | Monster AI with aggro/skills | Extends for custom monsters |
| `L2SiegeGuardAI` | Siege defender AI | Siege-specific NPCs |

## Common Patterns

### Creating Custom Monster AI via Script

```java
public class CustomBossAI extends L2AttackableAIScript
{
    public CustomBossAI()
    {
        super("ai/custom");
        addAttackId(BOSS_ID);
        addKillId(BOSS_ID);
    }
    
    @Override
    public String onAttack(L2Npc npc, Player attacker, int damage, boolean isPet)
    {
        // Custom attack response
        if (npc.getCurrentHp() < npc.getMaxHp() * 0.5)
            npc.doCast(RAGE_SKILL);
        return super.onAttack(npc, attacker, damage, isPet);
    }
}
```

### Scheduled Think Task Pattern

```java
// L2AttackableAI runs onEvtThink() every 1000ms when not IDLE
_aiTask = ThreadPool.scheduleAtFixedRate(this, 1000, 1000);

// L2SummonAI runs avoid task every 100ms
_avoidTask = ThreadPool.scheduleAtFixedRate(this, 100, 100);
```

## See Also

- [patterns](references/patterns.md) - AI patterns, state machine, anti-patterns
- [workflows](references/workflows.md) - Adding intentions, events, custom AI

## Related Skills

- See the **java** skill for L2J coding conventions
- See the **skill-system** skill for skill casting integration
- See the **geodata** skill for pathfinding and line-of-sight
- See the **npc-scripting** skill for Quest-based AI extensions