# kamrulhasan12345/qbert-project architecture

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

- Interactive diagram: https://gitdiagram.com/kamrulhasan12345/qbert-project
- Repository: https://github.com/kamrulhasan12345/qbert-project

## Overview

This repository is a C++ arcade-game project centered on a Q*bert implementation, but it also bundles a reusable graphics/audio framework and several sample/demo games built on top of that framework.

1. Core runtime boundary  
The main application entry point is `iMain.cpp`. It likely hosts the game loop and wires the game-specific logic into the engine layer. The runtime is a native desktop executable, not a browser or service.

2. Rendering subsystem  
Graphics are handled through a custom wrapper in `iGraphics.h`, backed by OpenGL and GLUT. The repo bundles OpenGL/GLUT headers and libraries under `OpenGL/` and `MINGW/`, which means rendering is intended to be self-contained for Windows builds. The game assets are mostly bitmap sprites and static screens.

3. Audio subsystem  
Sound is separated into `iSound.h` and uses SDL2 audio/mixer-style assets, based on the README and the presence of `.wav` and `.mp3` files. The audio layer plays background music plus short event sounds for gameplay actions such as movement, hits, and UI events.

4. Game logic layer  
The Q*bert-specific logic lives above the engine layer and is responsible for menu state, gameplay state, level progression, enemy behavior, scoring, and win/lose flow. The README calls out player movement, enemies, power-ups, and level completion as the main mechanics.

5. Asset pipeline  
Runtime content is file-based and local. Game art is stored in `assets/images/` and `assets/images/sprites/`, while audio is in `assets/sounds/`. The repo also contains many per-demo and per-game asset folders under `demo/`, showing that the framework is reused for multiple mini-games with separate image/sound packs.

6. Persistence and save data  
The project uses plain files for persistent data rather than a database or remote backend. The `saves/` directory contains high scores, player names, level data, and resume state. Several demo subprojects also maintain their own `.dat`, `.txt`, or `.cfg` files for save/score/settings data.

7. Cross-platform build boundary  
Build and run are driven by scripts: `build.bat` / `build.sh` and `runner.bat` / `runner.sh`. The repository is structured to support both Windows and Linux, but the presence of a full MinGW toolchain and Windows import libraries suggests Windows is the primary packaged environment, with Linux support relying more on system-installed dependencies.

8. Bundled toolchain and dependencies  
`MINGW/` contains a full GCC/MinGW distribution, and `OpenGL/` contains platform libraries, headers, and DLLs for OpenGL, GLUT, SDL2, FreeGLUT, and FreeType. These directories are effectively vendored build/runtime dependencies, which reduces external setup but makes the repo much larger and more self-contained.

9. Reusable examples and demos  
`examples/` contains focused tutorial-style programs for input, timers, images, sounds, fonts, files, sprites, and simple drawing. `demo/` contains larger standalone games such as `dxball`, `catch_the_egg`, `gems_collector`, `last_man_standing`, and `survival_racing`. Architecturally, these demonstrate that the engine is meant to be reused as a small game framework, not only for Q*bert.

10. Testing and verification  
`tests/windows-test.py` and `tests/linux-test.py` indicate simple platform-specific validation scripts, likely used to check build/run behavior. This suggests the repo’s quality gate is mostly integration-oriented rather than unit-test-heavy.

11. Diagram boundaries to capture  
An accurate architecture diagram should separate:  
- the Q*bert game module (`iMain.cpp` and game logic),  
- the reusable engine layer (`iGraphics.h`, `iSound.h`, related headers),  
- external runtime libraries (OpenGL/GLUT/SDL2),  
- bundled toolchains (`MINGW`, `OpenGL`),  
- and file-based content/persistence (`assets/`, `saves/`, demo data files).

12. Data flow summary  
User input from keyboard/mouse enters the engine layer, which updates game state. Game state drives rendering via OpenGL/GLUT and triggers audio playback through the sound layer. The game also reads static assets at startup and writes score/save data to local files during or after play.

