# mrxenginner/revc architecture

> Architecture diagram of the GitHub repository mrxenginner/revc, 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/mrxenginner/revc
- Repository: https://github.com/mrxenginner/revc

## Overview

1. **What this repository is**
   - This is a standalone reverse-engineered game executable for **GTA Vice City** (`reVC`), not a general-purpose engine.
   - The project expects a real Vice City installation: the code runs against **original game assets** plus a small set of updated/replacement `gamefiles`.

2. **High-level runtime shape**
   - The main executable is built from the C++ code under `src/`.
   - The program boots through platform-specific “skeleton” code, then enters the shared game loop in `src/core`.
   - Most gameplay logic is platform-agnostic; platform differences are isolated in `src/skel`, rendering backends, and audio backend selection.

3. **Platform boundary / launch layer**
   - `src/skel` contains the OS entry points and compatibility layer for **Windows, Android, SDL2, GLFW, and cross-platform support**.
   - Android has an additional Java/SDL launcher in `android/launcher`, with `MainActivity.java` and the embedded SDL activity/device code used to start and host the native game.
   - This layer handles startup, window/surface creation, input plumbing, logging, signal/exception handling, and platform services.

4. **Core game loop and global orchestration**
   - `src/core` is the central control plane: `main.cpp`, `Game.cpp`, `World.cpp`, `TimeStep.cpp`, `Streaming.cpp`, `Frontend.cpp`, `Pad.cpp`, `Camera.cpp`, and related files.
   - This layer coordinates initialization, frame updates, game state transitions, world streaming, camera, input, menus, and the main simulation tick.
   - It is the main hub through which the other subsystems interact.

5. **Gameplay simulation subsystems**
   - Gameplay is split into domain-specific modules:
     - `src/peds` for pedestrians, AI, combat, population, and player ped logic
     - `src/vehicles` for vehicle dynamics, handling, damage, trains, boats, planes, etc.
     - `src/weapons` for bullets, explosions, weapon info, and weapon effects
     - `src/control` for mission logic, scripts, pathfinding, traffic, pickups, garages, cutscenes, and world events
     - `src/objects` and `src/entities` for world objects and entity behavior
   - These subsystems feed the core world simulation and ultimately drive what the renderer and audio systems present.

6. **World data, streaming, and assets**
   - `src/core/Streaming.cpp`, `FileLoader.cpp`, `FileMgr.cpp`, and `Directory.cpp` manage loading of model, texture, script, and archive data from disk.
   - `gamefiles/` contains shipped runtime data the executable depends on: controller mappings, localized text, model textures, tuning tables, and script assets.
   - The repository also includes `utils/gxt` for text-table tooling, reflecting the game’s dependency on language/message resources.

7. **Rendering architecture**
   - `src/renderer` contains the game-side rendering logic: HUD, sprites, shadows, particles, weather, timecycle, water, post-processing, glass, coronas, etc.
   - `src/rw` and `src/fakerw` form the RenderWare-facing abstraction layer used by the reversed game code.
   - Rendering can target either original RenderWare/D3D8 behavior or the reimplementation path via **librw**, enabling backends such as **D3D9, OpenGL, and OpenGL ES**.

8. **Graphics extension and shader layer**
   - `src/extras` contains optional or enhanced rendering features: post-processing, screen droplets, debug menu, custom pipelines, and shader code.
   - The `src/extras/shaders` tree and generated `obj` shader artifacts show a backend that supports modernized shader-based rendering paths.
   - This is where platform-specific visual enhancements and pipeline variants are concentrated.

9. **Audio architecture**
   - `src/audio` is the game audio stack, including music, radio, collision sounds, script-driven audio, and sample management.
   - It supports multiple backend styles, including **MSS** compatibility and **OpenAL** through separate `sampman_*` implementations.
   - The audio layer is selected at build time and connects game events to ambient sound, mission audio, and radio playback.

10. **Animation and character rigging**
    - `src/animation` manages animation sequences, blend associations, hierarchy, cutscenes, and bone-driven updates.
    - This subsystem bridges model data and ped/character rendering, especially for player and NPC animation state.

11. **Persistence, UI text, and configuration**
    - `src/save` handles savegame serialization and memory-card/PC save formats.
    - `src/text` and `gamefiles/TEXT` provide localized message loading and in-game text.
    - `src/core/IniFile.cpp`, `config.h`, and related frontend/profile code handle runtime configuration, user settings, and behavior toggles.

