# sugaryhull/re3 architecture

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

- Interactive diagram: https://gitdiagram.com/sugaryhull/re3
- Repository: https://github.com/sugaryhull/re3

## Overview

1. This repository is a full game reimplementation of GTA III for PC, not a typical app. The executable is built from `src/core/main.cpp` into a standalone game runtime that depends on original GTA III assets in `gamefiles/` or an installed game directory.

2. The top-level architecture is a classic game-engine split: platform/bootstrap code in `src/skel`, engine services in `src/core`, and domain systems in feature folders such as `peds`, `vehicles`, `render`, `audio`, `animation`, `collision`, `control`, and `weapons`. `core/Game.cpp`, `core/World.cpp`, and `core/Streaming.cpp` are central coordination points.

3. Platform and windowing are abstracted behind the skeleton layer. `src/skel/win` handles the Windows executable path, while `src/skel/glfw` and `src/skel/crossplatform.*` support non-Windows builds. This layer owns startup, input/event plumbing, and backend selection.

4. Rendering is based on a custom RenderWare replacement (`src/fakerw` and `src/rw`) plus the external `librw` dependency mentioned in the README. The repo supports multiple graphics backends, notably Direct3D9 and OpenGL 3.3, with backend-specific code in `src/extras/custompipes_d3d9.cpp` and `src/extras/custompipes_gl.cpp`, plus shader assets under `src/extras/shaders/`.

5. The world simulation is organized around entity types. Base abstractions live in `src/entities`, while specialized gameplay objects are split into `buildings`, `objects`, `peds`, and `vehicles`. These systems share common math and placement types from `src/math` and `src/core/Placeable.*`.

6. Vehicle, pedestrian, and AI behavior are major subsystems rather than one monolith. `src/vehicles` contains vehicle physics and handling, `src/peds` contains pedestrian logic, pathing, combat, and population behavior, and `src/control` contains higher-level world logic such as car AI, traffic, bridges, garages, roadblocks, pickups, and mission/control scripts.

7. Collision and physical interaction are handled in a dedicated subsystem under `src/collision`, including collision models, primitives, and a specialized VU0 collision path. That collision layer feeds movement, vehicle interaction, and environment queries throughout the rest of the engine.

8. Animation is separate from render and entity logic. `src/animation` contains the animation graph and blending system, skeletal/bone support, cutscene animation, and the frame update path. This sits between model data and character/vehicle presentation.

9. Audio is its own subsystem with multiple backend options. `src/audio` contains audio logic, music, police radio, and script-driven sound objects. The build can use Miles, OpenAL, or a null backend; the presence of `FindMilesSDK.cmake`, `FindSndFile.cmake`, `Findmpg123.cmake`, and `Findopusfile.cmake` shows that decoded audio streams and middleware selection are part of the architecture.

10. Game content is loaded from external data rather than embedded. `src/core/FileLoader.cpp`, `FileMgr.cpp`, `Directory.cpp`, and `Streaming.cpp` orchestrate asset access, while `gamefiles/` holds text, model textures, scripts, controller mappings, and tweak tables. The repo’s runtime behavior is therefore data-driven and strongly coupled to the original game’s file formats.

11. Scripting, save, and UI/feedback are separate concerns. Mission/gameplay scripting lives in `src/control/Script*.cpp` and related command headers. Save systems live in `src/save`, text localization in `src/text`, and HUD/menu/frontend behavior in `src/render`, `src/core/Frontend*`, and `src/core/MenuScreens*`.

12. Build and packaging are cross-platform and configurable. The repo supports CMake, Conan, and Premake (`CMakeLists.txt`, `conanfile.py`, `premake5.lua`), with generated/recreated assets under `src/extras/shaders/obj`. The README also notes optional configuration flags in `src/core/config.h`, reflecting a project that exposes engine behavior through compile-time switches as well as external assets and backend choice.