Main entry points: [`demo`](https://github.com/kamrulhasan12345/qbert-project/tree/main/demo) (Demo Games), [`iGraphics.h`](https://github.com/kamrulhasan12345/qbert-project/blob/main/iGraphics.h) (Graphics API), [`iSound.h`](https://github.com/kamrulhasan12345/qbert-project/blob/main/iSound.h) (Sound API), [`OpenGL`](https://github.com/kamrulhasan12345/qbert-project/tree/main/OpenGL) (OpenGL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_i_main["iMain.cpp<br/>entrypoint<br/>[iMain.cpp]"]
end

subgraph group_engine["Engine"]
  node_graphics_api["Graphics API<br/>render wrapper<br/>[iGraphics.h]"]
  node_sound_api["Sound API<br/>audio wrapper<br/>[iSound.h]"]
  node_font_api["Font API<br/>text rendering<br/>[iFont.h]"]
end

subgraph group_game["Q*bert"]
  node_game_state(("Game State<br/>qbert logic"))
  node_gameplay_mechanics(("Gameplay<br/>rules"))
end

subgraph group_content["Content"]
  node_assets_images[("Images<br/>sprite assets")]
  node_assets_sounds[("Sounds<br/>audio assets")]
  node_saves[("Saves<br/>local persistence")]
end

subgraph group_tooling["Tooling"]
  node_opengl_bundle["OpenGL<br/>vendored runtime libs"]
  node_mingw_bundle["MinGW<br/>vendored toolchain"]
  node_build_scripts["Build Scripts<br/>cross-platform build<br/>[build.sh]"]
  node_tests["Platform Tests<br/>verification"]
end

subgraph group_demos["Demos"]
  node_examples["Examples<br/>tutorials"]
  node_demo_suite["Demo Games<br/>sample games"]
  node_dxball["dxball<br/>sample game"]
  node_catch_egg["catch_the_egg<br/>sample game"]
end

node_i_main -->|"renders via"| node_graphics_api
node_i_main -->|"plays audio"| node_sound_api
node_i_main -->|"hosts"| node_game_state
node_game_state -->|"uses"| node_gameplay_mechanics
node_game_state -->|"loads"| node_assets_images
node_game_state -->|"triggers"| node_assets_sounds
node_game_state -->|"reads/writes"| node_saves
node_graphics_api -->|"backed by"| node_opengl_bundle
node_sound_api -->|"uses SDL2"| node_opengl_bundle
node_font_api -->|"backed by"| node_opengl_bundle
node_build_scripts -->|"uses"| node_mingw_bundle
node_build_scripts -->|"links against"| node_opengl_bundle
node_tests -->|"verifies"| node_build_scripts
node_examples -->|"demonstrate"| node_graphics_api
node_examples -->|"demonstrate"| node_sound_api
node_examples -->|"demonstrate"| node_font_api
node_demo_suite -->|"built on"| node_graphics_api
node_demo_suite -->|"built on"| node_sound_api
node_demo_suite -->|"includes"| node_dxball
node_demo_suite -->|"includes"| node_catch_egg
node_dxball -->|"uses assets"| node_assets_images
node_dxball -->|"uses assets"| node_assets_sounds
node_catch_egg -->|"uses assets"| node_assets_images
node_catch_egg -->|"uses assets"| node_assets_sounds

click node_i_main "https://github.com/kamrulhasan12345/qbert-project/blob/main/iMain.cpp"
click node_graphics_api "https://github.com/kamrulhasan12345/qbert-project/blob/main/iGraphics.h"
click node_sound_api "https://github.com/kamrulhasan12345/qbert-project/blob/main/iSound.h"
click node_font_api "https://github.com/kamrulhasan12345/qbert-project/blob/main/iFont.h"
click node_assets_images "https://github.com/kamrulhasan12345/qbert-project/tree/main/assets/images"
click node_assets_sounds "https://github.com/kamrulhasan12345/qbert-project/tree/main/assets/sounds"
click node_saves "https://github.com/kamrulhasan12345/qbert-project/tree/main/saves"
click node_opengl_bundle "https://github.com/kamrulhasan12345/qbert-project/tree/main/OpenGL"
click node_mingw_bundle "https://github.com/kamrulhasan12345/qbert-project/tree/main/MINGW"
click node_build_scripts "https://github.com/kamrulhasan12345/qbert-project/blob/main/build.sh"
click node_tests "https://github.com/kamrulhasan12345/qbert-project/tree/main/tests"
click node_examples "https://github.com/kamrulhasan12345/qbert-project/tree/main/examples"
click node_demo_suite "https://github.com/kamrulhasan12345/qbert-project/tree/main/demo"
click node_dxball "https://github.com/kamrulhasan12345/qbert-project/tree/main/demo/dxball"
click node_catch_egg "https://github.com/kamrulhasan12345/qbert-project/tree/main/demo/catch_the_egg"

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_i_main toneBlue
class node_graphics_api,node_sound_api,node_font_api toneAmber
class node_game_state,node_gameplay_mechanics toneMint
class node_assets_images,node_assets_sounds,node_saves toneRose
class node_opengl_bundle,node_mingw_bundle,node_build_scripts,node_tests toneIndigo
class node_examples,node_demo_suite,node_dxball,node_catch_egg toneTeal
```

## Components

### Runtime

Native executable and app entrypoint

- [iMain.cpp](https://github.com/kamrulhasan12345/qbert-project/blob/main/iMain.cpp): entrypoint · Application entry and main loop wiring · `iMain.cpp`

### Engine

Reusable graphics/audio framework

- [Graphics API](https://github.com/kamrulhasan12345/qbert-project/blob/main/iGraphics.h): render wrapper · Custom drawing wrapper around OpenGL/GLUT · `iGraphics.h`
- [Sound API](https://github.com/kamrulhasan12345/qbert-project/blob/main/iSound.h): audio wrapper · Game audio and mixer integration · `iSound.h`
- [Font API](https://github.com/kamrulhasan12345/qbert-project/blob/main/iFont.h): text rendering · Text and font support for UI overlays · `iFont.h`

### Q*bert

Game-specific logic and flow

- **Game State**: qbert logic · Menus, progression, scoring, and win/lose flow
- **Gameplay**: rules · Movement, enemies, power-ups, and completion logic

### Content

Assets and local persistence

- [Images](https://github.com/kamrulhasan12345/qbert-project/tree/main/assets/images): sprite assets · Bitmap sprites, screens, and sprite sheets · `assets/images`
- [Sounds](https://github.com/kamrulhasan12345/qbert-project/tree/main/assets/sounds): audio assets · Background music and gameplay sound effects · `assets/sounds`
- [Saves](https://github.com/kamrulhasan12345/qbert-project/tree/main/saves): local persistence · High scores, names, resume state, and level data · `saves`

### Tooling

Build scripts, vendored toolchain, and tests

- [OpenGL](https://github.com/kamrulhasan12345/qbert-project/tree/main/OpenGL): vendored runtime libs · Bundled OpenGL, GLUT, SDL2, and FreeType headers/libs · `OpenGL`
- [MinGW](https://github.com/kamrulhasan12345/qbert-project/tree/main/MINGW): vendored toolchain · Bundled GCC/MinGW toolchain and Windows build dependencies · `MINGW`
- [Build Scripts](https://github.com/kamrulhasan12345/qbert-project/blob/main/build.sh): cross-platform build · Windows and shell build/launch scripts · `build.sh`
- [Platform Tests](https://github.com/kamrulhasan12345/qbert-project/tree/main/tests): verification · Simple Linux and Windows build/run checks · `tests`

### Demos

Examples and bundled sample games

- [Examples](https://github.com/kamrulhasan12345/qbert-project/tree/main/examples): tutorials · Focused framework demos for input, drawing, audio, files, and sprites · `examples`
- [Demo Games](https://github.com/kamrulhasan12345/qbert-project/tree/main/demo): sample games · Standalone games built on the shared framework · `demo`
- [dxball](https://github.com/kamrulhasan12345/qbert-project/tree/main/demo/dxball): sample game · Large breakout-style demo with assets, levels, and user data · `demo/dxball`
- [catch_the_egg](https://github.com/kamrulhasan12345/qbert-project/tree/main/demo/catch_the_egg): sample game · Mini-game demo with its own assets and leaderboard/save files · `demo/catch_the_egg`

## Connections

- iMain.cpp → Graphics API: renders via · Main app drives drawing through the graphics wrapper
- iMain.cpp → Sound API: plays audio · Main app triggers background music and effects
- iMain.cpp → Game State: hosts · Entry point wires the Q*bert game module into the runtime
- Game State → Gameplay: uses · Game state advances mechanics and rules
- Game State → Images: loads · Game pulls sprites and screens from local image assets
- Game State → Sounds: triggers · Gameplay events map to sound playback
- Game State → Saves: reads/writes · Scores, names, and resume data are stored in files
- Graphics API → OpenGL: backed by · Rendering wrapper depends on bundled OpenGL/GLUT libraries
- Sound API → OpenGL: uses SDL2 · Audio layer relies on vendored SDL2/mixer runtime pieces
- Font API → OpenGL: backed by · Font rendering also sits on the bundled graphics stack
- Build Scripts → MinGW: uses · Build scripts target the packaged MinGW toolchain on Windows
- Build Scripts → OpenGL: links against · Build scripts compile with the vendored OpenGL/SDL2 stack
- Platform Tests → Build Scripts: verifies · Platform scripts exercise build and run behavior
- Examples → Graphics API: demonstrate · Tutorial programs show graphics API usage
- Examples → Sound API: demonstrate · Tutorial programs show sound API usage
- Examples → Font API: demonstrate · Tutorial programs show text/font usage
- Demo Games → Graphics API: built on · Demo games reuse the shared graphics layer
- Demo Games → Sound API: built on · Demo games reuse the shared audio layer
- Demo Games → dxball: includes · One major bundled demo game
- Demo Games → catch_the_egg: includes · Another major bundled demo game
- dxball → Images: uses assets · Demo-specific bitmaps and sprite packs
- dxball → Sounds: uses assets · Demo-specific music and effects
- catch_the_egg → Images: uses assets · Demo-specific art pack
- catch_the_egg → Sounds: uses assets · Demo-specific sounds