How sugaryhull/re3 works
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: World.cpp World State · skeleton.h Skeleton · Renderer.cpp Renderer · Game.cpp Game Core
Components 24
Platform
Executable startup, input, and OS/backend selection.
- Game Main · Standalone executable entry and startup path.
src/core/main.cpp - Skeleton · Cross-platform bootstrap, windowing, events, and backend selection.
src/skel/skeleton.h - Windows Host · Windows-specific executable and resource glue.
src/skel/win/win.cpp - GLFW Host · Non-Windows window/input backend.
src/skel/glfw/glfw.cpp - Crossplatform · Shared platform abstractions and event plumbing.
src/skel/crossplatform.cpp
Runtime
Core game loop, asset access, world state, and global services.
- Game Core · Top-level game state and frame orchestration.
src/core/Game.cpp - World State · Global world coordination and entity management.
src/core/World.cpp - Streaming · Loads and schedules models, textures, and other runtime assets.
src/core/Streaming.cpp - File Access · Directory, file manager, and loader for game data.
src/core/FileLoader.cpp - Save System · Game storage, memory card, and PC save handling.
src/save/PCSave.cpp
World
Entities and gameplay systems that simulate the city.
- Placeable · Shared transform and positioning base for world objects.
src/core/Placeable.cpp - Entities · Common entity and physical object abstractions.
src/entities/Entity.cpp - Peds · Pedestrian behavior, combat, pathing, and population logic.
src/peds/Ped.cpp - Vehicles · Vehicle physics, handling, damage, and specialized types.
src/vehicles/Vehicle.cpp - Control AI · Traffic, pathfinding, garages, pickups, scripts, and mission control.
src/control/GameLogic.cpp - Collision · Collision models, primitives, and specialized collision paths.
src/collision/Collision.cpp
Presentation
Rendering, animation, audio, UI, and text systems.
- Animation · Blending, skeletons, cutscenes, and frame updates.
src/animation/AnimManager.cpp - Renderer · World rendering, HUD, effects, and presentation subsystems.
src/render/Renderer.cpp - Fake RW · RenderWare compatibility layer and core rendering types.
src/fakerw/fake.cpp - Graphics Backends · Backend-specific pipelines for D3D9 and OpenGL plus shaders.
src/extras/custompipes.cpp - Audio · Music, effects, police radio, scripting hooks, and backend selection.
src/audio/AudioManager.cpp - UI and Text · 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 · External assets, scripts, localization, tuning tables, and models.
gamefiles - Build System · CMake, Conan, and Premake build and packaging configuration.
CMakeLists.txt
Connections 24
- 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.