pawn-mind

# Pawn Mind

Decision is not motion. Intent, waypoints, and force live in three layers, or the pawn becomes a pile of flags.

Inspired by gamedev-skills/awesome-gamedev-agent-skills game-ai (Apache-2.0). Original Grok remake. Complements stick-map (input), juice-pass (feel), room-flow (space), lens-rig (camera), gold-sink (loot), save-slot. Not godot-teacher.

Read `references/ai-rules.md` before you design. Fill the three templates under `templates/`.

## When to use

- Enemy / NPC logic: patrol, chase, flee, idle, guard
- Choosing FSM vs behavior tree vs utility scoring
- Steering (seek / arrive) along a path, not through walls
- Pathfinding: A* on a grid or waypoint graph, or driving an engine navmesh
- Agents that stick on corners, flicker states, or repath every frame

## When NOT to use

- Concrete Godot/Unity navmesh bake, NavigationAgent, or BehaviorTree nodes → use godot-teacher
- Physics jitter, CCD, collision response feel → out of scope (a future physics skill)
- Loot tables, gold sinks, shop spread → use gold-sink
- Level blockout, critical path, room beats → use room-flow
- Camera follow / orbit → use lens-rig; hit juice → use juice-pass; bindings → use stick-map
- Aimbots, wallhacks, ESP, aim-assist injectors, cheat overlays, cracked tools, malware

## Inputs

- Genre slice (tile 2D, top-down, 3D navmesh, stealth guard, horde)
- How many distinct behaviors (2–5 obvious states vs many interruptible jobs)
- Graph type available (grid, waypoint graph, baked navmesh)
- Pain: never reaches goal, hugs corners, oscillates, FPS drop on repath
- Whether debug draw (path + current state) is available

## Procedure

1. Read `references/ai-rules.md`. Refuse aimbots, wallhacks, ESP, injectors, malware, and engine-API dumps.
2. Pick the decision model by complexity: 2–5 obvious states → FSM. Many reactive jobs with priority and interrupt → behavior tree. Continuous scored options → utility. Write the pick on `templates/decision-card.md`.
3. Separate the three layers. Decision outputs intent (target, action). Pathfinder yields a waypoint list. Steering follows the next waypoint, not the goal as the crow flies. Never bury A* inside a state's guts as if-flags.
4. Path on the right graph: grid for tile games, waypoint graph for sparse 2D, baked engine navmesh for 3D. Fewer nodes = faster. Prefer engine navmesh in 3D unless the world is a grid.
5. Steer along the path. Advance the waypoint when inside a radius. Seek at full speed; arrive ramps down inside a slow radius. Always scale by `dt`.
6. Recompute paths sparingly: timer, or when the goal moves a tile / cell. Cache the path. Only the waypoint index advances between recomputes.
7. FSM: each state object owns enter / update / exit. Transitions return from the state (or a small table), not a global if-spaghetti.
8. Behavior tree: Sequence = AND (stop at first non-SUCCESS). Selector = OR / fallback (stop at first non-FAILURE). Leaves that take many frames MUST return RUNNING until done, or the tree restarts the action every tick.
9. A* heuristic must be admissible (never overestimate remaining cost). Manhattan for 4-dir grids; octile for 8-dir. Overestimate = non-shortest paths.
10. Fill `templates/path-steer.md` (graph, repath policy, seek/arrive, waypoint radius).
11. Fill `templates/verify-ai.md`. Watch: reach goal, stuck on corners, oscillate states? Draw path + current state while tuning. Stuck timeout forces repath or a state change. Note FPS cost of repath.
12. Tiny original engine-neutral pseudocode only if asked. No vendor dumps. No GDScript copied from any source.

## Output format

- Decision card (model pick, states or tree sketch, blackboard vars)
- Path / steer card (graph, repath, seek/arrive, waypoint radius)
- Verify AI checklist (reach, corners, oscillation, stuck timeout, repath cost)
- One line: game AI worksheet; not a cheat overlay or Godot tutor

## Safety

- Follow `references/ai-rules.md` with no exceptions.
- No aimbots, wallhacks, ESP, aim-assist injectors, cheat overlays, cracked tools, or malware.
- No CSAM in NPC flavor or mock content.
- Engine-neutral notes only. Not a Godot tutor.

## Stop conditions

- Three templates delivered, or refused for cheats / wrong scope (godot-teacher / gold-sink / room-flow / physics)