This simulator models urban road traffic using two well-established traffic science algorithms — the Intelligent Driver Model (IDM) for car-following physics and MOBIL for lane-change decisions — running entirely in the browser with no dependencies. A built-in map editor lets you draw your own road networks from scratch. The documents below cover the theory behind each model, how it is implemented in the code, design decisions made along the way, and ideas for future development.
The master developer reference for the entire application. Covers the full architecture, file structure, script load-order dependency chain, all key algorithms in summary form, UI control mappings, known quirks and gotchas, and a catalogue of future enhancement ideas organised by theme.
A deep-dive into the physics engine that controls how fast each car goes, how it follows the car ahead, and how it brakes for red lights. Covers the full mathematical formula, every parameter, the stop-line braking extension, emergent traffic behaviours like stop-and-go waves, numerical integration, and ideas for future enhancements.
A comprehensive guide to MOBIL — the model that decides when a car should change lanes for speed gain. Explains the safety gate and incentive criterion, the politeness factor, how MOBIL interacts with turn-lane positioning, the cooldown timer, three bugs found and fixed during development, and potential future improvements.
Full documentation of how cars physically move between lanes. Explains the three-slot trajectory state machine (current / next / temp), the cubic Bézier curve geometry that produces smooth lane transitions, how traffic signals integrate with crossings, the acquire/release registration system, and seven identified enhancement opportunities with implementation sketches.
| File | Purpose |
|---|---|
| js/Settings.js | All global constants — colours, grid size, IDM defaults, MOBIL parameters, signal interval |
| js/model/Car.js | Vehicle class — IDM acceleration, MOBIL lane-change evaluation, turn signal state, per-tick move() |
| js/model/Trajectory.js | Three-slot lane position state machine — intersection crossings, voluntary lane changes, stop-line braking |
| js/model/Lane.js | Single directional lane — car registration, following-distance queries, MOBIL gap queries |
| js/model/ControlSignals.js | 4-phase traffic signal cycling per intersection — phase table, timing randomisation |
| js/model/World.js | Simulation engine — car/road/intersection pools, random grid map generation, beltway, main tick; removeRoad / removeIntersection for map editor deletions |
| js/geom/Curve.js | Cubic Bézier curve — De Casteljau evaluation, arc-length approximation used for lane-change paths |
| js/visualizer/Visualizer.js | Render loop — draws grid, roads, signals, cars (including turn-signal stripes), debug overlays; map editor state machine and overlays (ghost intersections, hover/selection rings) |
| js/App.js | Application bootstrap — wires all UI controls to simulation and visualizer properties |