12. **Math, collision, and low-level engine support**
    - `src/math` provides shared vector/matrix/quaternion types used everywhere.
    - `src/collision` contains the collision model, geometry, and detection logic.
    - `src/modelinfo` and `src/rw` act as model metadata and rendering-support layers that sit between world assets and simulation/rendering.

13. **Build and integration model**
    - The repo supports multiple build systems: **CMake**, **Premake**, **Conan**, and Android Gradle.
    - GitHub Actions workflows build Windows, Linux, Android, Switch, and MSVC variants, showing that platform output is a first-class concern.
    - `vendor/` and the `librw` submodule usage indicate the repo depends on external rendering infrastructure rather than owning the entire graphics stack.

14. **Practical architecture summary for a diagram**
    - A useful diagram would place **platform launchers / skeletons** on the left, feeding a shared **core simulation loop** in the center.
    - From there, branch into **gameplay subsystems** (peds, vehicles, weapons, scripts, control), **asset streaming / save / text**, and **presentation subsystems** (renderer, audio, animation).
    - A separate boundary should show **platform/back-end adapters** for rendering and audio, with external dependencies on **original GTA Vice City assets** plus `gamefiles/` and optional `librw`/OpenAL backends.

Main entry points: [`src/core/World.cpp`](https://github.com/mrxenginner/revc/blob/miami/src/core/World.cpp) (World), [`gamefiles`](https://github.com/mrxenginner/revc/tree/miami/gamefiles) (Gamefiles), [`src/control`](https://github.com/mrxenginner/revc/tree/miami/src/control) (Control), [`src/renderer`](https://github.com/mrxenginner/revc/tree/miami/src/renderer) (Renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform launch"]
  node_android_launcher["Android launcher<br/>android host<br/>[MainActivity.java]"]
  node_skeleton["Skeleton<br/>platform layer"]
end

subgraph group_core["Core loop"]
  node_core_main["Game loop<br/>runtime core<br/>[main.cpp]"]
  node_world["World<br/>simulation hub<br/>[World.cpp]"]
  node_streaming["Streaming<br/>asset runtime<br/>[Streaming.cpp]"]
  node_frontend["Frontend<br/>menus/ui<br/>[Frontend.cpp]"]
  node_input["Input<br/>controller layer<br/>[Pad.cpp]"]
end

subgraph group_gameplay["Gameplay systems"]
  node_peds["Peds<br/>npc simulation"]
  node_vehicles["Vehicles<br/>vehicle simulation"]
  node_weapons["Weapons<br/>combat system"]
  node_control["Control<br/>missions/scripts"]
  node_entities["Entities<br/>world objects"]
end

subgraph group_presentation["Presentation"]
  node_renderer["Renderer"]
  node_renderware["RenderWare<br/>rw bridge"]
  node_fakerw["Fake RW<br/>rw shim"]
  node_audio["Audio<br/>sound system"]
  node_animation["Animation<br/>character anim"]
end

subgraph group_data["Data and tools"]
  node_assets[("Gamefiles<br/>runtime data")]
  node_text["Text<br/>localization"]
  node_save["Save system<br/>persistence"]
  node_gxt_tools["GXT tools<br/>asset tool"]
end

node_android_launcher -->|"starts native runtime"| node_skeleton
node_skeleton -->|"boots"| node_core_main
node_core_main -->|"drives"| node_world
node_world -->|"requests data"| node_streaming
node_world -->|"state changes"| node_frontend
node_world -->|"reads controls"| node_input
node_world -->|"updates"| node_peds
node_world -->|"updates"| node_vehicles
node_world -->|"updates"| node_weapons
node_world -->|"runs logic"| node_control
node_world -->|"simulates"| node_entities
node_control -->|"directs AI"| node_peds
node_control -->|"directs traffic"| node_vehicles
node_control -->|"triggers combat"| node_weapons
node_renderer -->|"uses"| node_renderware
node_renderware -->|"abstracts"| node_fakerw
node_renderer -->|"consumes poses"| node_animation
node_audio -->|"loads sounds"| node_assets
node_text -->|"loads tables"| node_assets
node_save -->|"persists state"| node_assets
node_gxt_tools -.->|"supports"| node_text
node_streaming -->|"reads files"| node_assets
node_renderer -->|"uses textures"| node_assets

click node_android_launcher "https://github.com/mrxenginner/revc/blob/miami/android/launcher/app/src/main/java/com/revc/game/MainActivity.java"
click node_skeleton "https://github.com/mrxenginner/revc/tree/miami/src/skel"
click node_core_main "https://github.com/mrxenginner/revc/blob/miami/src/core/main.cpp"
click node_world "https://github.com/mrxenginner/revc/blob/miami/src/core/World.cpp"
click node_streaming "https://github.com/mrxenginner/revc/blob/miami/src/core/Streaming.cpp"
click node_frontend "https://github.com/mrxenginner/revc/blob/miami/src/core/Frontend.cpp"
click node_input "https://github.com/mrxenginner/revc/blob/miami/src/core/Pad.cpp"
click node_peds "https://github.com/mrxenginner/revc/tree/miami/src/peds"
click node_vehicles "https://github.com/mrxenginner/revc/tree/miami/src/vehicles"
click node_weapons "https://github.com/mrxenginner/revc/tree/miami/src/weapons"
click node_control "https://github.com/mrxenginner/revc/tree/miami/src/control"
click node_entities "https://github.com/mrxenginner/revc/tree/miami/src/entities"
click node_renderer "https://github.com/mrxenginner/revc/tree/miami/src/renderer"
click node_renderware "https://github.com/mrxenginner/revc/tree/miami/src/rw"
click node_fakerw "https://github.com/mrxenginner/revc/tree/miami/src/fakerw"
click node_audio "https://github.com/mrxenginner/revc/tree/miami/src/audio"
click node_animation "https://github.com/mrxenginner/revc/tree/miami/src/animation"
click node_assets "https://github.com/mrxenginner/revc/tree/miami/gamefiles"
click node_text "https://github.com/mrxenginner/revc/tree/miami/src/text"
click node_save "https://github.com/mrxenginner/revc/tree/miami/src/save"
click node_gxt_tools "https://github.com/mrxenginner/revc/tree/miami/utils/gxt"

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_android_launcher,node_skeleton toneBlue
class node_core_main,node_world,node_streaming,node_frontend,node_input toneAmber
class node_peds,node_vehicles,node_weapons,node_control,node_entities toneMint
class node_renderer,node_renderware,node_fakerw,node_audio,node_animation toneRose
class node_assets,node_text,node_save,node_gxt_tools toneIndigo
```

## Components

### Platform launch

OS entry points, Android launcher, and cross-platform skeleton code.

- [Android launcher](https://github.com/mrxenginner/revc/blob/miami/android/launcher/app/src/main/java/com/revc/game/MainActivity.java): android host · Java/SDL activity and embedded launcher that starts the native game on Android. · `android/launcher/app/src/main/java/com/revc/game/MainActivity.java`
- [Skeleton](https://github.com/mrxenginner/revc/tree/miami/src/skel): platform layer · OS entry, event plumbing, logging, windowing, and platform services across Windows, SDL2, GLFW, and Android. · `src/skel`

### Core loop

Central game control plane and shared runtime services.

- [Game loop](https://github.com/mrxenginner/revc/blob/miami/src/core/main.cpp): runtime core · Program entry and orchestration for initialization, frame updates, and state transitions. · `src/core/main.cpp`
- [World](https://github.com/mrxenginner/revc/blob/miami/src/core/World.cpp): simulation hub · Owns global world state and coordinates the main simulation tick. · `src/core/World.cpp`
- [Streaming](https://github.com/mrxenginner/revc/blob/miami/src/core/Streaming.cpp): asset runtime · Loads and manages streamed models, textures, scripts, and archives during play. · `src/core/Streaming.cpp`
- [Frontend](https://github.com/mrxenginner/revc/blob/miami/src/core/Frontend.cpp): menus/ui · Menu flow, UI state, and frontend transitions. · `src/core/Frontend.cpp`
- [Input](https://github.com/mrxenginner/revc/blob/miami/src/core/Pad.cpp): controller layer · Pad and controller configuration, including runtime input mapping. · `src/core/Pad.cpp`

### Gameplay systems

Simulation subsystems that drive world behavior.

- [Peds](https://github.com/mrxenginner/revc/tree/miami/src/peds): npc simulation · Pedestrian AI, player ped logic, population, combat, and routing. · `src/peds`
- [Vehicles](https://github.com/mrxenginner/revc/tree/miami/src/vehicles): vehicle simulation · Vehicle dynamics, handling, damage, and specialized vehicle types. · `src/vehicles`
- [Weapons](https://github.com/mrxenginner/revc/tree/miami/src/weapons): combat system · Projectiles, explosions, weapon data, and effects. · `src/weapons`
- [Control](https://github.com/mrxenginner/revc/tree/miami/src/control): missions/scripts · Mission logic, scripts, pathfinding, traffic, pickups, garages, and world events. · `src/control`
- [Entities](https://github.com/mrxenginner/revc/tree/miami/src/entities): world objects · Base entity and physical object behavior shared across gameplay systems. · `src/entities`

### Presentation

Rendering, audio, and animation layers.

- [Renderer](https://github.com/mrxenginner/revc/tree/miami/src/renderer): game renderer · HUD, particles, weather, timecycle, water, shadows, and other game-side drawing systems. · `src/renderer`
- [RenderWare](https://github.com/mrxenginner/revc/tree/miami/src/rw): rw bridge · RenderWare-facing abstraction used by the reversed game code and asset pipeline. · `src/rw`
- [Fake RW](https://github.com/mrxenginner/revc/tree/miami/src/fakerw): rw shim · Compatibility headers and shim layer for RenderWare types and APIs. · `src/fakerw`
- [Audio](https://github.com/mrxenginner/revc/tree/miami/src/audio): sound system · Music, radio, collision sounds, scripted audio, and sample management with multiple backend implementations. · `src/audio`
- [Animation](https://github.com/mrxenginner/revc/tree/miami/src/animation): character anim · Animation sequencing, blend state, hierarchy, and bone updates for characters and cutscenes. · `src/animation`

### Data and tools

Runtime assets, save/text resources, and tooling.

- [Gamefiles](https://github.com/mrxenginner/revc/tree/miami/gamefiles): runtime data · Shipped asset bundle containing text tables, scripts, textures, and tuning data required by the executable. · `gamefiles`
- [Text](https://github.com/mrxenginner/revc/tree/miami/src/text): localization · Localized message tables and in-game text resources. · `src/text`
- [Save system](https://github.com/mrxenginner/revc/tree/miami/src/save): persistence · Savegame serialization and memory-card/PC save formats. · `src/save`
- [GXT tools](https://github.com/mrxenginner/revc/tree/miami/utils/gxt): asset tool · Utilities for working with localized text-table resources. · `utils/gxt`

## Connections

- Android launcher → Skeleton: starts native runtime · Android launcher hosts and starts the shared native game layer.
- Skeleton → Game loop: boots · Platform entry hands control to the shared game executable.
- Game loop → World: drives · Main loop updates global world state each frame.
- World → Streaming: requests data · World simulation triggers model, texture, and script streaming.
- World → Frontend: state changes · World and game state transitions feed menus and frontend flow.
- World → Input: reads controls · Core simulation consumes controller and pad state.
- World → Peds: updates · World tick advances pedestrian AI and population behavior.
- World → Vehicles: updates · World tick advances vehicle dynamics and traffic actors.
- World → Weapons: updates · World tick resolves combat, projectiles, and explosions.
- World → Control: runs logic · Mission scripts and world events are executed through control systems.
- World → Entities: simulates · Shared entity and physical object behavior underpins the world update.
- Control → Peds: directs AI · Scripts and mission logic steer ped behavior and special cases.
- Control → Vehicles: directs traffic · Control systems manage traffic, spawns, and vehicle events.
- Control → Weapons: triggers combat · Scripts can spawn or configure combat and explosive events.
- Renderer → RenderWare: uses · Game-side renderer issues drawing through the RenderWare-facing layer.
- RenderWare → Fake RW: abstracts · Compatibility shims provide the expected RW interfaces and types.
- Renderer → Animation: consumes poses · Rendering consumes animated character and cutscene pose data.
- Audio → Gamefiles: loads sounds · Audio backends use shipped data and sample resources.
- Text → Gamefiles: loads tables · Localized messages are sourced from shipped GXT resources.
- Save system → Gamefiles: persists state · Save data coexists with the runtime asset and configuration bundle.
- GXT tools → Text: supports · Tooling reflects the game's dependency on text-table resources.
- Streaming → Gamefiles: reads files · Streaming system consumes original game assets and replacement gamefiles.
- Renderer → Gamefiles: uses textures · Presentation layer depends on shipped textures and model data.