How el8azaly/scavenger_hunt works
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: Level.cpp Level · Game.cpp Game · GameState.cpp Game state · main.cpp Main
Components 23
Entry & build
Application bootstrap and packaging wiring.
- Main · Qt application startup.
main.cpp - Build · Project configuration and target wiring.
CMakeLists.txt - Assets pack · Resource manifest for packaged assets.
resources.qrc
Runtime core
Game orchestration, simulation services, and world state.
- Game · Top-level game bootstrap and ownership boundary.
core/Game.cpp - Game loop · Per-frame update and timing control.
core/GameLoop.cpp - Game state · Active state and transition management.
core/GameState.cpp - Level · Runtime representation of the current level.
core/Level.cpp - Input · Translates user actions into gameplay commands.
engine/InputHandler.cpp - Collision · Resolves world interactions and overlaps.
engine/CollisionEngine.cpp - Camera · Tracks the visible portion of the world.
engine/Camera.cpp
Gameplay model
Entities and cross-cutting progression systems.
- Player · Main controllable character.
entities/Player.cpp - Enemies · Hostile actors and damage-bearing entities.
entities/Enemy.cpp - Interactables · Doors, containers, NPCs, and other interactive objects.
entities/InteractiveObject.cpp - World objects · Static platforms, hidden areas, and other traversal features.
entities/StaticPlatform.cpp - Systems · Inventory, quests, scoring, and level progression.
systems/LevelManager.cpp
Qt UI
Windowing, screens, HUD, and sprite presentation.
- Main window · Hosts the game viewport and overlay screens.
ui/MainWindow.cpp - Game widget · Actual game rendering surface and input target.
ui/GameWidget.cpp - Screens · Main menu, quiz dialog, and in-game overlay.
ui/screen/MainMenuScreen.cpp - Sprite UI · Reusable UI sprite and text rendering components.
ui/sprite/AnimatedSprite.cpp
Content pipeline
Authored data, level definitions, and packaged assets.
- Level loader · Loads authored level data into runtime objects.
data/LevelLoader.cpp - Level defs · Level-specific data and configuration.
data/levels/Level0.cpp - Registries · Entity and item lookup plus item definitions.
data/EntityRegistry.h - Sprites · Packaged sprite sheets, level layers, and descriptor files.
assets/sprites/levels/level0_bottom.json
Connections 27
- 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.