# XWUIGameAIDebugOverlay

An in-engine AI-state debug overlay that lists `agents` with a colored state dot (idle/patrol/alert/combat/flee/dead), and on click drills into the selected agent's `State`, `Target`, perception (`Sight`/`Hearing`), and patrol `Path Nodes` count. Drop it into a running scene to inspect agent behavior; toggle the `showPerception` and `showPatrol` config flags to trim the detail panel, and push live updates through `updateData({ agents, selectedId })`.

## Basic Usage

Mounts a populated overlay listing four guard agents across different states, with a patrolling sentry pre-selected so the detail panel shows its state, target, perception, and patrol path-node count.

```example
file: examples/BasicUsage.ts
html: examples/BasicUsage.html
title: Basic Usage
description: A populated AI debug overlay listing four guard agents with a patrolling sentry pre-selected to show its detail panel.
```

## Perception Tuning

A stealth-detection overlay with `showPatrol: false` so the detail panel focuses on each agent's contrasting sight and hearing ranges.

```example
file: examples/PerceptionTuning.ts
html: examples/PerceptionTuning.html
title: Perception Tuning
description: A stealth scene with the patrol row hidden, contrasting a long-sighted archer against a sharp-hearing cave stalker.
```

## Live Alert Escalation

A Raise Alarm button that calls `updateData()` to step the whole guard squad from idle to alert to combat, re-rendering the state dots live.

```example
file: examples/LiveAlertEscalation.ts
html: examples/LiveAlertEscalation.html
title: Live Alert Escalation
description: A button that escalates every agent idle to alert to combat via updateData(), shifting the state dots green to yellow to red.
```

```api
```