From fd2d4938ef9dd095e814de0c8679aa637ffd71e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Drago=C8=99-Andrei=20Bobu?= Date: Wed, 5 Aug 2026 23:48:51 +0300 Subject: [PATCH 1/2] docs: add suite architecture graphic --- docs/suite-architecture.svg | 39 +++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/suite-architecture.svg diff --git a/docs/suite-architecture.svg b/docs/suite-architecture.svg new file mode 100644 index 00000000..975f6dda --- /dev/null +++ b/docs/suite-architecture.svg @@ -0,0 +1,39 @@ + + Machine-Learning-Compatible Game Engine full-suite architecture + The suite combines a native C++ math, rendering and game layer, a set of example projects, and Python PyQt editor tools. + + + + + + + ML-Compatible Game Engine — full suite + Native graphics experiments, reusable engine primitives and Python editor tooling + + + + + + C++ engine layer + Vector3 and colour math + OpenGL primitives + GameObject components + Input state + GLUT / GLEW / GLFW-era stack + Example projects + Julia and Fourier visualisations + Pendulum simulations + Pi experiments + Tic-tac-toe and DVD bouncer + Perlin-noise terrain + Python editor layer + PyQt6 windows and tabs + Project file management + Hierarchy and inspector + Scene and terminal tabs + Scientific / ML libraries + + + + Historical prototype suite — components are partially integrated, not one packaged engine release + From 68f52c5a61f7be3f8b466895474d53d5482be08a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Drago=C8=99-Andrei=20Bobu?= Date: Wed, 5 Aug 2026 23:50:04 +0300 Subject: [PATCH 2/2] docs: add full-suite architecture and usage guide --- README.md | 391 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 391 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..78c28f53 --- /dev/null +++ b/README.md @@ -0,0 +1,391 @@ +# Machine-Learning-Compatible Game Engine — Full Suite + +**A historical experimental suite combining a small C++ graphics/game framework, visual simulation projects and a Python/PyQt editor prototype.** + +

+ Full-suite architecture +

+ +

+ C++ + OpenGL + Python + PyQt + Status +

