# el8azaly/scavenger_hunt architecture

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

- Interactive diagram: https://gitdiagram.com/el8azaly/scavenger_hunt
- Repository: https://github.com/el8azaly/scavenger_hunt

## Overview

1. This is a Qt/C++ 2D game, not a typical service or web app. The application entry point is `main.cpp`, with `CMakeLists.txt` and `resources.qrc` wiring the build and packaged assets.

2. The top-level runtime is split into a UI shell and the game runtime. `ui/MainWindow` hosts screens like the main menu, quiz dialog, and in-game overlay, while `ui/GameWidget` is the actual game viewport that renders and receives input.

3. The core game flow lives in `core/`. `Game`, `GameLoop`, and `GameState` coordinate startup, per-frame updates, state transitions, and the active level. This is the main orchestration boundary for gameplay.

4. Input, collision, and camera are separated into `engine/`. `InputHandler` turns user actions into gameplay commands, `CollisionEngine` resolves world interactions, and `Camera` tracks the visible portion of the level. These are shared services used by the game state and entities.

5. World content is organized around `core/Level` plus `data/LevelLoader`. The loader bridges authored level data into runtime objects, while `data/levels/Level0-3` provide level-specific definitions. The level assets under `assets/sprites/levels` include visual layers and separate collision/trap data files, indicating a data-driven level pipeline.

6. Gameplay entities are in `entities/` and form the main object model. There are base abstractions like `Entity`, `GameObject`, `InteractiveObject`, `AttackableEntity`, and concrete types such as `Player`, `Enemy`, `CaptainStar` NPC, `Door`, `Container`, `CollectibleItem`, `Cannon`, `Cannonball`, `HiddenArea`, and `StaticPlatform`.

7. The entity layer is split between movement/combat, interactions, and environmental objects. Enemies and the player handle combat and damage, interactive objects support doors, containers, and quiz/NPC interactions, and static or hidden world objects support traversal and discovery.

8. Game-wide progression and persistence-like concerns are handled by `systems/`. `InventorySystem`, `QuestSystem`, `ScoreManager`, and `LevelManager` sit above individual entities and track player state, objectives, scoring, and level progression. This is where cross-cutting gameplay rules are centralized.

9. The `data/` layer also contains registries (`EntityRegistry`, `ItemRegistry`, `ItemData`) that likely map asset/data identifiers to runtime types and item definitions. This is the main boundary between authored content and instantiated gameplay objects.

10. UI rendering is handled by reusable sprite components in `ui/sprite/`: `AnimatedSprite`, `PixelFont`, `SlicedSprite`, `SpriteButton`, `SkyBackground`, and `UISpriteSheet`. These wrap asset-specific drawing concerns and keep presentation separate from game logic.

11. The asset structure is strongly content-driven. Sprites are grouped by domain: player, enemies, items, NPCs, objects, sky, UI, and level layers. Several files are JSON descriptors and `.aseprite` sources, so the game likely consumes exported sprite metadata rather than hardcoding visuals.

12. The main data flow is: user input enters through Qt widgets and `InputHandler`, game state updates entities and systems, collision/camera/level services shape the simulation, and the UI layer renders the world plus HUD/menus. A diagram should show Qt UI as the shell, core/engine as runtime services, entities/systems as gameplay logic, and `data`/`assets` as the content pipeline.

