/game-code-review

name: "game-code-review"
description: >
  Invoke when the user wants a game-specific code review, architecture check, or
  technical analysis of game code. Covers frame independence, hot path performance,
  state machine integrity, and resource lifecycle. Triggers on: "code review", "review
  my code", "check architecture", "game code quality". Do NOT invoke for design
  document review (use game-design-review) or general sprint planning (use
  game-sprint-plan). Part of the AlterLab GameForge collection.
argument-hint: "[file or directory to review]"
effort: high
context: fork
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion
version: 1.3.0

AlterLab GameForge -- Game Code Review Workflow

Game code has failure modes that web code does not. A web app that allocates memory in a request handler costs you some latency. A game that allocates memory in an update loop costs you frame drops that players feel in their hands. A web app with a state management bug shows stale data. A game with a state management bug lets the player walk through walls or fire invisible bullets. Celeste's codebase is legendary precisely because Maddy Thorson and Noel Berry treated frame-perfect input handling as a first-class engineering concern -- and the result is the tightest platformer ever shipped.

This workflow reviews game code through two lenses simultaneously: standard software quality (naming, structure, testing, documentation) and game-specific correctness (frame independence, hot path performance, state machine integrity, resource lifecycle). Both lenses matter. Factorio maintains a million-entity simulation at 60fps because Wube Software treats architecture as a gameplay feature. Ignoring either lens produces code that is either well-structured but broken at runtime, or high-performing but unmaintainable.

Purpose & Triggers

Use this workflow when:

• A developer asks "review my game code" or "check my architecture"
• Before merging a significant feature branch
• When debugging a performance issue and suspecting structural causes
• When a new developer joins and needs to understand code quality standards
• After prototyping, when deciding which code to promote to production
• When transitioning from prototype to production-quality codebase

Problems this solves:

• Frame rate drops caused by per-frame allocations nobody noticed
• Physics that behave differently at 30fps vs 60fps vs 144fps
• State machines that enter impossible states under edge conditions
• Leaked resources on scene transitions causing gradual memory growth
• Hardcoded gameplay values that require recompilation to tune
• Circular dependencies that make systems impossible to test in isolation
• Raw input handling scattered through gameplay code instead of abstracted

Critical Rules

1. **Game-specific checks first.** Standard code quality matters, but game-specific issues cause harder-to-diagnose failures. A naming convention violation is annoying. A frame-rate- dependent physics calculation is a shipped bug on every hardware configuration except the developer's machine.

2. **Context-aware severity.** A `new` allocation in a menu screen handler is fine. The same allocation in a per-frame particle update is a critical GC pressure point. Always consider where code runs before rating severity.

3. **Measure, do not guess.** Do not flag hypothetical performance issues without evidence. If something looks expensive, note it as "potential concern -- profile before optimizing." Premature optimization is real. So is premature optimization anxiety.

4. **Engine idioms matter.** Each engine has conventions. Godot signals are not Unity events are not Unreal delegates. Review code against the conventions of its engine, not against abstract ideals. Noita's pixel physics system works because Nolla Games wrote to the engine's strengths rather than fighting its architecture. Reference the appropriate engine specialist skill for engine-specific standards.

5. **Gameplay values in data, not code.** Any numeric value that a designer might want to tweak (damage, speed, cooldown, spawn rate, drop chance) must live in a config file or data table, not as a constant in source code. This is non-negotiable -- it is a fundamental game architecture requirement documented in `docs/collaboration-protocol.md`.

6. **Test the untestable.** Game systems are notoriously hard to unit test. Push for testable architecture anyway. If a system cannot be tested because it is tightly coupled to the engine, that coupling is a design smell worth flagging. Factorio's developers maintain comprehensive automated tests for their simulation layer by keeping game logic separate from rendering -- that separation is why they ship with confidence.

Workflow

**Step 1: Architecture Overview**

Before reading individual files, understand the shape of the codebase.

• Map the major systems (rendering, physics, gameplay, AI, UI, audio, input, networking)
• Identify the dependency graph between systems
• Check for a clear architectural pattern (ECS, component-based, scene tree, MVC variant)
• Note the presence or absence of abstraction layers between gameplay and engine

ARCHITECTURE MAP TEMPLATE
-------------------------------------------------
System            | Location          | Dependencies       | Abstracted?
-------------------------------------------------
Game Loop / Core  | [path]            | [all systems]      | Y/N
Player Controller | [path]            | Input, Physics     | Y/N
Enemy AI          | [path]            | Pathfinding, State | Y/N
UI System         | [path]            | Game State         | Y/N
Audio Manager     | [path]            | Events             | Y/N
Save System       | [path]            | Serialization      | Y/N
-------------------------------------------------

**Step 2: Game-Specific Code Checks**

These are the checks that distinguish a game code review from a generic code review. Each chec