Alpha-7 Tanks Arena / Engineering field notes

Spec.Test.Fix.

Closing the game-development loop with Codex—from a written contract to something you can test, see, ship, and trust.

Kwabena Bediako Codex × Three.js × Colyseus

Live Alpha-7 Tanks Arena main menu — Production build / alpha7.asabeko.com

01 / The operating model

Close the loop,
not the ticket.

01SpecifyState the player outcome and the system contract.

02BuildLet Codex trace the contract into the smallest working change.

03TestReject broken changes with cheap automated gates.

04ObserveExpose runtime state and inspect what the player sees.

05FixRepair the shared root cause, then replay the evidence.

06ShipVerify the deployed system and feed reality back in.

Codex accelerates every pass.Evidence decides when a pass is done

02 / Specification as executable context

Four docs.
Four jobs.

Docs/PRD.md

Outcome

Who is the player? What must the complete loop feel like?

Docs/DESIGN.md

Intent

Warm concrete. Tactical hierarchy. Orange only when it means something.

Docs/SPEC.md

Contract

Server authority, client intent, deterministic maps, debug hooks.

Docs/QA_PLAN.md

Proof

Commands, screens, interactions, device tiers, honest boundaries.

A useful requirement names the experience and how failure becomes observable.

03 / Architecture follows the contract

Put truth in
one place.

The smallest multiplayer architecture is the one where every disputed fact has a clear owner.

Client / React + Three.js

Intent + presentation

Input vectors
Aim / fire / ability intents
Prediction + interpolation
Camera + HUD state

Server / Colyseus

Authoritative truth

Movement + collision
Combat + damage
Map seed + zone
Death + placement + winner

Why it helps Codex: the spec identifies the shared seam to fix instead of inviting patches in every caller.

04 / Automated floor

Smoke is a gate.
Not proof.

✓Typecheckshared → client → server

✓Unit testsmovement · maps · combat

✓Buildproduction bundles

✓Agent gatepnpm debug:agent:strict

✓Room smokecreate → join → ready → countdown

Passing this rowonly earns the next test: manual play, a purpose-built harness, and network stress.

05 / Make the game explain itself

Build the probe
the bug needs.

Expose the live state, reproduce the condition, and compare the result.

DeterministicHuman-readableMachine-checkable

> window.render_game_to_text()
{
  "route": "gameplay",
  "debug": {
    "counts": { "players": 8 },
    "hud": { "layout": { "overlap": {
      "matchHeaderWithMinimap": false,
      "abilityOutsideViewport": false
    }}}
  },
  "room": { "matchState": "danger" },
  "map": {
    "materialSource": "reference-informed-concrete-v4"
  },
  "arena": { "lighting": {
    "source": "seeded-directional-v1"
  }}
}

06 / Browser-based validation

Manually replay
the player path.

MenuCall sign, tank select, entry paths.

LobbyRoom code, players, ready state.

MatchMove, aim, fire, pickups, HUD.

DangerZone pressure, darkness, rain.

ResultsWinner, rankings, rematch.

VisualInputRuntime JSONConsole

07 / Root-cause iteration

Fix once.
Replay the loop.

Symptom

“The tank feels like it rubber-bands.”

After camera orbit
Near wall edges
Under speed boost

Shared root cause

Client prediction disagreed with server truth

One shared movement integrator
Server-equivalent circle collision
Synced speed multiplier
Frame-rate-independent reconciliation

Evidence 30ssustained wall push

Focused unit tests
Drive harness
Real room + bot
Effectively zero pose drift

08 / Confidence ladder

Smoke passed.
Now try to break it.

One green path is a checkpoint—not confidence.

01 / Reproduce

Bug harness

deterministic setup
measure
compare

02 / Stress

Transport

latency · loss
jitter
reconnect

03 / Deploy

Railway + Netlify

healthz
WebSocket
CORS

04 / Reality

Real devices

phones · LAN
8-player soak
game feel

Production check: Confirm the public client can connect, reconnect, and recover on the devices and network people will use.

09 / The operating contract

Codex assists.
You decide.

Codex can own

Trace contracts into code
Run repeatable gates
Read structured runtime state
Drive browser sweeps
Suggest root-cause fixes
Preserve the evidence trail

Engineer owns

Product intent
Visual taste + game feel
Acceptable tradeoffs
Real-device conditions
Risk + deployment authority
The final ship decision

Specify what must be true. Then keep closing the loop.