Main entry points: [`src/core/World.cpp`](https://github.com/sugaryhull/re3/blob/main/src/core/World.cpp) (World State), [`src/skel/skeleton.h`](https://github.com/sugaryhull/re3/blob/main/src/skel/skeleton.h) (Skeleton), [`src/render/Renderer.cpp`](https://github.com/sugaryhull/re3/blob/main/src/render/Renderer.cpp) (Renderer), [`src/core/Game.cpp`](https://github.com/sugaryhull/re3/blob/main/src/core/Game.cpp) (Game Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_platform["Platform"]
  node_n_main(("Game Main<br/>entrypoint<br/>[main.cpp]"))
  node_n_skel["Skeleton<br/>platform layer<br/>[skeleton.h]"]
  node_n_win["Windows Host<br/>win backend<br/>[win.cpp]"]
  node_n_glfw["GLFW Host<br/>cross-platform backend<br/>[glfw.cpp]"]
  node_n_cross["Crossplatform<br/>platform glue<br/>[crossplatform.cpp]"]
end

subgraph group_g_runtime["Runtime"]
  node_n_game["Game Core<br/>runtime loop<br/>[Game.cpp]"]
  node_n_world["World State<br/>simulation core<br/>[World.cpp]"]
  node_n_stream["Streaming<br/>[Streaming.cpp]"]
  node_n_loader["File Access<br/>asset io<br/>[FileLoader.cpp]"]
  node_n_save["Save System<br/>persistence<br/>[PCSave.cpp]"]
end

subgraph group_g_world["World"]
  node_n_placeable["Placeable<br/>spatial base<br/>[Placeable.cpp]"]
  node_n_entity["Entities<br/>base entity<br/>[Entity.cpp]"]
  node_n_peds["Peds<br/>character system<br/>[Ped.cpp]"]
  node_n_vehicles["Vehicles<br/>vehicle system<br/>[Vehicle.cpp]"]
  node_n_control["Control AI<br/>world logic<br/>[GameLogic.cpp]"]
  node_n_collision["Collision<br/>physics query<br/>[Collision.cpp]"]
end

subgraph group_g_presentation["Presentation"]
  node_n_anim["Animation<br/>[AnimManager.cpp]"]
  node_n_render["Renderer<br/>rendering<br/>[Renderer.cpp]"]
  node_n_fakerw["Fake RW<br/>rw compatibility<br/>[fake.cpp]"]
  node_n_backend["Graphics Backends<br/>gpu backends<br/>[custompipes.cpp]"]
  node_n_audio["Audio<br/>sound system<br/>[AudioManager.cpp]"]
  node_n_ui["UI and Text<br/>feedback layer<br/>[Frontend.cpp]"]
end

subgraph group_g_assets["Assets"]
  node_n_data[("Gamefiles<br/>content data")]
  node_n_build["Build System<br/>build config<br/>[CMakeLists.txt]"]
end

node_n_main -->|"boots"| node_n_skel
node_n_skel -->|"windows"| node_n_win
node_n_skel -->|"cross-platform"| node_n_glfw
node_n_skel -->|"shares"| node_n_cross
node_n_main -->|"creates"| node_n_game
node_n_game -->|"updates"| node_n_world
node_n_game -->|"uses"| node_n_stream
node_n_stream -->|"reads"| node_n_loader
node_n_loader -->|"loads"| node_n_data
node_n_world -->|"contains"| node_n_entity
node_n_entity -->|"inherits"| node_n_placeable
node_n_world -->|"simulates"| node_n_peds
node_n_world -->|"simulates"| node_n_vehicles
node_n_world -->|"coordinates"| node_n_control
node_n_world -->|"queries"| node_n_collision
node_n_world -->|"drives"| node_n_anim
node_n_render -->|"builds on"| node_n_fakerw
node_n_fakerw -->|"targets"| node_n_backend
node_n_render -->|"consumes"| node_n_anim
node_n_render -.->|"pairs with"| node_n_audio
node_n_ui -->|"draws in"| node_n_render
node_n_ui -->|"localizes"| node_n_data
node_n_save -.->|"persists to"| node_n_data
node_n_build -.->|"configures"| node_n_backend

click node_n_main "https://github.com/sugaryhull/re3/blob/main/src/core/main.cpp"
click node_n_skel "https://github.com/sugaryhull/re3/blob/main/src/skel/skeleton.h"
click node_n_win "https://github.com/sugaryhull/re3/blob/main/src/skel/win/win.cpp"
click node_n_glfw "https://github.com/sugaryhull/re3/blob/main/src/skel/glfw/glfw.cpp"
click node_n_cross "https://github.com/sugaryhull/re3/blob/main/src/skel/crossplatform.cpp"
click node_n_game "https://github.com/sugaryhull/re3/blob/main/src/core/Game.cpp"
click node_n_world "https://github.com/sugaryhull/re3/blob/main/src/core/World.cpp"
click node_n_stream "https://github.com/sugaryhull/re3/blob/main/src/core/Streaming.cpp"
click node_n_loader "https://github.com/sugaryhull/re3/blob/main/src/core/FileLoader.cpp"
click node_n_placeable "https://github.com/sugaryhull/re3/blob/main/src/core/Placeable.cpp"
click node_n_entity "https://github.com/sugaryhull/re3/blob/main/src/entities/Entity.cpp"
click node_n_peds "https://github.com/sugaryhull/re3/blob/main/src/peds/Ped.cpp"
click node_n_vehicles "https://github.com/sugaryhull/re3/blob/main/src/vehicles/Vehicle.cpp"
click node_n_control "https://github.com/sugaryhull/re3/blob/main/src/control/GameLogic.cpp"
click node_n_collision "https://github.com/sugaryhull/re3/blob/main/src/collision/Collision.cpp"
click node_n_anim "https://github.com/sugaryhull/re3/blob/main/src/animation/AnimManager.cpp"
click node_n_render "https://github.com/sugaryhull/re3/blob/main/src/render/Renderer.cpp"
click node_n_fakerw "https://github.com/sugaryhull/re3/blob/main/src/fakerw/fake.cpp"
click node_n_backend "https://github.com/sugaryhull/re3/blob/main/src/extras/custompipes.cpp"
click node_n_audio "https://github.com/sugaryhull/re3/blob/main/src/audio/AudioManager.cpp"
click node_n_ui "https://github.com/sugaryhull/re3/blob/main/src/core/Frontend.cpp"
click node_n_save "https://github.com/sugaryhull/re3/blob/main/src/save/PCSave.cpp"
click node_n_data "https://github.com/sugaryhull/re3/tree/main/gamefiles"
click node_n_build "https://github.com/sugaryhull/re3/blob/main/CMakeLists.txt"

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_n_main,node_n_skel,node_n_win,node_n_glfw,node_n_cross toneBlue
class node_n_game,node_n_world,node_n_stream,node_n_loader,node_n_save toneAmber
class node_n_placeable,node_n_entity,node_n_peds,node_n_vehicles,node_n_control,node_n_collision toneMint
class node_n_anim,node_n_render,node_n_fakerw,node_n_backend,node_n_audio,node_n_ui toneRose
class node_n_data,node_n_build toneIndigo
```

## Components

### Platform

Executable startup, input, and OS/backend selection.

- [Game Main](https://github.com/sugaryhull/re3/blob/main/src/core/main.cpp): entrypoint · Standalone executable entry and startup path. · `src/core/main.cpp`
- [Skeleton](https://github.com/sugaryhull/re3/blob/main/src/skel/skeleton.h): platform layer · Cross-platform bootstrap, windowing, events, and backend selection. · `src/skel/skeleton.h`
- [Windows Host](https://github.com/sugaryhull/re3/blob/main/src/skel/win/win.cpp): win backend · Windows-specific executable and resource glue. · `src/skel/win/win.cpp`
- [GLFW Host](https://github.com/sugaryhull/re3/blob/main/src/skel/glfw/glfw.cpp): cross-platform backend · Non-Windows window/input backend. · `src/skel/glfw/glfw.cpp`
- [Crossplatform](https://github.com/sugaryhull/re3/blob/main/src/skel/crossplatform.cpp): platform glue · Shared platform abstractions and event plumbing. · `src/skel/crossplatform.cpp`

### Runtime

Core game loop, asset access, world state, and global services.

- [Game Core](https://github.com/sugaryhull/re3/blob/main/src/core/Game.cpp): runtime loop · Top-level game state and frame orchestration. · `src/core/Game.cpp`
- [World State](https://github.com/sugaryhull/re3/blob/main/src/core/World.cpp): simulation core · Global world coordination and entity management. · `src/core/World.cpp`
- [Streaming](https://github.com/sugaryhull/re3/blob/main/src/core/Streaming.cpp): asset streaming · Loads and schedules models, textures, and other runtime assets. · `src/core/Streaming.cpp`
- [File Access](https://github.com/sugaryhull/re3/blob/main/src/core/FileLoader.cpp): asset io · Directory, file manager, and loader for game data. · `src/core/FileLoader.cpp`
- [Save System](https://github.com/sugaryhull/re3/blob/main/src/save/PCSave.cpp): persistence · Game storage, memory card, and PC save handling. · `src/save/PCSave.cpp`

### World

Entities and gameplay systems that simulate the city.

- [Placeable](https://github.com/sugaryhull/re3/blob/main/src/core/Placeable.cpp): spatial base · Shared transform and positioning base for world objects. · `src/core/Placeable.cpp`
- [Entities](https://github.com/sugaryhull/re3/blob/main/src/entities/Entity.cpp): base entity · Common entity and physical object abstractions. · `src/entities/Entity.cpp`
- [Peds](https://github.com/sugaryhull/re3/blob/main/src/peds/Ped.cpp): character system · Pedestrian behavior, combat, pathing, and population logic. · `src/peds/Ped.cpp`
- [Vehicles](https://github.com/sugaryhull/re3/blob/main/src/vehicles/Vehicle.cpp): vehicle system · Vehicle physics, handling, damage, and specialized types. · `src/vehicles/Vehicle.cpp`
- [Control AI](https://github.com/sugaryhull/re3/blob/main/src/control/GameLogic.cpp): world logic · Traffic, pathfinding, garages, pickups, scripts, and mission control. · `src/control/GameLogic.cpp`
- [Collision](https://github.com/sugaryhull/re3/blob/main/src/collision/Collision.cpp): physics query · Collision models, primitives, and specialized collision paths. · `src/collision/Collision.cpp`

### Presentation

Rendering, animation, audio, UI, and text systems.

- [Animation](https://github.com/sugaryhull/re3/blob/main/src/animation/AnimManager.cpp): animation system · Blending, skeletons, cutscenes, and frame updates. · `src/animation/AnimManager.cpp`
- [Renderer](https://github.com/sugaryhull/re3/blob/main/src/render/Renderer.cpp): rendering · World rendering, HUD, effects, and presentation subsystems. · `src/render/Renderer.cpp`
- [Fake RW](https://github.com/sugaryhull/re3/blob/main/src/fakerw/fake.cpp): rw compatibility · RenderWare compatibility layer and core rendering types. · `src/fakerw/fake.cpp`
- [Graphics Backends](https://github.com/sugaryhull/re3/blob/main/src/extras/custompipes.cpp): gpu backends · Backend-specific pipelines for D3D9 and OpenGL plus shaders. · `src/extras/custompipes.cpp`
- [Audio](https://github.com/sugaryhull/re3/blob/main/src/audio/AudioManager.cpp): sound system · Music, effects, police radio, scripting hooks, and backend selection. · `src/audio/AudioManager.cpp`
- [UI and Text](https://github.com/sugaryhull/re3/blob/main/src/core/Frontend.cpp): feedback layer · Frontend menus, HUD, text localization, and on-screen messaging. · `src/core/Frontend.cpp`

### Assets

External game data and build-time content used by the runtime.

- [Gamefiles](https://github.com/sugaryhull/re3/tree/main/gamefiles): content data · External assets, scripts, localization, tuning tables, and models. · `gamefiles`
- [Build System](https://github.com/sugaryhull/re3/blob/main/CMakeLists.txt): build config · CMake, Conan, and Premake build and packaging configuration. · `CMakeLists.txt`

## Connections

- Game Main → Skeleton: boots · Executable startup delegates to the platform/bootstrap layer.
- Skeleton → Windows Host: windows · Windows host implementation is selected on that platform.
- Skeleton → GLFW Host: cross-platform · GLFW backend provides non-Windows window/input support.
- Skeleton → Crossplatform: shares · Shared platform abstractions and events are centralized here.
- Game Main → Game Core: creates · Startup hands control to the core game runtime.
- Game Core → World State: updates · Main loop advances world state each frame.
- Game Core → Streaming: uses · Game loop coordinates streaming and asset readiness.
- Streaming → File Access: reads · Streaming depends on directory and file access services.
- File Access → Gamefiles: loads · Runtime data is sourced from external gamefiles content.
- World State → Entities: contains · World state manages base entities and physical objects.
- Entities → Placeable: inherits · Spatial placement is shared across world objects.
- World State → Peds: simulates · Pedestrians are a major world simulation subsystem.
- World State → Vehicles: simulates · Vehicles are a major world simulation subsystem.
- World State → Control AI: coordinates · Global world logic drives AI, traffic, scripts, and missions.
- World State → Collision: queries · Movement and interactions rely on collision services.
- World State → Animation: drives · World entities advance through the animation system.
- Renderer → Fake RW: builds on · Rendering sits on the RenderWare compatibility layer.
- Fake RW → Graphics Backends: targets · Backend-specific pipelines implement the final GPU path.
- Renderer → Animation: consumes · Rendering uses animation state for characters and vehicles.
- Renderer → Audio: pairs with · Presentation is complemented by the audio subsystem.
- UI and Text → Renderer: draws in · HUD, menus, and text are presented through rendering.
- UI and Text → Gamefiles: localizes · Text and frontend assets are loaded from external data files.
- Save System → Gamefiles: persists to · Save and profile behavior is tied to external game data/state.
- Build System → Graphics Backends: configures · Build tooling selects graphics and audio dependencies/backends.