---
name: ue-api
description: >
  Use this skill when the user asks anything about Unreal Engine C++ APIs,
  class hierarchies, system flows, or how engine subsystems work together.
  Trigger phrases include: "how does X work in UE", "what is the flow for",
  "which class handles", "what virtual functions", "UE API for", "Unreal Engine
  architecture", and any question that names UE types like ACharacter,
  UActorComponent, APlayerController, UBehaviorTreeComponent, APawn, etc.
  Always use this skill for Unreal Engine questions — don't rely on training
  data alone when local documentation is available.
---

# UE API Skill

Answer questions about Unreal Engine C++ APIs and system flows using the local
documentation corpus as the fast primary source, then source headers for depth.

## Configuration

Two environment variables control where to look:

| Variable | Purpose | Example |
|---|---|---|
| `UE_DOCS_PATH` | Root of the generated documentation | `/home/user/ue-docs` |
| `UE_ENGINE_ROOT` | UE engine source root (for header fallback) | `/home/user/UnrealEngine` |

**Resolve them at the start of every query:**

```bash
echo "$UE_DOCS_PATH"
echo "$UE_ENGINE_ROOT"
```

If `UE_DOCS_PATH` is unset, ask the user where their generated docs are before
proceeding. If `UE_ENGINE_ROOT` is unset, only ask when a question actually
requires source headers — don't interrupt doc-only queries.

The type index is always at `$UE_DOCS_PATH/type-index.txt`.

## Step 1 — Identify types, resolve paths

Extract UE type names from the question (e.g. `APlayerController`, `APawn`,
`UBehaviorTreeComponent`). Resolve all of them in a single grep:

```bash
grep "^APlayerController:\|^APawn:\|^ACharacter:" "$UE_DOCS_PATH/type-index.txt"
```

Paths in the index are relative to `$UE_DOCS_PATH` — prepend it when reading:

```bash
# index returns: AController: Engine/Classes/GameFramework/Controller.md
# read as:
Read "$UE_DOCS_PATH/Engine/Classes/GameFramework/Controller.md"
```

The `.md` files are compact by design — only items with C++ doc comments,
no deprecated entries, enums collapsed when undescribed.

## Step 2 — Follow the trail

Inline links in `*Inherits*:` lines and function signatures point to related
types. Follow them when the question spans multiple classes. A second grep on
`type-index.txt` is always cheaper than guessing paths.

## Step 3 — Escalate to source headers when docs aren't enough

The docs only surface items with C++ doc comments. Go to `.h` files when:

- The exact call order or implementation logic isn't described in any comment
- A function or member is absent from `.md` files (no doc comment)
- The question involves macros: `UCLASS`, `UPROPERTY`, `UFUNCTION`,
  `DECLARE_DELEGATE_*`, `GENERATED_BODY`, etc.
- Private or protected members are relevant to the answer
- The user asks about edge-case behaviour ("what happens when X is null?")

Search under `$UE_ENGINE_ROOT/Engine/Source/` — e.g.:

```bash
Glob("**/*Controller*.h", path="$UE_ENGINE_ROOT/Engine/Source/Runtime/Engine")
Grep("void Possess", path="$UE_ENGINE_ROOT/Engine/Source")
```

## Output format

Lead with the direct answer or a concise flow description. For multi-step
flows use an ASCII sequence or numbered list. For single-class API questions,
a brief prose answer with the key function signatures is enough.

Cite every substantive claim — `(Controller.md)` for docs, `(Controller.h:142)`
for source. Mark source-derived facts as *implementation detail* since they can
change across engine versions; doc-derived facts reflect the stable API contract.

## Examples

**"How does APlayerController possess APawn?"**
→ check `$UE_DOCS_PATH` → grep type-index for AController, APawn,
APlayerController, ACharacter → read the four `.md` files → ASCII diagram

**"What virtual functions does ACharacter expose for movement?"**
→ grep for ACharacter, UCharacterMovementComponent → read docs → list virtuals

**"What does UFUNCTION(BlueprintCallable) expand to?"**
→ docs won't help (macro) → search `$UE_ENGINE_ROOT` for `UFUNCTION` definition

**"How does the behavior tree pick which task to run?"**
→ grep for UBehaviorTreeComponent, UBTCompositeNode, UBTDecorator → read docs
→ if execution order is still unclear, escalate to `BehaviorTreeComponent.h`