Before implementing OpenGL, physics, or window creation, we need to define the engine’s module layout. This blueprint determines:

• the cleanliness of the codebase
• how easily the engine can be extended
• the predictability of its dependencies
• its long-term maintainability

A strong module layout separates a hobby project from a production-quality engine.

This article defines the core modules, their responsibilities and boundaries, and the way they interact.

The engine consists of six primary modules, each with one clear responsibility.

Responsible for:

• vectors
• matrices
• transforms
• coordinate spaces
• numerical utilities

This module contains pure logic: no OpenGL and no platform-specific code. It supports both rendering and simulation.

Responsible for:

• window creation
• OpenGL context
• input events
• timing

This module handles all platform-specific functionality, including window creation, input events, and timing. It abstracts away the underlying OS and library details from the rest of the engine.

Responsible for:

• shaders
• buffers
• textures
• materials
• draw submission
• camera
• scene traversal

The renderer is GPU-focused and data-driven. It depends on math and platform, while no other module depends on it.

Responsible for:

• loading assets
• caching resources
• managing lifetimes
• preventing duplication

This module ensures that:

• textures aren’t loaded twice
• shaders are reused
• meshes are cached

It serves as the engine’s “asset manager”.

Responsible for:

• physics
• collisions
• integration
• world updates
• deterministic stepping

Simulation depends on math, but not on renderer. This separation ensures physics can run headless.

Responsible for:

• logging
• debugging tools
• profiling
• small helpers

This module provides shared utilities without creating dependency cycles.

A clear folder structure keeps the engine organized as it grows.

engine/
    include/
        math/
        platform/
        renderer/
        resources/
        simulation/
        utils/
    src/
        math/
        platform/
        renderer/
        resources/
        simulation/
        utils/
examples/
thirdparty/
CMakeLists.txt

Key principles:

• include/ stores public headers
• src/ stores private implementation files
• A module never includes another module’s src/ directory
• Global headers are not allowed
• Mixed-responsibility “god folders” are not allowed

This structure scales cleanly with the engine.

Public headers (in include/):

• define the module’s public API
• expose only what consumers need
• hide internal implementation details

Private headers (in src/):

• support internal helpers
• contain implementation details
• remain inaccessible outside the module

This separation keeps module boundaries explicit.

Each module has its own CMakeLists:

add_library(engine_math)
target_sources(engine_math PRIVATE src/*.cpp)
target_include_directories(engine_math PUBLIC include)

This approach keeps:

• modules independent
• linking explicit
• dependencies visible

The engine must prevent dependency cycles and hidden coupling.

math        → (no dependencies)
platform    → math
renderer    → math, platform
resources   → math, renderer
simulation  → math
utils       → (no dependencies)

renderer    → simulation
simulation  → renderer
platform    → renderer
any module  → utils internals
any module  → another module’s src/

These constraints protect the architecture from gradual breakdown.

Maintainability: The renderer can change without disrupting physics.

Testability: Simulation can be tested without a GPU.

Extensibility: New modules can be added without rewriting existing ones.

Clarity: Developers can quickly determine where each piece of code belongs.

GusOnGames is part of a broader ecosystem:

• btm framework
• BeforeTheMesh
• TheMeshProject
• GusOnGames

GusOnGames covers:

• simple game development
• interactive graphics
• real time physics simulation
• educational visualization
• approachable engine architecture

BeforeTheMesh and TheMeshProject cover:

• computational engineering
• numerical methods
• CAE workflows
• mesh generation
• simulation pipelines
• scientific visualization

Despite overlap in mathematics, simulation, and rendering, these domains differ fundamentally in:

• audience
• complexity
• performance constraints
• tooling
• architecture
• design philosophy

GusOnGames therefore remains a standalone framework, not a shared base for CAE projects.

Different goals

• GusOnGames aims for:
• clarity
• simplicity
• real time responsiveness
• educational value
• small, modular systems
• CAE projects aim for:
• precision
• numerical stability
• large datasets
• offline or semi real time computation
• complex pipelines

Different performance profiles

• Games require:
• fast rendering
• predictable frame pacing
• lightweight physics
• CAE requires:
• heavy numerical computation
• mesh operations
• solvers
• multi step pipelines

Different user expectations

• GusOnGames readers want:
• approachable tutorials
• simple examples
• clear architecture
• real-time feedback
• CAE users want:
• engineering rigor
• numerical correctness
• domain-specific tooling
• advanced workflows

• No shared engine code
• No shared module layout
• No shared architectural constraints
• Only shared engineering philosophy

The GusOnGames engine is free to evolve according to the needs of simple games and physics simulations — without inheriting the complexity of CAE tools.

• GusOnGames engine = standalone, simple, modular, real-time
• BeforeTheMesh / TheMeshProject = independent, CAE focused, complex
• No shared code
• No shared architecture
• Only shared engineering mindset

This keeps the GusOnGames engine clean, focused, and true to its purpose.

This article established the engine’s architectural foundation:

• six focused core modules
• a scalable folder structure
• strict dependency rules
• clear public and private boundaries
• consistent multi-repository integration

This layout forms the engine’s backbone and provides the foundation for every article that follows.