+ +## What this repository is + +`full-suite` brings together several branches of the Machine-Learning-Compatible Game Engine concept: + +1. **A native C++ layer** containing vector mathematics, colours, drawing primitives, input tracking and lightweight game-object components. +2. **A collection of C++ visual projects** that exercise the engine through mathematical simulations, fractals, games and graphics experiments. +3. **A Python/PyQt editor prototype** with project loading, hierarchy, inspector, scene, asset and terminal-oriented UI components. +4. **Scientific and machine-learning dependencies** intended to make Python a high-level experimentation and integration layer. + +The repository should not be interpreted as a polished, versioned game-engine distribution. It is a development snapshot in which several components are useful independently but only partially integrated into one workflow. + +## Main capabilities + +### C++ engine layer + +The public header under `Engine/engine.h` defines: + +- `MathEngine::Vector3` with arithmetic, dot product and distance operations; +- `MathEngine::Color` with RGBA values and named colours; +- `RenderEngine` callbacks and primitive drawing operations; +- points, lines, rectangles, circles, fill and stroke configuration; +- `GameEngine::GameObject` with transform, rigid body, renderer and collider components; +- a keyboard input table and basic axis access. + +The implementation is split across: + +```text +Engine/math.cpp +Engine/render.cpp +Engine/game.cpp +Engine/engine.h +``` + +### Included visual projects + +The `Projects/` directory contains experiments such as: + +| Project | Focus | +|---|---| +| `julia` | Animated Julia-set rendering | +| `fourier` | Fourier-series visualisation | +| `pendulum` | Pendulum simulation | +| `double-pendulum` | Chaotic double-pendulum motion | +| `pi-collisions` | Collision-based π approximation experiment | +| `pi-monte-carlo` | Monte Carlo π estimation | +| `terrain-perlin-noise` | Procedural terrain/noise rendering | +| `dvd_bouncer` | Bouncing-logo graphics exercise | +| `tic-tac-toe` | Small interactive game | + +Several projects contain a local `compile` script and an optional `runner.cpp` or helper source. + +### Python editor layer + +The `Editor/` tree contains multiple PyQt6 entry points and UI modules: + +- splash and hub experiments; +- project selection and validation; +- main editor window; +- hierarchy and inspector panels; +- scene view; +- asset and terminal tabs; +- transform, vector and game-object widgets; +- JSON-oriented project metadata handling. + +The main editor module supports: + +```bash +python -m Editor.Editor +``` + +and a project-opening mode: + +```bash +python -m Editor.Editor OpenProject --path /path/to/project-or-projectData.json +``` + +Project validation is delegated to the editor file-manager module before the full project page is opened. + +## Architecture + +```mermaid +flowchart LR + Project[Example project main.cpp] + Header[Engine/engine.h] + Math[Engine/math.cpp] + Render[Engine/render.cpp] + Game[Engine/game.cpp] + OpenGL[OpenGL / GLUT / GLEW / GLFW stack] + Editor[Python PyQt6 editor] + Metadata[Project metadata / JSON] + Sci[NumPy, SciPy, pandas, scikit-learn] + + Project --> Header + Header --> Math + Header --> Render + Header --> Game + Render --> OpenGL + Editor --> Metadata + Editor --> Sci + Editor -. intended integration .-> Project +``` + +### Runtime callback model + +Example projects configure the native renderer with callbacks: + +```cpp +RenderEngine::setStart([]() { + RenderEngine::background(Color(255)); + RenderEngine::strokeWeight(10); + RenderEngine::stroke(0); +}); + +RenderEngine::setUpdate(update); +RenderEngine::Enabled(true); +``` + +The renderer owns the application loop and invokes project-defined startup and update behaviour. + +## Repository structure + +```text +full-suite/ +├── Engine/ +│ ├── engine.h +│ ├── math.cpp +│ ├── render.cpp +│ └── game.cpp +├── Projects/ +│ ├── julia/ +│ ├── fourier/ +│ ├── pendulum/ +│ ├── double-pendulum/ +│ ├── pi-collisions/ +│ ├── pi-monte-carlo/ +│ ├── terrain-perlin-noise/ +│ ├── dvd_bouncer/ +│ └── tic-tac-toe/ +├── Editor/ +│ ├── Editor/ +│ ├── Hub/ +│ ├── Splash/ +│ └── FileManager/ +├── requirements +├── .venv/ # Historical committed environment snapshot +├── docs/ +│ └── suite-architecture.svg +└── README.md +``` + +## Platform expectations + +The native compile scripts are currently Linux-oriented. Their link flags target the Mesa/OpenGL and X11 ecosystem: + +```text +-lGL -lGLU -lglut -ldl -lm -lglfw -lGLEW -lXi -lXmu +``` + +A Linux machine or WSL environment with GUI support is the most direct setup. Windows and macOS would require a proper cross-platform build system and platform-specific dependency configuration. + +## Native prerequisites + +On Ubuntu or Debian: + +```bash +sudo apt update +sudo apt install \ + build-essential \ + freeglut3-dev \ + libglew-dev \ + libglfw3-dev \ + libglu1-mesa-dev \ + libxi-dev \ + libxmu-dev +``` + +The exact package names may differ across distributions. + +## Run a C++ example + +### 1. Clone the repository + +```bash +git clone https://github.com/Machine-Learning-Compatible-Game-Engine/full-suite.git +cd full-suite +``` + +### 2. Compile an example + +The compile scripts assume the current directory is the repository root. For the Julia-set example: + +```bash +bash Projects/julia/compile +``` + +The script invokes: + +```bash +g++ Projects/julia/main.cpp \ + Engine/render.cpp \ + Engine/math.cpp \ + Engine/game.cpp \ + -o Projects/julia/main \ + -lGL -lGLU -lglut -ldl -lm -lglfw -lGLEW -lXi -lXmu +``` + +### 3. Run it + +```bash +./Projects/julia/main +``` + +Use the same pattern for another experiment: + +```bash +bash Projects/double-pendulum/compile +./Projects/double-pendulum/main +``` + +### Development compile with warnings + +The historical scripts do not enable strict warning flags. For investigation, add: + +```text +-std=c++17 -Wall -Wextra -Wpedantic +``` + +Some source may need cleanup before compiling without warnings. + +## Run the Python editor + +### 1. Create a clean environment + +Do not rely on the committed `.venv` directory. Virtual environments are machine-specific and should be recreated locally. + +```bash +python3 -m venv .venv-local +source .venv-local/bin/activate +``` + +On Windows PowerShell: + +```powershell +py -m venv .venv-local +.\.venv-local\Scripts\Activate.ps1 +``` + +### 2. Install Python dependencies + +The repository uses a file named `requirements` rather than the conventional `requirements.txt`: + +```bash +python -m pip install --upgrade pip +python -m pip install -r requirements +``` + +Declared packages include: + +- PyQt6 and PyOpenGL; +- NumPy, SciPy, Matplotlib and pandas; +- scikit-learn; +- Colorama and termcolor; +- pyserial. + +### 3. Start the editor + +From the repository root: + +```bash +python -m Editor.Editor +``` + +Without a project path, the editor opens its no-project page. + +To open a project: + +```bash +python -m Editor.Editor OpenProject --path ./path/to/project +``` + +The path must pass the repository's project-validation logic. + +## Example: Julia-set project + +The Julia example demonstrates the native API by: + +1. precomputing an iteration colour table; +2. installing renderer startup and update callbacks; +3. animating the complex constant over time; +4. iterating each pixel in an 800 × 800 logical field; +5. drawing points through `RenderEngine::point`. + +This makes it useful as both a graphics demonstration and a stress test for the immediate-mode point renderer. + +## Engine API sketch + +```cpp +#include "Engine/engine.h" + +void update() { + RenderEngine::background(Color::white); + RenderEngine::stroke(Color::blue); + RenderEngine::line(Vector3(-0.5, 0), Vector3(0.5, 0)); +} + +int main() { + RenderEngine::setStart([]() { + RenderEngine::strokeWeight(2); + }); + RenderEngine::setUpdate(update); + RenderEngine::Enabled(true); +} +``` + +This example illustrates the intended style. Build it with the engine implementation files and required OpenGL libraries. + +## Relationship between the layers + +The project vision is to keep responsibilities separated: + +| Layer | Primary language | Intended responsibility | +|---|---|---| +| Mathematics | C++ | Vectors, transformations and numerical primitives | +| Rendering | C++ / OpenGL | Window loop and drawing primitives | +| Game model | C++ | Game objects, components and input | +| Editor | Python / PyQt6 | Project navigation and interactive tooling | +| ML/scientific interface | Python | Experimentation with numerical and learning libraries | +| Example projects | C++ | Demonstrate and test individual engine capabilities | + +The current repository contains these layers, but the editor does not yet provide a fully reliable end-to-end authoring, build and execution pipeline for every native project. + +## Known limitations + +- There is no canonical CMake, Meson or Make-based build system. +- Each project carries a near-duplicate shell compile command. +- Native builds are tightly coupled to Linux/X11/OpenGL package names. +- The engine is a small educational abstraction, not a complete scene graph, ECS or asset pipeline. +- Rendering, input and lifecycle behaviour require deeper API documentation and tests. +- Several classes are partial; for example, the collider component is currently only a placeholder type. +- Python and C++ components are only partially integrated. +- The editor project format is not documented as a stable public schema. +- A complete machine-learning workflow is not exposed as one runnable feature. +- A full virtual environment is committed to the repository. +- Generated executables and local environment artefacts may be present. +- There is no automated test suite or CI build matrix. +- Dependency versions are not pinned. +- The `requirements` filename is unconventional and lacks hashes or a lockfile. + +## Recommended next steps + +1. Remove `.venv` and generated binaries from version control, then add a comprehensive `.gitignore`. +2. Introduce one top-level CMake project with the engine as a library and examples as targets. +3. Add a versioned public API namespace and headers separated from implementation files. +4. Add unit tests for `Vector3`, colours, input and collision behaviour. +5. Document and validate a stable `projectData.json` schema. +6. Make the editor launch, build and run native examples through one explicit adapter. +7. Replace duplicated compile scripts with reusable build commands. +8. Pin Python dependencies using `pyproject.toml` and a lockfile. +9. Add screenshots or short recordings for representative examples and editor pages. +10. Define what “machine-learning-compatible” means at the API boundary: data exchange, model lifecycle, inference hooks and reproducibility. + +## Project status + +This repository is best used as: + +- a portfolio of graphics and simulation experiments; +- a source of reusable early engine code; +- an architectural reference for the wider project; +- a migration source for a cleaner future engine repository. + +It should not yet be presented as a production-ready engine SDK. + +## License + +No explicit licence is currently included. Unless a licence is added, the source remains under the copyright holder's default rights.