WEB PORT ARCHITECTURE

Plain HTML + Canvas — no build tools, no frameworks

FILES

game.js

~2,550 lines. All game logic, rendering, input, and audio orchestration. Single file, no imports.

levels.js

35 decoded stage maps as JS arrays — one 13×13 tile-type grid per stage, extracted from ROM.

sound.js

Web Audio API synthesizer. Recreates 2A03 square/noise channels for all SFX.

tiles/chr_all.png

Full 8 KB CHR-ROM decoded to PNG. 32×16 grid of 8×8 tiles (9px cells with 1px border). BG bank tiles 0–255, sprite bank 256–511.

index.html

Game shell. Canvas wrapped in a clipping div that hides 8px top/bottom to replicate NTSC CRT overscan.

catalog.html

Visual reference: all metasprites, terrain tiles, palettes, and SFX playback — rendered live from chr_all.png.

COORDINATE SYSTEM

All game logic runs in NES pixel space (256×240). A single SCALE constant (= 3) maps NES pixels to CSS pixels at render time. Changing it resizes everything without touching any game code.

Constant	Value	Meaning
`NES_W / NES_H`	256 / 240	Full NES PPU output size
`SCALE`	3	CSS pixels per NES pixel
`FX / FY`	16 / 16	Playfield top-left in NES pixels (2-tile border)
`GW / GH`	13 / 13	Playfield width/height in metatiles
`META`	16	Pixels per metatile (2×2 CHR tiles)
`TANK_SZ`	16	Tank sprite size in NES pixels

Tank and bullet positions are stored as the sprite center in NES pixels. Collision probes use the leading-edge corners, mirroring the ROM's MoveGridSnap routine.

RENDER PIPELINE

The renderer faithfully reproduces the NES PPU pipeline order: background first, then sprites on top.

CHR tile engine

chr_all.png is loaded once into an offscreen canvas (chrOff)
drawCHRTile(tileAbs, palIdx, x, y) — reads an 8×8 pixel block from the sheet, applies the NES palette, writes into a scaled cached canvas, then blits to the main canvas
Tile cache keyed by "tileAbs_palIdx_transparent" — avoids re-processing identical tiles
drawMetatile composes 4 CHR tiles into a 16×16 BG metatile
drawSprite16 composes two 8×16 OAM entries into a 16×16 metasprite, with transparency (color-0 = skip)

Palette system

9 background palette sets extracted from ROM $D565 BGPaletteTable — indexed by palSet
Fixed sprite palettes from ROM $D555 SpritePaletteData
All palette entries map through the Nestopia NTSC master palette (846 entries covering all 64 NES color indices)
Active palette set switches on water animation (every 32 frames), title screen, game-over, and grenade/shovel flash

Per-frame render order

1Fill border regions (gray tile $FC)

2Fill playfield black (C.FIELD)

3Draw all 13×13 terrain metatiles (brick with sub-quadrant masking, steel, trees, water, ice)

4Draw eagle sprite

5Draw power-up sprite (if active)

6Draw entity sprites — tanks (CHR metasprites), spawn animation, death explosion

7Draw bullet sprites

8Draw trees overlay (painted after tanks so trees appear in front)

9Draw HUD — right panel: enemy tank icons, player lives, stage number

10Draw overlays — shield glint, GAME OVER scroll, grenade flash, freeze indicator

GAME LOOP

Runs via requestAnimationFrame locked to 60 fps. Each tick: read input → update all subsystems → render.

Subsystem	ROM reference	Notes
Input	`$9689 ReadControllers`	Keyboard → D-pad + A/B; gamepad API supported
Entity movement	`$DD30 MoveGridSnap`	8px snap grid; leading-edge collision probes
AI	`$DC7C EntityMovementAI`	Hardcoded direction sequences + target seeking
Firing	`$E162 EnemyFireTick`	1/32 chance per frame per enemy; player fire on button press
Bullet movement	`$E604 BulletTerrainCollision`	4 px/frame; nametable shadow read for tile type
Bullet–entity hit	`$E70C EnemyBulletPlayerCollision`	Proximity ≤ 10px; armor hit counting
Bullet–bullet cancel	—	Opposing bullets within 8px destroy each other
Power-ups	`$EA7E`	6 types; spawned on kill of flagged enemy
Shield / freeze	—	Frame-count timers; freeze stops all enemy movement and AI
Spawn animation	`$DDA0`	Cycling tile pattern over ~60 frames before tank appears
Death animation	`$DE64 DeathAnimTick`	Expanding ring of colored rects, 4 phases
Stage clear	`$C728 CheckGameOver`	All 20 enemies defeated → victory scroll
Game over	`$C728 CheckGameOver`	Eagle destroyed or all lives lost → GAME OVER sprite scroll

BRICK DESTRUCTION MODEL

Each metatile cell stores a 4-bit mask (brickBits) representing which 8×8 quadrants remain: TL=bit0, TR=bit1, BL=bit2, BR=bit3. When a bullet hits, the mask for the struck quadrant(s) is cleared. The tile is re-classified based on which bits remain:

All bits 0 → EMPTY
Only right column bits → BRICK_R
Only bottom row bits → BRICK_B
Only left column bits → BRICK_L
Only top row bits → BRICK_T

This exactly mirrors the ROM's $D745 SubTileBitmask system.

SOUND

All sound effects are synthesized at runtime using the Web Audio API — no audio files. Each SFX recreates the 2A03 channel behavior:

Square channels — used for engine idle hum, bullet fire, explosions, power-up jingle
Noise channel — used for explosion rumble
SFX are triggered by boolean flags mirroring ROM RAM addresses $030B–$030D
Engine sound plays continuously while a tank is moving, stops when idle

CONSTRUCTION MODE

A level editor (Famicom-exclusive feature) is implemented as a game state. The 13×13 grid is editable with cursor navigation; the current tile type cycles through all terrain types. Custom maps are stored in JS memory and passed directly to the stage loader — no serialization.

FIDELITY NOTES

All 35 stage maps decoded from ROM nibble table and verified tile-by-tile
Eagle wall geometry (Π-shape, 5 metatile cells) confirmed against pixel-position analysis of ROM nametable writes
Enemy spawn positions (3 fixed spawn points), player spawn positions, and eagle position are hardcoded ROM values
Spawn delay formula: max(50, 186 − stageIndex × 4 − (2P ? 20 : 0)) frames — ROM $C3A2: $BE − stage × 4; 2P penalty $C3B0: SBC #$14
Enemy type distribution per stage from ROM $EA51 EnemyTypeTable (20 entries per stage)
Score values per tank type match ROM $D9E1 SetupScoreDigits BCD encoding
NTSC overscan (8px top/bottom) replicated via CSS clip on the canvas wrapper