How batmanscode/simdrive works
1. Overall shape
- Sim Drive is a TypeScript multiplayer game with a browser-based frontend and a Node.js authoritative server.
- The architecture is split between:
- a shared game domain layer used by both client and server,
- a real-time game server that owns room and race state,
- and browser clients that render either the shared display or a phone controller.
2. Client application
- The browser app lives under src/ and is built with Vite + React.
- src/main.tsx bootstraps the app, while src/App.tsx likely switches between the major experience modes: display, phone controller, lobby, tutorial, race, and results.
- src/styles.css provides the UI styling for the whole game surface.
3. Display vs controller roles
- The same frontend supports two very different roles:
- the shared display, which shows the room, lobby, race HUD, and results,
- the phone controller, which handles tilt steering, touch fallback, setup, and driver options.
- This role split is central to the product: one browser acts as the host screen while multiple phones join as drivers.
4. Authoritative server
- server/index.ts is the core simulation and room manager.
- It owns:
- room lifecycle,
- player connection/disconnection,
- race phase progression,
- results and DNF handling,
- and the authoritative movement/race logic.
- The server is not just matchmaking; it runs the race rules and determines the source of truth for gameplay.
5. Shared domain layer
- src/shared/ contains code that must stay identical on both sides of the wire:
- cars.ts for vehicle definitions and handling profiles,
- tracks.ts for track data and procedural track structure,
- physics.ts for movement/simulation helpers,
- types.ts for shared room, driver, race, and message types.
- This shared boundary reduces drift between what the client draws and what the server simulates.
6. Real-time data flow
- Players connect to the server over the network and exchange room/race updates in real time, almost certainly via WebSockets.
- The flow is:
- display creates a room,
- phones join using QR code or room code,
- controller input streams to the server,
- the server simulates the race and broadcasts authoritative state back to all clients.
- The README notes that the dev server proxies WebSockets through the same origin, which simplifies local and Codespaces testing.
7. Game-state and matchmaking boundaries
- Room flow is a major subsystem:
- room creation,
- controller join/resume,
- VIP assignment,
- lobby configuration,
- one-player practice,
- and room cleanup after disconnect.
- The server keeps rooms alive through a short grace window if displays disconnect, which means room state is persistent across brief host interruptions but still server-owned.
8. Race simulation subsystem
- The race logic includes vehicle-specific movement, lap counting, checkpoints, collisions, off-track reset behavior, warm-up/flying start timing, and results calculation.
- The server also applies per-driver setup multipliers and vehicle-specific quirks, so the simulation is not just a generic kinematic loop; it is tied to the selected car and race settings.
9. Rendering and presentation
- The display side renders the game’s presentation screens: landing, lobby, tutorial, in-race HUD, and results.
- The README describes a cockpit-style race view with track ribbons, terrain, minimap, leaderboard, rear-view mirror, countdown lights, and auto-spectate after finish.
- The exact rendering library is not explicit in the tree, but the architecture clearly separates visual presentation from the server simulation.
10. Phone input and device-specific behavior
- The controller supports tilt steering, motion permission prompts, touch fallback controls, haptics, and browser-specific sensor paths.
- This implies a distinct input subsystem on mobile that translates device motion and touch into normalized driving commands before sending them to the server.
11. Automation and playtesting
- playtests/ contains scripted test drivers and visual-capture tooling.
- This is a separate verification layer for end-to-end race behavior, likely used to validate lap completion, full-race flow, and render output without manual phone testing.
12. Deployment/runtime model
- In development, Vite serves the client while the Node server handles gameplay traffic.
- In production, npm start runs a single Node process on port 8787 that serves the built frontend and the WebSocket/game server together.
- Static assets live in public/ and include web metadata such as robots.txt, site.webmanifest, and sitemap.xml.
13. Key architectural boundary to diagram
- The most important boundary is between:
- authoritative server simulation and
- stateless-ish browser clients.
- Clients provide input and render state; the server owns the truth of room membership, race progress, physics, and results.
Main entry points: App.tsx App · index.ts Game Server · package.json Package · main.tsx Main
Components 16
Browser Client
Vite + React frontend with shared display and phone controller roles.
- Entry HTML · Bootstraps the browser app and static asset loading.
index.html - Main · Starts the React frontend.
src/main.tsx - App · Switches between display, controller, lobby, race, and results experiences.
src/App.tsx - Styles · Global presentation styling for the game surface.
src/styles.css
Shared Domain
Game models and simulation helpers used by both client and server.
- Types · Room, driver, race, and message types shared across the wire.
src/shared/types.ts - Cars · Vehicle definitions and handling profiles.
src/shared/cars.ts - Tracks · Track layouts and procedural track structure.
src/shared/tracks.ts - Physics · Movement and simulation helpers shared by client and server.
src/shared/physics.ts
Authoritative Server
Node runtime that owns rooms, races, and real-time game state.
- Game Server · Owns rooms, race phases, player state, and race simulation.
server/index.ts
Playtests
Scripted end-to-end drivers and visual capture tooling.
Static Assets
Public files served with the built app.
- Public Assets · Robots, web manifest, and sitemap served with the app.
public/robots.txt - Manifest · Browser app metadata for install and sharing.
public/site.webmanifest - Sitemap · Site indexing metadata.
public/sitemap.xml
Other components
- Package · Defines the client/server build and start workflow.
package.json
Connections 20
- Entry HTML → Main: loads · HTML entry loads the React bootstrap.
- Main → App: mounts · Main entry renders the application shell.
- App → Styles: uses · App-wide presentation styling.
- App → Types: reads · UI reacts to shared room and race state.
- App → Cars: uses · Shows vehicle selections and properties.
- App → Tracks: uses · Renders track-dependent screens and previews.
- App → Physics: mirrors · Client-side presentation aligns with simulation rules.
- Game Server → Types: contracts · Server and client communicate through shared message and state types.
- Game Server → Cars: simulates · Vehicle handling and tuning inform race behavior.
- Game Server → Tracks: runs on · Server race logic is track-aware.
- Game Server → Physics: executes · Authoritative movement and race calculations.
- Game Server → App: broadcasts · Streams authoritative room and race state back to clients.
- Driver → Game Server: drives · Automated inputs exercise the game server.
- Full Lap → Driver: uses · Scenario logic is built on the scripted driver.
- Capture → Full Lap: captures · Visual tooling records scenario runs.
- Package → Game Server: starts · Production runtime launches the Node game server.
- Package → Main: builds · Frontend build and dev workflow.
- Package → Full Lap: runs · Playtest scripts are part of the project toolchain.
- Public Assets → Manifest: bundles · Public site metadata lives alongside other static assets.
- Manifest → Sitemap: bundles · Static web metadata set.