# polarvoid/moon-engine architecture

> Architecture diagram of the GitHub repository polarvoid/moon-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/polarvoid/moon-engine
- Repository: https://github.com/polarvoid/moon-engine

## Overview

##### Project Type and Purpose
- The project is a game engine (Moon Engine) intended for game development. Its core is a Rust library that is compiled to WebAssembly with a WebGL2 rendering backend.
- The README clearly describes interactions (e.g., WASD movement controls, particle system toggles) which indicate that the engine supports interactive real-time graphics and game physics/components.

##### File Structure
- Top-level folders indicate several key aspects:
- .github – Contains GitHub workflows for continuous integration (including code analysis and wasm-pack workflows).
- docs – Houses pre-built WebAssembly modules, JavaScript bootstrap files, textures, and an HTML demo providing developer documentation.
- moon – The core project directory. Inside, you find:
○ Cargo configuration, Rust source files (under src), and tests – These represent the static engine code, with modules like camera.rs, collider.rs, renderer.rs, shader.rs, and more, each encapsulating specific gameplay and rendering functionality.
○ www – Contains a demo application that includes index.html, JavaScript files (index.js, bootstrap.js), Node.js configuration (package.json, webpack.config.js), and associated resources (textures). This acts as the frontend layer that integrates with the compiled wasm engine.
- The separation between the core engine (Rust) and the demo (web frontend) is evident, pointing toward a layered architecture.

##### README for Additional Insights
- The README details build instructions using wasm-pack (for Rust to WebAssembly compilation) and Node.js for running a demo server. It explains controls and usage, and provides guidance for both build and development.
- The README confirms the integration of Rust (compiled to wasm) with WebGL2 rendering via the browser, hinting at a clear communication channel between WebAssembly and JavaScript.

a. Main Components to Include:
- Core Engine (Rust Library)
- Sub-modules: camera, collider, component, gl, input, math, mesh, particle, renderer, shader, texture, transform, ui, utils, web.
- How these modules collaborate to process game logic and render graphics.
- WebAssembly Module
- Represents the compiled output coming from the Rust source, using wasm-pack.
- Web Frontend (Demo Application)
- Located in the moon/www directory, includes JavaScript bootstrap files, webpack configuration, and the index.html.
- This layer loads the WebAssembly module and provides a runtime environment for the game demo.
- Development & Build Tools:
- Tools like wasm-pack (for building the wasm module), Node.js/npm (for managing the demo application), and CI/CD configurations from .github (GitHub, Travis, Appveyor).

b. Relationships and Interactions:
- A directional flow from the Rust Core Engine to the WebAssembly Module (indicate compilation).
- How the WebAssembly Module interacts with the WebGL2 Renderer (part of the engine) to process rendering commands.
- Build and deployment pipelines that use CI/CD workflows (from .github and others) to automate builds/deployments.

c. Important Architectural Patterns:
- Layered Architecture: Separate the core engine (logic & rendering) from the web frontend interface.
- Integration via WebAssembly: Clearly mark the cross-compilation and integration swirl between Rust code and JavaScript runtime.

d. Technologies & Frameworks:
- Rust (core language for the engine).
- WebAssembly (compiled module produced by wasm-pack).
- WebGL2 (rendering backend).
- Node.js & npm (for managing the demo app and build processes).
- CI/CD tools (GitHub workflows, Travis CI, AppVeyor).

