Neural Racer

Neural Racer is a PixiJS-powered 2D racing sandbox where neural network populations learn to drive through neuroevolution. It loads SVG tracks, spawns simulated cars, and iteratively improves their controllers via evolutionary strategies (elite carryover, crossover, mutation, hall of fame).

Live demo: jamro.github.io/neural-racer

Project trailer & explanation (YouTube): youtu.be/Vc70yLcZxmE

What it does

• Renders a track and cars with PixiJS.
• Simulates driving physics and sensors for many cars in parallel.
• Evolves neural controllers over generations (standard, hall-of-fame, all-track modes) via genetic algorithms.
• Persists evolution progress locally so runs can resume.

Screenshots

1. Race simulation
   

2. Evolution screen
   

3. Neural network preview & test
   

Prerequisites

• Node.js 18+ (recommended) and npm.
• A browser with WebGL enabled.

Install

From the repository root:

npm install

Run (development)

Start the dev server with hot reload:

npm run dev

Then open http://localhost:3000.

Build (production)

npm run build

Outputs go to dist/ (served by your host of choice).

Lint

Run ESLint across src/:

npm run lint

Apply auto-fixes where possible:

npm run lint:fix

Tests

Unit tests run with Jest:

npm test

Project layout (quick map)

• src/index.js – entrypoint wiring the app and HMR.
• src/app/Application.js – boot sequence: preload, renderer init, track load, evolution loop.
• src/engine/simulation – car physics, sensors, track interaction, view scaling.
• src/engine/evolution – generations, epoch runners, hall of fame, persistence.
• src/presentation – UI overlays (evo lab, previews, controls).
• src/resources – assets, preloader UI, and loader modules (SVG track parsing under src/resources/loaders/track).
• public/tracks/*.svg – sample tracks loaded at startup.

Documentation

• Evolution System – Genetic algorithm design, operators, and multi-track strategies
• Neural Network Architecture – Controller design, inputs, outputs, and normalization
• Physics Model – Vehicle dynamics, forces, and simulation details
• Persistence & Storage – How evolution state is saved and compressed
• Project Learnings – Practical insights and lessons from development

Architecture

See docs/architecture.md for high-level flow, domains, and data movement.

Development guide

See docs/dev_guide.md for workflows (tracks, assets, config, testing, performance).

Tech stack

• PixiJS 8 for rendering
• Webpack 5 + Webpack Dev Server for bundling and HMR