Canvas Game Arcade

A multi-game arcade platform with 52 playable games built with TypeScript and HTML5 Canvas (Vite).

Tutorial Series

Follow the step-by-step tutorial series to build all 50 games from scratch — ordered from beginner to advanced. Perfect for YouTube content creators and learners.

Browse the concept reference for standalone explainers on every math, algorithm, physics, and design pattern concept used.

Quick Start

pnpm install
pnpm dev        # http://localhost:3000
pnpm build      # production build

Games (52)

Arcade (16)

Game	Description	Tutorial	Key Concepts
Snake	Eat food, grow longer, avoid yourself	Tutorial (5 steps)	State Machines, Delta Time
Breakout	Paddle + ball, break bricks, powerups	Tutorial (6 steps)	AABB Collision, Angle Reflection
Asteroids	Rotate, thrust, shoot splitting rocks	Tutorial (6 steps)	Trigonometry, Momentum
Space Invaders	Shoot descending aliens, shield cover	Tutorial (6 steps)	Wave System
Flappy Bird	Tap to fly through pipe gaps	Tutorial (5 steps)	Gravity, Terminal Velocity
Tetris	Stack blocks, clear lines	Tutorial (7 steps)	Matrix Rotation, DAS
Whack-a-Mole	Timed reflex clicking	Tutorial (4 steps)	Combo System
Helicopter	One-button cave scroller	Tutorial (4 steps)	Velocity
Pong	Paddle tennis vs AI or 2-player	Tutorial (5 steps)	Bounce, Vectors
Pac-Man	Eat dots, avoid/eat ghosts	Tutorial (7 steps)	Pathfinding, Strategy Pattern
Doodle Jump	Endless vertical platform jumping	Tutorial (5 steps)	One-Way Platforms, Screen Wrap
Rhythm Tap	Tap shrinking circles in time	Tutorial (5 steps)	Sine Wave
Reaction Timer	Test your reflexes	Tutorial (3 steps)	Canvas Setup, localStorage
Balloon Pop	Click balloons before they escape	Tutorial (4 steps)	Circle Collision
Color Switch	Pass through matching color gates	Tutorial (5 steps)	Transforms
Frogger	Cross roads and rivers	Tutorial (6 steps)	Layered Rendering
Typing Speed	Type falling words	Tutorial (5 steps)	Text Rendering

Action (9)

Game	Description	Tutorial	Key Concepts
Tower Defense	Place towers, survive enemy waves	Tutorial (8 steps)	Economy, Wave System
Platformer	Jump, collect coins, stomp enemies	Tutorial (7 steps)	Camera, Gravity
Top-Down Shooter	WASD + mouse aim, wave survival	Tutorial (6 steps)	Trigonometry, Particles
Zombie Survival	Day/night cycle, barricades, ammo	Tutorial (7 steps)	Day/Night, Fog of War
Racing	Top-down track with AI opponents	Tutorial (7 steps)	Friction, Momentum
Fruit Ninja	Slice flying fruit, avoid bombs	Tutorial (5 steps)	Line Intersection, Quadratic
Lava Floor	Platforms sink into lava	Tutorial (5 steps)	One-Way Platforms
Basketball	Drag to aim, physics arc shooting	Tutorial (5 steps)	Projectile Motion, Parametric Equations
Golf	Top-down mini golf, 9 holes	Tutorial (6 steps)	Friction, Reflection

Puzzle (14)

Game	Description	Tutorial	Key Concepts
Physics Puzzle	Place pieces, simulate gravity	Tutorial (6 steps)	AABB Collision, Gravity
Minesweeper	Reveal cells, flag mines	Tutorial (5 steps)	Flood Fill, Probability
Match-3	Swap gems, cascade combos	Tutorial (6 steps)	Combo System, Lerp
2048	Slide + merge number tiles	Tutorial (5 steps)	Colors & Gradients
Sokoban	Push boxes onto targets	Tutorial (5 steps)	Stack (Undo)
Maze Runner	Fog of war, timed procedural mazes	Tutorial (5 steps)	Maze Generation, Fog of War
Word Search	Find hidden words in letter grid	Tutorial (5 steps)	Coordinate Systems
Sudoku	9x9 number placement, 3 difficulties	Tutorial (6 steps)	Backtracking, Factory
Pipe Connect	Rotate pipes to connect water flow	Tutorial (5 steps)	Flood Fill
Lights Out	Toggle adjacent lights off	Tutorial (4 steps)	Shapes & Paths, Shadows
Memory Match	Flip cards to find pairs	Tutorial (5 steps)	Shuffle, Rounded Rects
Simon Says	Repeat growing color sequences	Tutorial (4 steps)	Circles & Arcs
Gravity Ball	Toggle gravity direction	Tutorial (5 steps)	Level Progression
Hangman	Guess the word letter by letter	Tutorial (4 steps)	Text Rendering

Strategy (7)

