# sonicretro/s1disasm architecture

> Architecture diagram of the GitHub repository sonicretro/s1disasm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sonicretro/s1disasm
- Repository: https://github.com/sonicretro/s1disasm

## Overview

This repository is a disassembly of the 16-bit Sonic the Hedgehog game, accompanied by SonLVL object-definition utilities for level editing. The principal product workflow is editing level/object data and game assets, then assembling the game into a playable result; the README identifies the repository as a disassembly but does not document that workflow in detail. The graph preserves the major runtime, content, and asset areas visible in the tree. Dashed links indicate plausible relationships not verified in the supplied excerpts; sampled SonLVL definitions directly show their asset-loading relationships.

Main entry points: [`_inc/Level Drawing (REV00).asm`](https://github.com/sonicretro/s1disasm/blob/AS/_inc/Level%20Drawing%20(REV00).asm) (Level engine), [`_incObj`](https://github.com/sonicretro/s1disasm/tree/AS/_incObj) (Level objects), [`_inc/ExecuteObjects.asm`](https://github.com/sonicretro/s1disasm/blob/AS/_inc/ExecuteObjects.asm) (Object runtime), [`levels`](https://github.com/sonicretro/s1disasm/tree/AS/levels) (Level data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Game runtime"]
  node_player["Sonic behavior<br/>[01 Sonic.asm]"]
  node_object_runtime["Object runtime<br/>[ExecuteObjects.asm]"]
  node_level_runtime["Level engine"]
  node_special_stage_runtime["Special stages"]
  node_hud["HUD and pause<br/>[HUD Update.asm]"]
  node_sound_runtime["Sound routines"]
end

subgraph group_content["Game content"]
  node_game_objects["Level objects"]
  node_sonic_content["Sonic animation<br/>[Sonic.asm]"]
end

subgraph group_assets["Game assets"]
  node_object_maps["Object mappings"]
  node_animation_data["Animation data"]
  node_compressed_art["Compressed art"]
  node_level_data["Level data"]
  node_audio_data["Music and effects"]
  node_shared_maps["Shared object maps"]
  node_shared_art["Shared object art"]
end

subgraph group_editor["Level editing"]
  node_sonlvl_definitions["Object definitions"]
  node_ring_definition["Ring definition<br/>[Ring.cs]"]
  node_spike_definition["Spikeball definition<br/>[Spikeball.cs]"]
end

node_editor_user(("Level editor user"))
node_assembly_result["Playable game"]

node_editor_user -.->|"edits objects"| node_sonlvl_definitions
node_ring_definition -->|"loads art"| node_shared_art
node_ring_definition -->|"maps sprites"| node_shared_maps
node_spike_definition -->|"loads art"| node_shared_art
node_spike_definition -->|"maps sprites"| node_shared_maps
node_sonlvl_definitions -.->|"edits placements"| node_level_data
node_level_data -.->|"supplies levels"| node_level_runtime
node_level_runtime -.->|"dispatches objects"| node_object_runtime
node_object_runtime -.->|"runs objects"| node_game_objects
node_player -.->|"interacts with"| node_object_runtime
node_sonic_content -.->|"uses animation"| node_animation_data
node_special_stage_runtime -.->|"loads layouts"| node_level_data
node_hud -.->|"shows status"| node_player
node_sound_runtime -.->|"plays audio"| node_audio_data
node_level_runtime -.->|"loads graphics"| node_compressed_art
node_game_objects -.->|"draws mappings"| node_object_maps
node_game_objects -.->|"uses animation"| node_animation_data
node_level_runtime -.->|"contributes runtime"| node_assembly_result

click node_player "https://github.com/sonicretro/s1disasm/blob/AS/_incObj/01%20Sonic.asm"
click node_object_runtime "https://github.com/sonicretro/s1disasm/blob/AS/_inc/ExecuteObjects.asm"
click node_level_runtime "https://github.com/sonicretro/s1disasm/blob/AS/_inc/Level%20Drawing%20(REV00).asm"
click node_special_stage_runtime "https://github.com/sonicretro/s1disasm/blob/AS/_inc/Special%20Stage%20Loading%20%26%20Drawing.asm"
click node_hud "https://github.com/sonicretro/s1disasm/blob/AS/_inc/HUD%20Update.asm"
click node_sound_runtime "https://github.com/sonicretro/s1disasm/blob/AS/_inc/Queue%20Sound%20Routines.asm"
click node_game_objects "https://github.com/sonicretro/s1disasm/tree/AS/_incObj"
click node_sonic_content "https://github.com/sonicretro/s1disasm/blob/AS/_anim/Sonic.asm"
click node_object_maps "https://github.com/sonicretro/s1disasm/tree/AS/_maps"
click node_animation_data "https://github.com/sonicretro/s1disasm/tree/AS/_anim"
click node_compressed_art "https://github.com/sonicretro/s1disasm/tree/AS/artnem"
click node_level_data "https://github.com/sonicretro/s1disasm/tree/AS/levels"
click node_audio_data "https://github.com/sonicretro/s1disasm/tree/AS/sound"
click node_sonlvl_definitions "https://github.com/sonicretro/s1disasm/tree/AS/Utility%20Project%20Files/SonLVL%20INI%20Files"
click node_ring_definition "https://github.com/sonicretro/s1disasm/blob/AS/Utility%20Project%20Files/SonLVL%20INI%20Files/Common/Ring.cs"
click node_spike_definition "https://github.com/sonicretro/s1disasm/blob/AS/Utility%20Project%20Files/SonLVL%20INI%20Files/LZ/Spikeball.cs"
click node_shared_maps "https://github.com/sonicretro/s1disasm/tree/AS/_maps"
click node_shared_art "https://github.com/sonicretro/s1disasm/tree/AS/artnem"

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_player,node_object_runtime,node_level_runtime,node_special_stage_runtime,node_hud,node_sound_runtime,node_editor_user toneBlue
class node_game_objects,node_sonic_content toneAmber
class node_object_maps,node_animation_data,node_compressed_art,node_level_data,node_audio_data,node_shared_maps,node_shared_art toneMint
class node_sonlvl_definitions,node_ring_definition,node_spike_definition toneRose
class node_assembly_result toneIndigo
```

## Components

### Game runtime

- [Sonic behavior](https://github.com/sonicretro/s1disasm/blob/AS/_incObj/01%20Sonic.asm): `_incObj/01 Sonic.asm`
- [Object runtime](https://github.com/sonicretro/s1disasm/blob/AS/_inc/ExecuteObjects.asm): `_inc/ExecuteObjects.asm`
- [Level engine](https://github.com/sonicretro/s1disasm/blob/AS/_inc/Level%20Drawing%20(REV00).asm): `_inc/Level Drawing (REV00).asm`
- [Special stages](https://github.com/sonicretro/s1disasm/blob/AS/_inc/Special%20Stage%20Loading%20%26%20Drawing.asm): `_inc/Special Stage Loading & Drawing.asm`
- [HUD and pause](https://github.com/sonicretro/s1disasm/blob/AS/_inc/HUD%20Update.asm): `_inc/HUD Update.asm`
- [Sound routines](https://github.com/sonicretro/s1disasm/blob/AS/_inc/Queue%20Sound%20Routines.asm): `_inc/Queue Sound Routines.asm`

### Game content

- [Level objects](https://github.com/sonicretro/s1disasm/tree/AS/_incObj): `_incObj`
- [Sonic animation](https://github.com/sonicretro/s1disasm/blob/AS/_anim/Sonic.asm): `_anim/Sonic.asm`

### Game assets

- [Object mappings](https://github.com/sonicretro/s1disasm/tree/AS/_maps): `_maps`
- [Animation data](https://github.com/sonicretro/s1disasm/tree/AS/_anim): `_anim`
- [Compressed art](https://github.com/sonicretro/s1disasm/tree/AS/artnem): `artnem`
- [Level data](https://github.com/sonicretro/s1disasm/tree/AS/levels): `levels`
- [Music and effects](https://github.com/sonicretro/s1disasm/tree/AS/sound): `sound`
- [Shared object maps](https://github.com/sonicretro/s1disasm/tree/AS/_maps): `_maps`
- [Shared object art](https://github.com/sonicretro/s1disasm/tree/AS/artnem): `artnem`

### Level editing

- [Object definitions](https://github.com/sonicretro/s1disasm/tree/AS/Utility%20Project%20Files/SonLVL%20INI%20Files): `Utility Project Files/SonLVL INI Files`
- [Ring definition](https://github.com/sonicretro/s1disasm/blob/AS/Utility%20Project%20Files/SonLVL%20INI%20Files/Common/Ring.cs): `Utility Project Files/SonLVL INI Files/Common/Ring.cs`
- [Spikeball definition](https://github.com/sonicretro/s1disasm/blob/AS/Utility%20Project%20Files/SonLVL%20INI%20Files/LZ/Spikeball.cs): `Utility Project Files/SonLVL INI Files/LZ/Spikeball.cs`

### Other components

- **Level editor user**
- **Playable game**

## Connections

- Level editor user → Object definitions: edits objects
- Ring definition → Shared object art: loads art (evidence: `Utility Project Files/SonLVL INI Files/Common/Ring.cs`)
- Ring definition → Shared object maps: maps sprites (evidence: `Utility Project Files/SonLVL INI Files/Common/Ring.cs`)
- Spikeball definition → Shared object art: loads art (evidence: `Utility Project Files/SonLVL INI Files/LZ/Spikeball.cs`)
- Spikeball definition → Shared object maps: maps sprites (evidence: `Utility Project Files/SonLVL INI Files/LZ/Spikeball.cs`)
- Object definitions → Level data: edits placements
- Level data → Level engine: supplies levels
- Level engine → Object runtime: dispatches objects
- Object runtime → Level objects: runs objects
- Sonic behavior → Object runtime: interacts with
- Sonic animation → Animation data: uses animation
- Special stages → Level data: loads layouts
- HUD and pause → Sonic behavior: shows status
- Sound routines → Music and effects: plays audio
- Level engine → Compressed art: loads graphics
- Level objects → Object mappings: draws mappings
- Level objects → Animation data: uses animation
- Level engine → Playable game: contributes runtime