##### Final Recommendations
- Integration between the compiled wasm module and the JavaScript loaded in the www directory is well represented, showing how the WebAssembly interacts with the browser’s WebGL2 context.
- Avoid over-simplifying: capturing each key contact point—from code module decomposition to build and deployment—is essential for an accurate architecture view.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD & Build Tools
    subgraph "CI/CD & Build Tools"
        CIC1["GitHub Workflows"]
        CIC2["Travis & AppVeyor"]
    end

    %% Core Engine (Rust Library)
    subgraph "Core Engine (Rust Library)"
        CORE1["Camera"]
        CORE2["Collider"]
        CORE3["Component"]
        CORE4["OpenGL/Rendering Context"]
        CORE5["Input Handling"]
        CORE6["Math Utilities"]
        CORE7["Mesh Management"]
        CORE8["Particle System"]
        CORE9["Renderer"]
        CORE10["Shader Management"]
        CORE11["Texture Handling"]
        CORE12["Transformations"]
        CORE13["User Interface"]
        CORE14["Utility Functions"]
        CORE15["Web Integration"]
    end

    %% WebAssembly Module
    subgraph "WebAssembly Module"
        WASM1["Built WASM Modules"]
        WASM2["WASM JS Bootstrap"]
    end

    %% Demo Frontend
    subgraph "Demo Frontend"
        FRONT1["index.html"]
        FRONT2["index.js"]
        FRONT3["bootstrap.js"]
        FRONT4["package.json"]
        FRONT5["webpack.config.js"]
        FRONT6["Textures"]
    end

    %% Documentation
    subgraph "Documentation"
        DOC1["Developer Documentation"]
    end

    %% Connections
    CIC1 -->|"triggerBuild"| CORE1
    CIC2 -->|"triggerBuild"| CORE1

    CORE3 -->|"compiledViaWasmPack"| WASM1
    WASM1 -->|"bootstrappedBy"| WASM2
    WASM2 -->|"integratedIn"| FRONT1
    FRONT1 -->|"servesAssets"| DOC1

    %% Styling Classes
    class CIC1,CIC2 cicd
    class CORE1,CORE2,CORE3,CORE4,CORE5,CORE6,CORE7,CORE8,CORE9,CORE10,CORE11,CORE12,CORE13,CORE14,CORE15 core
    class WASM1,WASM2 wasm
    class FRONT1,FRONT2,FRONT3,FRONT4,FRONT5,FRONT6 frontend
    class DOC1 docs

    %% Click Events for CI/CD & Build Tools
    click CIC1 "https://github.com/polarvoid/moon-engine/tree/main/.github/workflows/"
    click CIC2 "https://github.com/polarvoid/moon-engine/blob/main/moon/.travis.yml"

    %% Click Events for Core Engine Modules
    click CORE1 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/camera.rs"
    click CORE2 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/collider.rs"
    click CORE3 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/component.rs"
    click CORE4 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/gl.rs"
    click CORE5 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/input.rs"
    click CORE6 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/math.rs"
    click CORE7 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/mesh.rs"
    click CORE8 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/particle.rs"
    click CORE9 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/renderer.rs"
    click CORE10 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/shader.rs"
    click CORE11 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/texture.rs"
    click CORE12 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/transform.rs"
    click CORE13 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/ui.rs"
    click CORE14 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/utils.rs"
    click CORE15 "https://github.com/polarvoid/moon-engine/blob/main/moon/src/web.rs"

    %% Click Events for WebAssembly Module
    click WASM1 "https://github.com/polarvoid/moon-engine/tree/main/docs/"
    click WASM2 "https://github.com/polarvoid/moon-engine/blob/main/docs/10.bootstrap.js"

    %% Click Events for Demo Frontend
    click FRONT1 "https://github.com/polarvoid/moon-engine/blob/main/moon/www/index.html"
    click FRONT2 "https://github.com/polarvoid/moon-engine/blob/main/moon/www/index.js"
    click FRONT3 "https://github.com/polarvoid/moon-engine/blob/main/moon/www/bootstrap.js"
    click FRONT4 "https://github.com/polarvoid/moon-engine/blob/main/moon/www/package.json"
    click FRONT5 "https://github.com/polarvoid/moon-engine/blob/main/moon/www/webpack.config.js"
    click FRONT6 "https://github.com/polarvoid/moon-engine/tree/main/moon/www/texture"

    %% Click Event for Documentation
    click DOC1 "https://github.com/polarvoid/moon-engine/tree/main/docs/"

    %% Class Definitions for Coloring
    classDef cicd fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef wasm fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef frontend fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef docs fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
