# galacean/engine architecture

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

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

## Overview

##### Main Components
- Core Engine: The central module (found under packages/core) that manages components such as scene management, entity/component systems, rendering pipelines, asset management, and core utilities.
- Graphics Module: Encompassing 2D and 3D graphics; it includes modules for shaders, materials, meshes, textures, and lighting, distributed among packages like rhi‑webgl, shader‑lab, and shader‑shaderlab.
- Animation System: Contains support for animation clips, animators, state machines, and interpolation, evident in packages/core/animation.
- Physics & Collision: There are various physics implementations (physics‑lite and physics‑physx) along with support for physics scenes, colliders, joints, and forces.
- UI System: The engine’s GUI capabilities, provided by packages/ui, which include canvas, interactive components, and event handing suitable for dynamic GUI.
- XR Support: XR modules come in several parts (packages/xr, xr‑webxr) handling XR input, session management, and trackable features.
- Loader & Asset Management: The packages/loader contain various loaders (GLTF, KTX, prefab, etc.) designed to deserialize and load external assets.
- Math & Utility Libraries: Modules like packages/math provide essential support (vectors, matrices, bounding volumes, collision utilities, etc.).
- Editor and Development Tools: Documentation, examples, tests, and e2e are included to showcase usage and ensure quality.

##### Relationships and Interactions
- The Core Engine serves as the central orchestrator for the engine’s subsystems. It initializes the rendering pipelines, asset managers, and scene managers.
- Graphics and shader modules interact closely with the core engine to render both 2D and 3D scenes. The shader modules (shader‑lab and shader‑shaderlab) provide the shader logic and compile shaders that run on the GPU.
- The Animation and Physics systems both attach to entities managed by the core engine, updating state each frame.
- The UI system sits on top of the rendering engine, receiving input through shared mechanisms found in the input modules.
- Loader and asset management modules feed required resources (like textures, models, audio, etc.) into the core engine.
- XR modules interact with input and rendering to provide immersive experiences.
- Math and utility libraries are cross‑cutting and used by nearly all other modules for calculations and common helper functions.

##### Architectural Patterns & Design Principles
- Component-Based Architecture: Each entity in a scene is built from components (e.g., rendering, animation, physics) that can be composed flexibly.
- Modular/Plugin Structure: The engine is split into multiple packages distributed within a monorepo, facilitating scalability and independent upgrades.
- Separation of Concerns: Graphics, physics, input, and asset loading are all logically separated, with clear APIs and data flows.
- Event-Driven Updates: Several subsystems use events (from input or physics triggers) to signal changes or transitions, as seen in event dispatcher utilities.

##### Additional Notes for the Principal Software Engineer
- Be detailed in capturing every essential architectural element and interconnection.
- Explicit dependencies (e.g., how the loader modules interact with asset management in the core engine).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Subsystems"
        A["Animation System"]:::animation
        subgraph "Graphics Module"
            GW["RHI-WebGL"]:::graphics
            SL["Shader Lab"]:::graphics
            SSL["Shader ShaderLab"]:::graphics
        end
        subgraph "Physics & Collision"
            PL["Physics Lite"]:::physics
            PP["Physics PhysX"]:::physics
        end
        U["UI System"]:::ui
        subgraph "XR Support"
            XR["XR Module"]:::xr
            XW["XR WebXR"]:::xr
        end
        L["Loader & Asset Management"]:::loader
    end

    C["Core Engine: Scene & Entity Management"]:::core

    subgraph "Utilities"
        ML["Math Library"]:::utility
        CU["Core Utils"]:::utility
    end

    C -->|"manage"| A
    C -->|"render"| GW
    C -->|"render"| SL
    C -->|"render"| SSL
    C -->|"update"| PL
    C -->|"update"| PP
    C -->|"interface"| U
    C -->|"integrate"| XR
    XR -->|"session"| XW
    L -->|"loadAssets"| C

    C -.->|"uses"| ML
    A -.->|"uses"| ML
    GW -.->|"uses"| ML
    SL -.->|"uses"| ML
    SSL -.->|"uses"| ML
    PL -.->|"uses"| ML
    PP -.->|"uses"| ML
    U -.->|"uses"| ML
    XR -.->|"uses"| ML
    XW -.->|"uses"| ML

    C -.->|"utils"| CU
    L -.->|"utils"| CU

    click C "https://github.com/galacean/engine/tree/main/packages/core"
    click A "https://github.com/galacean/engine/tree/main/packages/core/src/animation"
    click GW "https://github.com/galacean/engine/tree/main/packages/rhi-webgl"
    click SL "https://github.com/galacean/engine/tree/main/packages/shader-lab"
    click SSL "https://github.com/galacean/engine/tree/main/packages/shader-shaderlab"
    click PL "https://github.com/galacean/engine/tree/main/packages/physics-lite"
    click PP "https://github.com/galacean/engine/tree/main/packages/physics-physx"
    click U "https://github.com/galacean/engine/tree/main/packages/ui"
    click XR "https://github.com/galacean/engine/tree/main/packages/xr"
    click XW "https://github.com/galacean/engine/tree/main/packages/xr-webxr"
    click L "https://github.com/galacean/engine/tree/main/packages/loader"
    click ML "https://github.com/galacean/engine/tree/main/packages/math"
    click CU "https://github.com/galacean/engine/tree/main/packages/core/src/utils"

    classDef core fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef animation fill:#98FB98,stroke:#2E8B57,stroke-width:2px;
    classDef graphics fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
    classDef physics fill:#E6E6FA,stroke:#9370DB,stroke-width:2px;
    classDef ui fill:#F0E68C,stroke:#BDB76B,stroke-width:2px;
    classDef xr fill:#FFA07A,stroke:#FF4500,stroke-width:2px;
    classDef loader fill:#90EE90,stroke:#008000,stroke-width:2px;
    classDef utility fill:#D3D3D3,stroke:#A9A9A9,stroke-width:2px;
```
