Top-Down Mini Racers

A Micro Machines-inspired top-down arcade racing game where toy cars race across a kitchen table, dodging everyday obstacles like salt shakers, cups, and plates.

Built with Phaser 3 and a clean hexagonal architecture that keeps all game logic framework-agnostic and fully testable.

<p align="center"> <img src="screenshots/menu.png" alt="Main Menu" width="380" /> <img src="screenshots/racing.png" alt="Race Start" width="380" /> </p> <p align="center"> <img src="screenshots/gameplay.png" alt="Mid-Race Gameplay" width="380" /> </p>

Features

• 4 playable cars with unique stats (Red Racer, Blue Blitz, Green Machine, Golden Thunder)
• 2 tracks - Kitchen Table Grand Prix and Breakfast Speedway
• 3 power-ups - Nitro Boost, Oil Slick, and Homing Missile
• Drift physics with grip-based steering and realistic slide mechanics
• AI opponents with obstacle avoidance and rubber-band difficulty
• Procedural pixel art - all textures generated at runtime via Canvas2D
• Visual effects - skid marks, speed lines, screen shake, particle effects, vignette overlay
• 87 unit & integration tests covering core systems, physics, collision, and AI

Getting Started

Prerequisites

• Node.js (v18+)

Install & Run

git clone https://github.com/jonathanleahy/micro-machines.git
cd micro-machines
npm install
npm run dev

Opens at http://localhost:3000.

Controls

Build & Test

npm run build        # Production build to dist/
npm test             # Run tests once
npm run test:watch   # Run tests in watch mode

Architecture

The project follows a hexagonal (ports & adapters) pattern:

src/
├── core/                    # Framework-agnostic game logic
│   ├── entities/            # Car, Track, Race, PowerUp, Obstacle
│   ├── systems/             # RaceManager, PhysicsEngine, CollisionSystem, AIDriver
│   ├── ports/               # Abstract interfaces (Renderer, Input, Audio)
│   ├── data/                # Car configs, power-up configs, track definitions
│   └── utils/               # Vector math, geometry, math helpers
├── adapters/
│   ├── phaser/              # Phaser 3 implementations
│   │   ├── scenes/          # Boot, Menu, Race, Results
│   │   ├── sprites/         # TextureGenerator, CarSprite, TrackRenderer
│   │   ├── effects/         # Particles, skid marks, post-processing
│   │   └── hud/             # Lap counter, speed, position display
│   └── null/                # Test adapters (no browser needed)
├── shared/                  # Constants shared across layers
└── main.js                  # Phaser config & entry point

Core logic has zero framework dependencies and runs entirely in Node for testing. Adapters handle rendering, input, and audio through well-defined port interfaces. Swap Phaser for any renderer without touching game logic.

How It Works

Race loop (managed by RaceManager):

AI drivers follow track waypoints, brake for sharp turns, dodge obstacles using perpendicular distance scanning, and use rubber-banding to keep races competitive.

Drift model: each car has a grip value that controls how quickly the movement angle aligns with the facing angle. Lower grip = more slide.

License

MIT