# bit-racer/bit-racer-assembly-game architecture

> Architecture diagram of the GitHub repository bit-racer/bit-racer-assembly-game, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bit-racer/bit-racer-assembly-game
- Repository: https://github.com/bit-racer/bit-racer-assembly-game

## Overview

Bit Racer is an x86 assembly racing game. The intended player workflow is to start the game, navigate a race, and see the result; the README confirms the game and its assembly implementation but does not describe its controls or runtime module wiring. The source tree suggests distinct input, movement, track, rendering, and interface responsibilities, so those appear as separate components with unverified links. The sampled image converter is also shown as an asset-authoring utility. Most assembly sources were not sampled, so their relationships remain dashed rather than asserted.

Main entry points: [`src/main.asm`](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/main.asm) (Game Entry), [`src/track.inc`](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/track.inc) (Track State), [`src/moveP.inc`](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/moveP.inc) (Player Input), [`src/drawM.inc`](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/drawM.inc) (Display Drawing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_game["Game Runtime"]
  node_entry["Game Entry<br/>[main.asm]"]
  node_constants["Game Constants<br/>[consts.inc]"]
  node_procedures["Shared Procedures<br/>[procs.inc]"]
end

subgraph group_race["Race Systems"]
  node_input["Player Input<br/>[moveP.inc]"]
  node_movement["Car Movement<br/>[moveM.inc]"]
  node_random["Random Events<br/>[randomP.inc]"]
  node_track["Track State<br/>[track.inc]"]
  node_trackplayer["Player Track Logic<br/>[trackMP.inc]"]
  node_trackmachine["Track Logic<br/>[trackMM.inc]"]
  node_powerups["Power-ups<br/>[puM.inc]"]
end

subgraph group_visuals["Display and Interface"]
  node_drawplayer["Player Drawing<br/>[drawP.inc]"]
  node_drawmachine["Display Drawing<br/>[drawM.inc]"]
  node_chat["Chat Interface<br/>[chatP.inc]"]
  node_chatdisplay["Chat Display<br/>[chatM.inc]"]
end

subgraph group_assets["Asset Authoring"]
  node_imageincludes["Image Data"]
  node_imageconverter["Image Converter<br/>[convert_all.py]"]
end

node_player(("Player"))

node_player -.->|"starts game"| node_entry
node_entry -.->|"handles input"| node_input
node_input -.->|"drives movement"| node_movement
node_entry -.->|"uses track"| node_track
node_track -.->|"supports player"| node_trackplayer
node_track -.->|"supports track"| node_trackmachine
node_entry -.->|"uses randomness"| node_random
node_entry -.->|"uses power-ups"| node_powerups
node_entry -.->|"draws player"| node_drawplayer
node_entry -.->|"draws display"| node_drawmachine
node_entry -.->|"uses chat"| node_chat
node_chat -.->|"uses display"| node_chatdisplay
node_drawmachine -.->|"uses image data"| node_imageincludes
node_imageconverter -.->|"generates image data"| node_imageincludes
node_entry -.->|"uses constants"| node_constants
node_entry -.->|"uses procedures"| node_procedures

click node_entry "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/main.asm"
click node_constants "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/consts.inc"
click node_procedures "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/procs.inc"
click node_input "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/moveP.inc"
click node_movement "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/moveM.inc"
click node_random "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/randomP.inc"
click node_track "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/track.inc"
click node_trackplayer "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/trackMP.inc"
click node_trackmachine "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/trackMM.inc"
click node_drawplayer "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/drawP.inc"
click node_drawmachine "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/drawM.inc"
click node_chat "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/chatP.inc"
click node_chatdisplay "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/chatM.inc"
click node_powerups "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/puM.inc"
click node_imageincludes "https://github.com/bit-racer/bit-racer-assembly-game/tree/phase-1/src/image-includes"
click node_imageconverter "https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/convert_all.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_constants,node_procedures toneBlue
class node_input,node_movement,node_random,node_track,node_trackplayer,node_trackmachine,node_powerups toneAmber
class node_drawplayer,node_drawmachine,node_chat,node_chatdisplay toneMint
class node_imageincludes,node_imageconverter toneRose
class node_player toneIndigo
```

## Components

### Game Runtime

- [Game Entry](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/main.asm): `src/main.asm`
- [Game Constants](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/consts.inc): `src/consts.inc`
- [Shared Procedures](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/procs.inc): `src/procs.inc`

### Race Systems

- [Player Input](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/moveP.inc): `src/moveP.inc`
- [Car Movement](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/moveM.inc): `src/moveM.inc`
- [Random Events](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/randomP.inc): `src/randomP.inc`
- [Track State](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/track.inc): `src/track.inc`
- [Player Track Logic](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/trackMP.inc): `src/trackMP.inc`
- [Track Logic](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/trackMM.inc): `src/trackMM.inc`
- [Power-ups](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/puM.inc): `src/puM.inc`

### Display and Interface

- [Player Drawing](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/drawP.inc): `src/drawP.inc`
- [Display Drawing](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/drawM.inc): `src/drawM.inc`
- [Chat Interface](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/chatP.inc): `src/chatP.inc`
- [Chat Display](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/chatM.inc): `src/chatM.inc`

### Asset Authoring

- [Image Data](https://github.com/bit-racer/bit-racer-assembly-game/tree/phase-1/src/image-includes): `src/image-includes`
- [Image Converter](https://github.com/bit-racer/bit-racer-assembly-game/blob/phase-1/src/convert_all.py): `src/convert_all.py`

### Other components

- **Player**

## Connections

- Player → Game Entry: starts game
- Game Entry → Player Input: handles input
- Player Input → Car Movement: drives movement
- Game Entry → Track State: uses track
- Track State → Player Track Logic: supports player
- Track State → Track Logic: supports track
- Game Entry → Random Events: uses randomness
- Game Entry → Power-ups: uses power-ups
- Game Entry → Player Drawing: draws player
- Game Entry → Display Drawing: draws display
- Game Entry → Chat Interface: uses chat
- Chat Interface → Chat Display: uses display
- Display Drawing → Image Data: uses image data
- Image Converter → Image Data: generates image data
- Game Entry → Game Constants: uses constants
- Game Entry → Shared Procedures: uses procedures