Game	Description	Tutorial	Key Concepts
City Builder	Manage population, food, power, happiness	Tutorial (6 steps)	Economy, Registry
Card Battle	Draw cards, defeat AI enemies	Tutorial (6 steps)	State Pattern
Ant Colony	Emergent ant simulation	Tutorial (6 steps)	Pheromones, Cellular Automata
Tic-Tac-Toe	Unbeatable minimax AI	Tutorial (5 steps)	Minimax
Connect Four	Drop discs, connect 4 vs AI	Tutorial (5 steps)	Minimax, Transparency
Chess	Full rules, castling, en passant, promotion UI	—	Minimax, State Machines
Checkers	Forced captures, multi-jump chains, king promotion	—	Minimax, Stack (Undo)

Chill (6)

Game	Description	Tutorial	Key Concepts
Fishing	Cast, hook timing, reel tension	Tutorial (5 steps)	Weighted Random, Sine Wave
Idle Clicker	Click + buy upgrades, persistent	Tutorial (5 steps)	Exponential Growth, localStorage
Particle Sand	Sand/water/fire cellular automata	Tutorial (5 steps)	Cellular Automata, Image Data
Brick Builder	LEGO-like creative stacking	Tutorial (4 steps)	Responsive Canvas
Pixel Art	Draw pixel art with palette	Tutorial (4 steps)	Flood Fill, Coordinate Systems

Concept Reference (76 pages)

Learn the foundations behind every game. Each page has plain-English explanation, formulas, TypeScript code, and links to games where it's used.

Category	Pages	Topics
Canvas API	15	Setup, Shapes, Arcs, Colors, Text, Transforms, Transparency, Glow, Clipping, Pixels, Rounded Rects, Animation, Coords, Layers, Responsive
Mathematics	12	Trig, Vectors, Distance, Lerp, Parametric, Reflection, Modular, Quadratic, Probability, Matrix Rotation, Exponential, Sine Wave
Algorithms	15	Flood Fill, Minimax, Backtracking, Maze Gen, Shuffle, AABB, Circle-Rect, Circle-Circle, Line-Segment, Pathfinding, Cellular Automata, State Machines, Delta Time, Weighted Random, Stack/Queue
Design Patterns	9	SOLID, Adapter, Observer, State, Factory, Strategy, ECS, Registry, Template Method
Physics	9	Gravity, Velocity, Friction, Momentum, Bounce, Terminal Velocity, Screen Wrap, One-Way Platforms, Projectile Motion
Game Systems	10	Waves, Economy, Combos, Levels, Camera, Particles, Day/Night, Fog of War, Pheromones, DAS
Engineering	6	Event Lifecycle, RAF Loop, localStorage, Path Aliases, Vite, Canvas API

Browse all 76 concept pages

Project Structure

src/
├── main.ts                     # Platform entry point
├── platform/
│   ├── GameRegistry.ts         # Record<GameCategory, GameDefinition[]>
│   ├── GameLauncher.ts         # Create/destroy game instances
│   └── PlatformMenu.ts        # Game selector with category tabs
├── shared/
│   ├── GameInterface.ts        # GameDefinition + GameInstance + GameHelp
│   ├── HelpOverlay.ts          # Shared in-game help renderer
│   ├── Updatable.ts            # System interface
│   ├── Renderable.ts           # Renderer interface
│   └── InputHandler.ts         # Input handler interface
└── games/
    └── <game-name>/            # Each game is self-contained
        ├── index.ts            # GameDefinition export
        ├── types.ts            # Game-specific types + constants
        ├── <Game>Engine.ts     # Game loop orchestrator
        ├── adapters/
        │   └── PlatformAdapter.ts
        ├── systems/            # Game logic (Updatable)
        ├── renderers/          # Drawing (Renderable)
        └── data/               # Static data (levels, words, etc.)

Adding a New Game

1. Create the game folder

mkdir -p src/games/my-game/{systems,renderers,adapters,data}

2. Define types

// src/games/my-game/types.ts
export interface MyGameState {
  score: number;
  // ... your game state
}

3. Create systems

Each system implements Updatable<MyGameState>:

// src/games/my-game/systems/PhysicsSystem.ts
import type { Updatable } from '@shared/Updatable';
import type { MyGameState } from '../types';

export class PhysicsSystem implements Updatable<MyGameState> {
  update(state: MyGameState, dt: number): void {
    // game logic here
  }
}

4. Create renderers

Each renderer implements Renderable<MyGameState>:

// src/games/my-game/renderers/GameRenderer.ts
import type { Renderable } from '@shared/Renderable';
import type { MyGameState } from '../types';

export class GameRenderer implements Renderable<MyGameState> {
  render(ctx: CanvasRenderingContext2D, state: MyGameState): void {
    // draw here
  }
}

5. Create input handler

// src/games/my-game/systems/InputSystem.ts
import type { InputHandler } from '@shared/InputHandler';

