game-code-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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 check targets a failure mode specific to real-time interactive software.

**Check 2.1 -- Delta Time Usage**

All time-dependent calculations must use delta time (the time elapsed since the last
frame). Without delta time, game behavior changes with frame rate.

```
DELTA TIME AUDIT
-------------------------------------------------
FIND: Any += or -= in update/process/tick functions without * delta
FLAG: position += speed (WRONG: frame-rate dependent)
FIX:  position += speed * delta_time (CORRECT: frame-rate independent)

Also check:
- Timers that count frames instead of elapsed time
- Animation speed tied to frame rate
- Cooldowns that expire faster on faster machines
- Velocity calculations that assume fixed frame rate

Severity: CRITICAL when found in gameplay-affecting code
          MINOR when found in cosmetic-only code (particle trails, etc.)
-------------------------------------------------
```

**Check 2.2 -- Hot Path Allocations**

Code that runs every frame must not allocate heap memory. The garbage collector will
eventually reclaim it, but GC pauses cause visible frame drops.

```
HOT PATH ALLOCATION AUDIT
-------------------------------------------------
FIND: new, Array(), Object.create(), .push() growing arrays, string
      concatenation, closures capturing variables, lambda creation --
      in any function called per-frame

FLAG: Allocations in update(), _process(), _physics_process(), Tick(),
      FixedUpdate(), any function called from the main loop

FIX:  Object pooling, pre-allocated arrays, cached references,
      struct-based data (for engines that support it)

Also check:
- Dictionary/Map creation inside loops

From AlterLab-IEU/AlterLab_GameForge, MIT.

More from AlterLab-IEU/AlterLab_GameForge