Main entry points: [`core/Level.cpp`](https://github.com/el8azaly/scavenger_hunt/blob/master/core/Level.cpp) (Level), [`core/Game.cpp`](https://github.com/el8azaly/scavenger_hunt/blob/master/core/Game.cpp) (Game), [`core/GameState.cpp`](https://github.com/el8azaly/scavenger_hunt/blob/master/core/GameState.cpp) (Game state), [`main.cpp`](https://github.com/el8azaly/scavenger_hunt/blob/master/main.cpp) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_entry["Entry & build"]
  node_n_main(("Main<br/>entry point<br/>[main.cpp]"))
  node_n_build["Build<br/>cmake<br/>[CMakeLists.txt]"]
  node_n_resources["Assets pack<br/>qrc bundle<br/>[resources.qrc]"]
end

subgraph group_grp_runtime["Runtime core"]
  node_n_game["Game<br/>orchestrator<br/>[Game.cpp]"]
  node_n_loop["Game loop<br/>frame loop<br/>[GameLoop.cpp]"]
  node_n_state["Game state<br/>state machine<br/>[GameState.cpp]"]
  node_n_level["Level<br/>world state<br/>[Level.cpp]"]
  node_n_input["Input<br/>[InputHandler.cpp]"]
  node_n_collision["Collision<br/>physics service"]
  node_n_camera["Camera<br/>view service<br/>[Camera.cpp]"]
end

subgraph group_grp_gameplay["Gameplay model"]
  node_n_player(("Player<br/>entity<br/>[Player.cpp]"))
  node_n_enemies(("Enemies<br/>combat entities<br/>[Enemy.cpp]"))
  node_n_interact(("Interactables<br/>interaction entities"))
  node_n_worldobj(("World objects<br/>environment entities<br/>[StaticPlatform.cpp]"))
  node_n_systems["Systems<br/>progression services<br/>[LevelManager.cpp]"]
end

subgraph group_grp_ui["Qt UI"]
  node_n_uiwindow["Main window<br/>Qt shell<br/>[MainWindow.cpp]"]
  node_n_gamewidget["Game widget<br/>viewport<br/>[GameWidget.cpp]"]
  node_n_screens["Screens<br/>[MainMenuScreen.cpp]"]
  node_n_sprites["Sprite UI<br/>render widgets<br/>[AnimatedSprite.cpp]"]
end

subgraph group_grp_content["Content pipeline"]
  node_n_loader["Level loader<br/>content bridge<br/>[LevelLoader.cpp]"]
  node_n_levels["Level defs<br/>authored levels<br/>[Level0.cpp]"]
  node_n_registry["Registries<br/>data registry<br/>[EntityRegistry.h]"]
  node_n_assets["Sprites<br/>asset set<br/>[level0_bottom.json]"]
end

node_n_main -->|"builds with"| node_n_build
node_n_main -->|"loads"| node_n_resources
node_n_main -->|"starts"| node_n_game
node_n_game -->|"runs"| node_n_loop
node_n_game -->|"manages"| node_n_state
node_n_loop -->|"polls"| node_n_input
node_n_loop -->|"ticks"| node_n_state
node_n_state -->|"owns"| node_n_level
node_n_state -->|"updates"| node_n_systems
node_n_input -->|"controls"| node_n_player
node_n_collision -->|"resolves"| node_n_player
node_n_collision -->|"resolves"| node_n_enemies
node_n_camera -->|"tracks"| node_n_level
node_n_loader -->|"instantiates"| node_n_levels
node_n_loader -->|"binds"| node_n_registry
node_n_loader -->|"uses"| node_n_assets
node_n_level -->|"contains"| node_n_player
node_n_level -->|"contains"| node_n_enemies
node_n_level -->|"contains"| node_n_interact
node_n_level -->|"contains"| node_n_worldobj
node_n_uiwindow -->|"hosts"| node_n_gamewidget
node_n_uiwindow -->|"shows"| node_n_screens
node_n_gamewidget -->|"renders via"| node_n_camera
node_n_gamewidget -->|"draws with"| node_n_sprites
node_n_screens -->|"renders with"| node_n_sprites
node_n_uiwindow -->|"wraps"| node_n_game
node_n_assets -->|"feeds"| node_n_sprites

click node_n_main "https://github.com/el8azaly/scavenger_hunt/blob/master/main.cpp"
click node_n_build "https://github.com/el8azaly/scavenger_hunt/blob/master/CMakeLists.txt"
click node_n_resources "https://github.com/el8azaly/scavenger_hunt/blob/master/resources.qrc"
click node_n_game "https://github.com/el8azaly/scavenger_hunt/blob/master/core/Game.cpp"
click node_n_loop "https://github.com/el8azaly/scavenger_hunt/blob/master/core/GameLoop.cpp"
click node_n_state "https://github.com/el8azaly/scavenger_hunt/blob/master/core/GameState.cpp"
click node_n_level "https://github.com/el8azaly/scavenger_hunt/blob/master/core/Level.cpp"
click node_n_input "https://github.com/el8azaly/scavenger_hunt/blob/master/engine/InputHandler.cpp"
click node_n_collision "https://github.com/el8azaly/scavenger_hunt/blob/master/engine/CollisionEngine.cpp"
click node_n_camera "https://github.com/el8azaly/scavenger_hunt/blob/master/engine/Camera.cpp"
click node_n_player "https://github.com/el8azaly/scavenger_hunt/blob/master/entities/Player.cpp"
click node_n_enemies "https://github.com/el8azaly/scavenger_hunt/blob/master/entities/Enemy.cpp"
click node_n_interact "https://github.com/el8azaly/scavenger_hunt/blob/master/entities/InteractiveObject.cpp"
click node_n_worldobj "https://github.com/el8azaly/scavenger_hunt/blob/master/entities/StaticPlatform.cpp"
click node_n_systems "https://github.com/el8azaly/scavenger_hunt/blob/master/systems/LevelManager.cpp"
click node_n_uiwindow "https://github.com/el8azaly/scavenger_hunt/blob/master/ui/MainWindow.cpp"
click node_n_gamewidget "https://github.com/el8azaly/scavenger_hunt/blob/master/ui/GameWidget.cpp"
click node_n_screens "https://github.com/el8azaly/scavenger_hunt/blob/master/ui/screen/MainMenuScreen.cpp"
click node_n_sprites "https://github.com/el8azaly/scavenger_hunt/blob/master/ui/sprite/AnimatedSprite.cpp"
click node_n_loader "https://github.com/el8azaly/scavenger_hunt/blob/master/data/LevelLoader.cpp"
click node_n_levels "https://github.com/el8azaly/scavenger_hunt/blob/master/data/levels/Level0.cpp"
click node_n_registry "https://github.com/el8azaly/scavenger_hunt/blob/master/data/EntityRegistry.h"
click node_n_assets "https://github.com/el8azaly/scavenger_hunt/blob/master/assets/sprites/levels/level0_bottom.json"

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_build,node_n_resources toneBlue
class node_n_game,node_n_loop,node_n_state,node_n_level,node_n_input,node_n_collision,node_n_camera toneAmber
class node_n_player,node_n_enemies,node_n_interact,node_n_worldobj,node_n_systems toneMint
class node_n_uiwindow,node_n_gamewidget,node_n_screens,node_n_sprites toneRose
class node_n_loader,node_n_levels,node_n_registry,node_n_assets toneIndigo
```

## Components

### Entry & build

Application bootstrap and packaging wiring.

- [Main](https://github.com/el8azaly/scavenger_hunt/blob/master/main.cpp): entry point · Qt application startup. · `main.cpp`
- [Build](https://github.com/el8azaly/scavenger_hunt/blob/master/CMakeLists.txt): cmake · Project configuration and target wiring. · `CMakeLists.txt`
- [Assets pack](https://github.com/el8azaly/scavenger_hunt/blob/master/resources.qrc): qrc bundle · Resource manifest for packaged assets. · `resources.qrc`

### Runtime core

Game orchestration, simulation services, and world state.

- [Game](https://github.com/el8azaly/scavenger_hunt/blob/master/core/Game.cpp): orchestrator · Top-level game bootstrap and ownership boundary. · `core/Game.cpp`
- [Game loop](https://github.com/el8azaly/scavenger_hunt/blob/master/core/GameLoop.cpp): frame loop · Per-frame update and timing control. · `core/GameLoop.cpp`
- [Game state](https://github.com/el8azaly/scavenger_hunt/blob/master/core/GameState.cpp): state machine · Active state and transition management. · `core/GameState.cpp`
- [Level](https://github.com/el8azaly/scavenger_hunt/blob/master/core/Level.cpp): world state · Runtime representation of the current level. · `core/Level.cpp`
- [Input](https://github.com/el8azaly/scavenger_hunt/blob/master/engine/InputHandler.cpp): input service · Translates user actions into gameplay commands. · `engine/InputHandler.cpp`
- [Collision](https://github.com/el8azaly/scavenger_hunt/blob/master/engine/CollisionEngine.cpp): physics service · Resolves world interactions and overlaps. · `engine/CollisionEngine.cpp`
- [Camera](https://github.com/el8azaly/scavenger_hunt/blob/master/engine/Camera.cpp): view service · Tracks the visible portion of the world. · `engine/Camera.cpp`

### Gameplay model

Entities and cross-cutting progression systems.

- [Player](https://github.com/el8azaly/scavenger_hunt/blob/master/entities/Player.cpp): entity · Main controllable character. · `entities/Player.cpp`
- [Enemies](https://github.com/el8azaly/scavenger_hunt/blob/master/entities/Enemy.cpp): combat entities · Hostile actors and damage-bearing entities. · `entities/Enemy.cpp`
- [Interactables](https://github.com/el8azaly/scavenger_hunt/blob/master/entities/InteractiveObject.cpp): interaction entities · Doors, containers, NPCs, and other interactive objects. · `entities/InteractiveObject.cpp`
- [World objects](https://github.com/el8azaly/scavenger_hunt/blob/master/entities/StaticPlatform.cpp): environment entities · Static platforms, hidden areas, and other traversal features. · `entities/StaticPlatform.cpp`
- [Systems](https://github.com/el8azaly/scavenger_hunt/blob/master/systems/LevelManager.cpp): progression services · Inventory, quests, scoring, and level progression. · `systems/LevelManager.cpp`

### Qt UI

Windowing, screens, HUD, and sprite presentation.

- [Main window](https://github.com/el8azaly/scavenger_hunt/blob/master/ui/MainWindow.cpp): Qt shell · Hosts the game viewport and overlay screens. · `ui/MainWindow.cpp`
- [Game widget](https://github.com/el8azaly/scavenger_hunt/blob/master/ui/GameWidget.cpp): viewport · Actual game rendering surface and input target. · `ui/GameWidget.cpp`
- [Screens](https://github.com/el8azaly/scavenger_hunt/blob/master/ui/screen/MainMenuScreen.cpp): ui screens · Main menu, quiz dialog, and in-game overlay. · `ui/screen/MainMenuScreen.cpp`
- [Sprite UI](https://github.com/el8azaly/scavenger_hunt/blob/master/ui/sprite/AnimatedSprite.cpp): render widgets · Reusable UI sprite and text rendering components. · `ui/sprite/AnimatedSprite.cpp`

### Content pipeline

Authored data, level definitions, and packaged assets.

- [Level loader](https://github.com/el8azaly/scavenger_hunt/blob/master/data/LevelLoader.cpp): content bridge · Loads authored level data into runtime objects. · `data/LevelLoader.cpp`
- [Level defs](https://github.com/el8azaly/scavenger_hunt/blob/master/data/levels/Level0.cpp): authored levels · Level-specific data and configuration. · `data/levels/Level0.cpp`
- [Registries](https://github.com/el8azaly/scavenger_hunt/blob/master/data/EntityRegistry.h): data registry · Entity and item lookup plus item definitions. · `data/EntityRegistry.h`
- [Sprites](https://github.com/el8azaly/scavenger_hunt/blob/master/assets/sprites/levels/level0_bottom.json): asset set · Packaged sprite sheets, level layers, and descriptor files. · `assets/sprites/levels/level0_bottom.json`

## Connections

- Main → Build: builds with · CMake config defines the application target.
- Main → Assets pack: loads · Application startup uses packaged resources.
- Main → Game: starts · Main creates the game runtime.
- Game → Game loop: runs · Game owns the frame loop.
- Game → Game state: manages · Game coordinates the active state.
- Game loop → Input: polls · Loop routes user input into commands.
- Game loop → Game state: ticks · Per-frame updates advance game state.
- Game state → Level: owns · State tracks the active level.
- Game state → Systems: updates · Cross-cutting progression systems advance with state.
- Input → Player: controls · Player actions originate from input handling.
- Collision → Player: resolves · Physics interactions affect the player.
- Collision → Enemies: resolves · Physics interactions affect enemies and hazards.
- Camera → Level: tracks · Camera follows the active world area.
- Level loader → Level defs: instantiates · Loader turns authored levels into runtime structures.
- Level loader → Registries: binds · Registries map authored identifiers to runtime types.
- Level loader → Sprites: uses · Level loading relies on packaged visual and collision assets.
- Level → Player: contains · Level hosts the playable character.
- Level → Enemies: contains · Level hosts hostile entities.
- Level → Interactables: contains · Level hosts interactive objects.
- Level → World objects: contains · Level hosts traversal and environment objects.
- Main window → Game widget: hosts · Main window embeds the game viewport.
- Main window → Screens: shows · Main window switches between menu, quiz, and overlay screens.
- Game widget → Camera: renders via · Viewport renders the current camera slice.
- Game widget → Sprite UI: draws with · UI sprite components support the viewport and HUD.
- Screens → Sprite UI: renders with · Screens use shared sprite widgets and fonts.
- Main window → Game: wraps · Qt shell contains the gameplay runtime.
- Sprites → Sprite UI: feeds · Sprite descriptors and assets drive UI rendering.