export class InputSystem implements InputHandler {
  attach(): void { /* add event listeners */ }
  detach(): void { /* remove event listeners */ }
}

6. Create the engine

Wire systems + renderers in a requestAnimationFrame loop.

7. Create the adapter

// src/games/my-game/adapters/PlatformAdapter.ts
import type { GameInstance } from '@shared/GameInterface';
import { MyGameEngine } from '../MyGameEngine';

export class PlatformAdapter implements GameInstance {
  private engine: MyGameEngine;
  constructor(canvas: HTMLCanvasElement, onExit: () => void) {
    this.engine = new MyGameEngine(canvas, onExit);
  }
  start(): void { this.engine.start(); }
  destroy(): void { this.engine.destroy(); }
}

8. Export the GameDefinition

// src/games/my-game/index.ts
import type { GameDefinition } from '@shared/GameInterface';
import { PlatformAdapter } from './adapters/PlatformAdapter';

export const MyGame: GameDefinition = {
  id: 'my-game',
  name: 'My Game',
  description: 'Short description',
  icon: '🎮',
  color: '#ff5722',
  category: 'arcade',  // arcade | action | puzzle | strategy | chill
  help: {
    goal: 'What the player needs to do.',
    controls: [
      { key: 'Arrow Keys', action: 'Move' },
      { key: 'Space', action: 'Action' },
      { key: 'ESC', action: 'Exit to menu' },
    ],
    tips: [
      'Helpful tip for new players',
    ],
  },
  create(canvas, onExit) {
    const inst = new PlatformAdapter(canvas, onExit);
    inst.start();
    return inst;
  },
};

9. Register in the GameRegistry

// src/platform/GameRegistry.ts
import { MyGame } from '@games/my-game';

// Add to the appropriate category array:
export const GAME_REGISTRY: Record<GameCategory, GameDefinition[]> = {
  arcade: [
    // ...existing games
    MyGame,
  ],
};

Checklist

• All event listeners removed in destroy() / detach()
• Uses @shared/... path aliases (not relative ../../shared/)
• No constructor parameter properties (erasableSyntaxOnly)
• help field with goal, controls, and tips
• category field set
• ESC key exits to platform menu
• npx tsc --noEmit passes with zero errors

Path Aliases

Alias	Maps to
@shared/*	src/shared/*
@platform/*	src/platform/*
@games/*	src/games/*

Architecture (SOLID)

Principle	Application
Single Responsibility	Each system/renderer does one thing
Open/Closed	New mechanics = new system files
Liskov Substitution	All games implement GameInstance
Interface Segregation	Updatable, Renderable, InputHandler
Dependency Inversion	Systems depend on state interfaces, not engine

Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b feat/my-new-game
3. Add your game following the steps above
4. Ensure npx tsc --noEmit and pnpm build pass
5. Commit following the Commit Convention below
6. Open a pull request

Guidelines

• One game per PR for clean review
• SOLID architecture — separate systems, renderers, adapters
• Clean up listeners — all event handlers must be removed on destroy()
• Help data required — every game needs goal, controls, and tips
• No external dependencies — pure TypeScript + Canvas API only
• Test locally — run pnpm dev, verify the game launches, plays, and exits cleanly

Commit Convention

We use Conventional Commits. The release script auto-generates changelogs from these prefixes:

Prefix	Category	When to use	Example
feat:	New Games & Features	New game, new platform feature, new tutorial	feat: add Chess game (#51) — full rules, minimax AI
fix:	Bug Fixes	Bug fix, rule correction, UX fix	fix: first-row game cards not clickable
perf:	Performance	Optimization, code splitting, caching	perf: code-split all 52 games via dynamic import()
docs:	Documentation	Tutorials, README, concept pages	docs: write Tetris tutorial (Game 24) — 7 steps
refactor:	Refactoring	Code restructure without behavior change	refactor: use Record for game registry
chore:	Other Changes	Config, tooling, CI, dependencies	chore: setup eslint, prettier, husky

Format:

<prefix>: <short description> (under 72 chars)

Optional longer body explaining the "why" after a blank line.

Co-Authored-By: Name <email>

Branch naming:

feat/game-name        # new game
fix/bug-description   # bug fix
docs/tutorial-name    # documentation
perf/optimization     # performance
chore/config-change   # tooling

Releases

See RELEASE.md for the full release workflow. Quick reference:

pnpm release:patch   # 1.0.0 → 1.0.1 (bug fixes)
pnpm release:minor   # 1.0.0 → 1.1.0 (new games/features)
pnpm release:major   # 1.0.0 → 2.0.0 (breaking changes)

The release script auto-generates CHANGELOG.md with clickable commit hashes and author attribution from your commit messages.

Tech Stack

• TypeScript — strict mode, zero errors
• Vite — dev server + production build
• HTML5 Canvas — all rendering
• No frameworks — pure vanilla TS

License

MIT