Propose game-ai-behavior skill (Game Coding Complete Ch. 11-13, adapted to 2D)

[diego3]

Summary

Adds a new project skill, .claude/skills/game-ai-behavior/, proposing guidance for enemy/actor
AI and behavior — finite state machines, decision/utility scoring, and pathfinding — grounded in
Game Coding Complete, 4th Edition Ch. 11-13, adapted to this engine's 2D Python-scripted
actors.

Where this came from

The user supplied a draft "AI Game Developer Specialist" skill description generated from a RAG
pass over the book. Before proposing it as-is, I checked it against what this codebase actually
implements (event/, resource/, process/, script/, games/metalslug_demo/scripts/python/,
.github/workflows/) and against the already-open game-architecture skill (#23), which covers
most of the draft's engine-architecture claims in more accurate, code-grounded detail.

Two things came out of that check:

1. Several claims in the draft don't match this codebase and would have misled future
   contributors if shipped verbatim:

   • "32-bit GUID messaging" — this engine solved the same problem (avoiding a monolithic event
     enum) with a type-safe generic bus instead (event.Subscribe[T]/Emit, keyed by
     reflect.Type — see event/bus.go), not GUIDs.
   • "XML-defined templates" — actor/scene templates here are YAML (application/data/,
     games/*/scenes/*.yaml), not XML.
   • "Lua for rapid prototyping" — CLAUDE.md's Development Rules require new scripts in
     Python; Lua is legacy/frozen.
   • "LRU Resource Cache" — resource.Manager caches by path but has no eviction policy;
     it grows unbounded. Flagged as a known gap rather than assumed-solved.
   • "Defensive debugging / minidumps" — no crash-report or panic-recovery system exists in this
     repo; CI (test.yml, codeql.yml) covers the "always have a build" half of that section,
     nothing covers the crash-telemetry half.
   • The engine-architecture, process-manager, prototype-spawning, and resource-cache material
     the draft covers is otherwise already documented, accurately, by game-architecture (Propose game-architecture skill (Game Coding Complete patterns) #23)
     — this PR doesn't re-describe it.

2. The one section with genuinely no precedent in this repo is AI/behavior — no FSM
   framework, no decision/utility scoring, no pathfinding exists anywhere in the codebase today.
   enemy_bomber.py and enemy_walk.py are both single hand-written update(dt) functions.
   That's the real gap worth a skill for, so this PR narrows the draft down to that.

What the skill covers

• §1 FSM — when to graduate enemy_bomber.py's informal 2-state if into an explicit
  state-dispatch table, sized as a plain Python dict (no new engine API).
• §2 Decision trees / utility scoring — scoring candidate actions instead of nested
  if/elif, with a note to keep weights YAML-driven rather than hardcoded, matching this
  repo's existing data-driven conventions.
• §3 Pathfinding — A* over a coarse platform-derived grid (not a 3D navmesh — this engine's
  levels are AABB/Box2D platformer geometry), explicitly scoped down from the book's 3D approach.
• §4 — routes AI timing state through the same three conventions game-architecture already
  documents (script globals / object.Timer / process.Manager) instead of inventing a fourth.
• A "Correcting a Common Misreading" section spelling out the GUID/XML/Lua/LRU/minidump gaps
  above, so the corrections are visible in the skill itself, not just this PR description.
• references/behavior-patterns.md — full worked sketches (FSM table, utility scoring, A* grid
  plan) sized to this engine's actual script API surface.

Scope

Docs-only (two new files under .claude/skills/game-ai-behavior/); no engine or game code
changed. Not stacked on any other open PR — branches from main.

---

Generated by Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[diego3]

Updated this skill with a second pass: the user shared a more advanced NotebookLM-generated skill draft (HSM, GOAP/utility, steering behaviors, perception/sensory modeling, navmesh/influence maps, LOD AI, AI regulators, fuzzy logic). Rather than proposing it separately, I validated it against this repo and folded in the parts that add real value for this game:

• New §5 Steering Behaviors — vec2-based Seek/Flee/Arrive, flagged as usually a better first move than an FSM or A* for "movement feels flat."
• New §6 Perception & Sensory Gating — calls out that enemy_bomber.py currently reads the player's position unconditionally every frame ("sensory omnipotence"), and shows the range/line-of-sight gate to use for enemies that should only react once they notice the player.
• Time-sliced pathfinding note (§3) and AI Regulator / update-throttling note (references/) — both tie directly into process.Manager, which already exists in this engine and is still unwired.
• New "Deliberately Out of Scope" section — explains why HSM, GOAP, goal trees, navmesh/influence maps, LOD AI, and fuzzy logic don't fit a linear 2D shooter with a handful of on-screen enemies, so future contributors don't reach for machinery sized for an open-world/RTS game.

Docs-only, same two files as before, no other changes.

---

Generated by Claude Code