Arcade Hub

Pick a game. Play instantly.

A modern, lightweight, high-performance browser arcade platform built with Next.js 16 (App Router), React 19, Tailwind CSS v4, and Strict TypeScript.
Featuring 12 original instant web games, zero sign-ups, zero tracking, instant code-split chunk loading, and procedurally synthesized audio.

---

Table of Contents

• Game Catalog (12 Games)
  • 1. Dino Runner
  • 2. Snake
  • 3. Tic-Tac-Toe
  • 4. Minesweeper
  • 5. Memory Match
  • 6. Breakout
  • 7. Pong
  • 8. 2048
  • 9. Flappy Fly
  • 10. Basketball Shot
  • 11. Soccer Penalty Shootout
  • 12. Cricket Hit
• Unified Game Shell
• Core Platform Highlights
• Architecture & Engine Design
• Quick Start & Development
• Adding a New Game (Plugin System)
• Quality Gates & Testing
• Asset Licensing & Original IP

---

Game Catalog

All 12 games are original implementations engineered with custom Canvas/DOM renderers and procedural Web Audio sound synthesis — no copyrighted assets, scraped code, or external dependencies.

1. Dino Runner _{endless reaction jump}

Jump and duck through an endless prehistoric desert. Obstacle density and velocity scale progressively as you survive longer. Personal best score is saved locally.

• Controls:
  • Desktop: Space / ↑ to Jump · ↓ to Duck · Space to Restart
  • Mobile: Tap screen to jump
• Highlights: Dynamic obstacle generation, realistic gravity physics, ducking collision box adaptation.

---

2. Snake _{arcade classic grid}

Slither across the grid, devour food pellets, and grow. Prevent 180° self-collisions and avoid crashing into grid boundaries.

• Controls:
  • Desktop: ↑ ↓ ← → / W A S D
  • Mobile: Swipe in 4 directions or use on-screen D-pad
• Highlights: Buffered input queue to prevent self-reversals, high score tracking, smooth grid rendering.

---

3. Tic-Tac-Toe _{strategy puzzle ai}

Classic three-in-a-row strategy. Challenge a friend locally or play against an unbeatable Minimax AI with 3 difficulty modes.

• Controls:
  • Desktop: Click any cell or navigate with keyboard arrows + Enter
  • Mobile: Tap any grid cell
• Highlights: Minimax AI engine with proven zero-loss rate on hard mode, accessible keyboard cursor navigation.

---

4. Minesweeper _{puzzle logic classic}

Clear the board without detonating any hidden mines. Uncover numerical clues indicating adjacent explosive threats.

• Controls:
  • Desktop: Left-Click to reveal · Right-Click to place/remove Flag
  • Mobile: Tap to reveal · Toggle Flag Mode button to place flags
• Highlights: Guaranteed first-click safety, recursive flood-fill reveals, 3 board size presets (Beginner, Intermediate, Expert).

---

5. Memory Match _{puzzle memory cards}

Flip cards, find all matching symbol pairs, and clear the board in record time and moves.

• Controls:
  • Desktop: Click cards to reveal
  • Mobile: Tap cards to flip
• Highlights: 3D CSS card-flip transitions, move counter, match timer, seedable procedural deck shuffler.

---

6. Breakout _{arcade retro physics}

Demolish walls of bricks with a bouncing ball and paddle. Angle shots off paddle edges to curve your trajectory.

• Controls:
  • Desktop: ← / → or A / D or Mouse movement
  • Mobile: Touch & drag paddle horizontally
• Highlights: Sub-stepped continuous collision detection (zero tunneling through thin bricks), particle brick destruction.

---

7. Pong _{sports retro 2-player}

The definitive table tennis duel. Face off against an adaptive CPU opponent — first to 7 points claims victory.

• Controls:
  • Desktop: W / S or ↑ / ↓
  • Mobile: Drag paddle vertically
• Highlights: Dynamic deflection angle based on point of contact, smoothing CPU tracking AI, rally speed multiplier.

---

8. 2048 _{puzzle strategy numbers}

Slide and merge matching number tiles to reach the legendary 2048 tile and beyond.

• Controls:
  • Desktop: ↑ ↓ ← → / W A S D
  • Mobile: Swipe in 4 directions
• Highlights: Pure engine sliding/merging matrix, tile spawn animations, local best score tracking.

---

9. Flappy Fly _{arcade endless reaction}

Tap to flap your wings and pilot through treacherous pipe obstacles in an endless scrolling sky.

• Controls:
  • Desktop: Space / Left Click to flap
  • Mobile: Tap screen to flap
• Highlights: Crisp velocity impulses, pipe gap randomization, collision bounds testing.

---

10. Basketball Shot _{sports physics aim}

Drag, aim trajectory arc, and flick swishes before the 30-second shot clock expires.

• Controls:
  • Desktop: Click & Drag back to aim shot trajectory, release to shoot
  • Mobile: Touch & Drag backwards to aim, release to shoot
• Highlights: Realistic parabola physics, rim bouncing, net swish detection, streak multipliers.

---

11. Soccer Penalty Shootout _{sports aim reaction}

Step up to the penalty spot. Beat the agile goalkeeper across 5 dramatic penalty kick rounds.

• Controls:
  • Desktop: Click a goal target zone (corners, top, bottom)
  • Mobile: Tap a goal zone
• Highlights: Goalkeeper dive estimation AI, shot trajectory animation, round outcome indicator.

---

12. Cricket Hit _{sports timing reaction}

Time your swing precisely as the bowler bowls. Connect to strike 4s and 6s — mistime it and lose your wicket!

