Binding-Fignyaac/docs/ARCHITECTURE.md

Architecture

Overview

The game is a single-page Canvas 2D application. The source is written in TypeScript and split into ~19 modules under src/, bundled by Bun into a single dist/main.js. The HTML shell in dist/index.html loads the bundle.

Module Dependency Graph

main.ts
  ├── input.ts           (global KEYS, setupInput)
  └── Game.ts
        ├── constants.ts (all shared numeric constants)
        ├── types.ts     (Dir, RoomType, CombatMode, Box, Doors)
        ├── math.ts      (shuffle, rand, ri, dist, overlap)
        ├── RoomMap.ts   → Room.ts, tiles.ts, doors.ts
        ├── Player.ts
        ├── Enemy.ts
        ├── Tear.ts
        ├── MeleeSwing.ts
        ├── collision.ts → Room.ts, tiles.ts
        ├── transitions.ts → Game.ts (type only), input.ts
        ├── spawner.ts   → Room.ts, Enemy.ts
        └── render/*
              → roomRenderer.ts, entityRenderer.ts,
                hudRenderer.ts, minimapRenderer.ts

Game Loop

Every frame (requestAnimationFrame):

1. Timers — decrement invTimer, atkCD, transCD
2. Movement — read WASD, apply velocity, resolve wall collisions
3. Attack — read arrow keys / Space, fire tear or create melee swing
4. Melee Update — decrement swing life, apply damage + knockback
5. Tear Update — move projectiles, check wall/enemy collisions
6. Enemy AI — chase player, contact damage with cooldown
7. Room Clear — if all enemies dead → room.cleared = true, rebuild tiles with doors
8. Transition Check — if player on door tile + key pressed → load adjacent room
9. Win Check — if boss room cleared → won = true
10. Render — draw room tiles → entities → HUD → minimap → overlays

Transition System

Room transitions are the most complex subsystem. Key design:

• Door geometry: DOOR constant defines 3-tile-wide openings at each cardinal edge (top: cols 6-8, row 0; bottom: cols 6-8, row 10; left: rows 4-6, col 0; right: rows 4-6, col 14).
• Detection: checkTransition() computes the player's tile position (col, row). If they're on a door tile AND pressing the matching movement key, the transition fires.
• Cooldown: transCD = 15 prevents re-entry within 15 frames.
• Movement lock: Transition only works in cleared rooms (room.cleared === true).
• Collision bypass: isBlocked() returns false for out-of-bounds tiles at door openings, letting the player's bounding box extend beyond the room boundary.

Collision System

• isBlocked(room, col, row) — per-tile check. Returns true for wall tiles and out-of-bounds positions, except at door openings.
• collidesWall(box, room, ox, oy) — iterates all tiles covered by the entity's bounding box. If any tile is blocked, returns true.
• Movement resolves axis-independently: apply X, revert if collision; apply Y, revert if collision.

Room Generation

RoomMap.generate() uses a random walk:

1. Start at (0,0) with a spawn room.
2. Maintain a frontier list of rooms that have room to expand.
3. Each step, pick a random frontier room, shuffle directions, and attempt to add a new room in an unoccupied adjacent cell within the 7×7 grid.
4. Room types are assigned probabilistically (boss at ~20%, treasure at ~12%, rest normal).
5. If no boss room was generated, one normal room is promoted.

Rendering

Rendering is split into 4 stateless functions, each taking CanvasRenderingContext2D as the first argument:

• roomRenderer — tile loop with wall/door/floor styles
• entityRenderer — enemies (3 types), player (body + weapon), tears, melee swing arc
• hudRenderer — HP bar, mode indicator, enemy count, room label
• minimapRenderer — 7×7 grid with visited/current room highlights

Weapon Visuals

• Pistol (ranged): Barrel line + body rect, rotated toward facing direction. Muzzle flash circle at atkCD > 8.
• Knife (melee): Triangular blade + handle + guard rects, offset in facing direction.

Enemy Types

Type	Size	HP	Speed	Damage	Visual
Normal	32px	3	1.15	1	Brown block, yellow eyes
Fast	26px	2	1.9	1	Red circle, small eyes
Boss	46px	10	0.9	2	Large red circle, horns, HP bar

State Management

• GAME_OVER / WON — boolean flags checked in loop and render.
• KEYS — global mutable map, reset on window blur.
• Room state (cleared, visited, enemies[], tears[]) — per-room.
• Player state (hp, mode, facing, transCD, etc.) — single Player instance.
• Cooldowns (invTimer, atkCD, transCD) decrement each frame.

Build Pipeline

bun build src/main.ts --outdir dist --target browser --minify
cp src/index.html dist/

• Bundler: Bun's native bundler (esbuild under the hood).
• Target: browser (ES module → IIFE/global wrapper).
• Result: single dist/main.js (~30 KB) + dist/index.html.
• Open dist/index.html directly in any modern browser.