• Controls:
  • Desktop: Space / Left Click to swing bat
  • Mobile: Tap screen to swing bat
• Highlights: Bowling speed variation, sweet-spot timing physics, run score accumulator.

---

Unified Game Shell

Every game in the platform runs inside a unified, battle-tested chrome container (GameShell):

• True Instant Pause: Press P or click the toolbar button in any game to instantly freeze the simulation and display the pause overlay.
• Global Web Audio Synthesizer: Real-time procedural audio generation for clicks, jumps, scores, hits, and game-overs. Global mute toggle persists across page transitions.
• Robust High Score Storage: Safe, schema-versioned localStorage score repository with beforeunload / pagehide auto-flushing so closing a tab never loses a personal best.
• Adaptive Input Bridge: Automatic device detection providing keyboard events on desktop, swipe gestures, and virtual on-screen controls on touchscreens.

---

Core Platform Highlights

• True Per-Game Code Splitting: Every game is lazily loaded on demand via Next.js dynamic chunk loading. The home and catalog routes bundle zero game engine code.
• Progressive Enhancement: The catalog (game cards, category filtering, search, about page) is fully server-rendered and works seamlessly with JavaScript disabled.
• Modern Dark & Light UI: Polished neon dark mode and crisp light mode styling built with Tailwind CSS v4 and CSS variables.
• Accessibility & Keyboard Focus: Comprehensive ARIA live regions, focus-visible outlines, and screen-reader labeled game states.
• SEO & Metadata Ready: Dynamic OpenGraph preview tags, structured schema, robots.txt, and automated sitemap.xml generation.

---

Architecture & Engine Design

src/
├── app/                  # Next.js 16 App Router (/, /games, /games/[slug], /categories, /about)
├── components/
│   ├── game/             # GameHost, GameShell, GameToolbar, GameCard, ScoreBoard
│   └── layout/           # Header, Footer, ThemeToggle, Navigation
├── games/
│   ├── core/             # Sanctioned game loop (useGameLoop), Audio synth, RNG, Storage
│   └── <slug>/           # 12 Self-contained game modules
│       ├── engine/       # Pure TypeScript game rules (0 DOM/React dependencies)
│       ├── renderer.ts   # Canvas / DOM rendering logic
│       ├── component.tsx # Game UI & interaction bridge
│       └── index.ts      # GameDefinition manifest export
├── registry/games.ts     # Single source of truth catalog registry
└── types/game.ts         # TypeScript plugin contract & interfaces

Pure Engine vs Renderer Separation

1. Pure Engine Logic: Game logic in engine/ has zero React/DOM dependencies. It operates on immutable state transitions and is injected with a seeded deterministic RNG (Prng) for 100% reproducible unit tests.
2. Standardized Game Loop: useGameLoop manages requestAnimationFrame with delta-time clamping, visibility auto-pausing (document.hidden), and StrictMode safe lifecycle cleanup.

---

Quick Start & Development

Prerequisites

• Node.js: ≥ 22.13.0
• Package Manager: pnpm ≥ 11.0.0

Installation & Run

# Clone repository
git clone https://github.com/JasonTM17/Arcade_Hub_Game.git
cd Arcade_Hub_Game

# Install dependencies
pnpm install

# Start development server (Turbopack)
pnpm dev

Open http://localhost:3000 in your browser.

Available Scripts

Command	Description
pnpm dev	Start Next.js Turbopack development server
pnpm build	Create optimized production build
pnpm start	Run production server
pnpm lint	Run ESLint check (0 errors required)
pnpm typecheck	Run TypeScript strict type verification
pnpm test	Run 227 Vitest unit tests
pnpm test:watch	Run Vitest in interactive watch mode
pnpm test:e2e	Run 64 Playwright end-to-end tests
pnpm format	Auto-format codebase with Prettier
pnpm format:check	Verify formatting consistency

---

Adding a New Game (Plugin System)

Adding a game to Arcade Hub requires only 4 straightforward steps:

1. Create Module: Add src/games/<slug>/ containing engine/, renderer.ts, component.tsx, and index.ts exporting a GameDefinition.
2. Register Game: Import and append your GameDefinition to gameRegistry in src/registry/games.ts.
3. Register Host Loader: Add one lazy import line to GAME_LOADERS in src/components/game/game-host.tsx.
4. Add Asset: Place an SVG icon at public/games/<slug>.svg.

The TypeScript compiler enforces that all slugs match the registry, preventing runtime 404s.

---

Quality Gates & Testing

Every pull request and commit passes rigorous automated CI pipelines:

• Unit Tests: 227 Vitest tests covering core math, random seeds, score storage, audio synth, and all 12 game engine state machines (including unbeatable Minimax AI proofs).
• E2E Tests: 64 Playwright tests covering desktop browsers, mobile viewports (Pixel 5), keyboard navigation, pause overlays, and JavaScript-disabled catalog rendering.
• Strict Linting & Typing: Strict TypeScript mode with noEmit and zero ESLint warnings.

# Run the full validation suite locally
pnpm lint && pnpm typecheck && pnpm test && pnpm build

---

Asset Licensing & Original IP

Arcade Hub generates 100% of its visual assets, thumbnails, and audio procedurally at runtime via the Canvas API, custom SVG, and the Web Audio API.

• No scraped copyrighted game code or sprites.
• No third-party sound packs or external font dependencies.
• See docs/ASSET_LICENSES.md for full compliance details.

---

Arcade Hub · Crafted with Next.js, React 19 & TypeScript.