# playcanvas/engine architecture

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

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

## Overview

##### Project Type and Purpose
- This is a game engine intended for running interactive 3D content and games in web browsers.
- The README makes it clear that its purpose is to support advanced 3D graphics, robust physics (via ammo.js integration), input handling, animation, asset streaming, and scripting.
- Usability in conjunction with the PlayCanvas Editor also suggests that it is designed for extensibility and real-time interactive workflows.

##### File Structure Insights
- The top-level directories include:
- “src” that contains core engine code (math, core utilities, platform abstraction, polyfills),
- “framework” which holds game system components (entities, rendering components, script system, physics, various component systems such as audio, camera, model, etc.),
- “scene” which provides scene management, geometry, materials, shader libraries, and rendering pipelines,
- “examples” and “test” folders that showcase how engine features are utilized and validated.
- Other directories like “scripts,” “utils,” “examples/assets,” “lib” (for third party libraries like ammo, draco, basis, glslang) indicate modularity and support for asset loading, physics, data compression, and shader management.
- Build scripts and configuration files (e.g., rollup.config.mjs, tsconfig.json) reinforce a well-organized build process.

##### Key Components
a. Core Engine Layer:
- Core utilities (math, arrays, events, logging, preprocessor)
- Platform Abstractions (graphics, audio, input, network)
- Polyfills (to enable compatibility)
b. Framework Layer:
- Component System for game entities (scripts, animation, physics, camera, models, sound, UI, etc.)
- Asset management and bundling
- Animation blending, state graph and evaluation subsystems
c. Scene and Rendering Pipeline:
- Scene graph management (nodes, components, spatial organization)
- Rendering subsystems (shaders, materials, lighting, post-processing, shadow mapping)
- Scene-related utilities (geometry, batching, immediate rendering, skybox)
d. External Libraries and Integrations:
- Physics engine (ammo.js integration)
- Compression libraries (Draco, Basis)
- Shader processing libraries (glslang, twgsl)
e. Build and Development Tools:
- Build scripts (rollup, TypeScript configurations)
- Testing framework (unit tests across core, framework, scene, etc.)

##### Relationships and Interactions
- Data flows from the core engine to the higher-level framework components; for example, the math and graphics utilities (in “src”) are consumed by the rendering pipeline (in “scene”) and the game logic (in “framework”).
- The framework layer manages game entities that are composed of multiple components (camera, light, model, script, audio, etc.) and orchestrates their interactions.
- The asset management system and external libraries work in tandem to load, decode and manage resources, feeding the scene and rendering pipeline.
- There is a clear separation of concerns where the rendering engine exclusively handles visuals, while physics, audio, and input are encapsulated in their own modules with defined interfaces interacting with the game loop.
- Build tools and testing scripts are linked to continuous integration flows (as observed in the “.github/workflows” directory) to ensure quality and maintainability.

##### Architectural Patterns and Design Principles
- Modular Design: Each subsystem (graphics, input, physics, animation) is organized in its own directory and exposed via well-defined APIs.
- Entity-Component-System (ECS) pattern: The engine represents game objects as entities with attached components, promoting reusability and decoupling.
- Layered Architecture: Core utilities at the base, abstracted platform and framework layers, and finally the scene/rendering system form logical tiers.
- Asynchronous Asset Loading: Given the presence of reference to glTF, Draco, and Basis, the asset pipeline supports non-blocking resource management.
- Extensibility and Integration: With a distinct separation between the engine’s core and external libraries, integrations (like with the PlayCanvas Editor) are streamlined.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Engine Layer"
        CU("Core Utilities"):::core
        Poly("Polyfills"):::core
        subgraph "Platform Abstractions"
            Gfx("Graphics"):::platform
            Au("Audio"):::platform
            In("Input"):::platform
            Net("Network"):::platform
            Sd("Sound"):::platform
        end
    end

    subgraph "Framework Layer"
        CS("Component Systems"):::framework
        AM("Asset Management"):::framework
        SS("Scripting System"):::framework
    end

    subgraph "Scene and Rendering Pipeline"
        SR("Scene Graph & Rendering"):::scene
    end

    subgraph "External Libraries & Integrations"
        Phys("Physics Engine (ammo.js)"):::external
        Drac("Compression (Draco)"):::external
        Base("Compression (Basis)"):::external
        Gls("Shader Processing (glslang)"):::external
        Twg("Shader Processing (twgsl)"):::external
    end

    subgraph "Build & Development Tools"
        Roll("Rollup Config"):::tools
        TS("TypeScript Config"):::tools
        CIW("CI Workflows"):::tools
    end

    %% Relationships between Core Engine and Framework Layer
    CU -->|"provides"| CS
    Poly -->|"provides"| CS
    Gfx -->|"API"| CS
    Au  -->|"API"| CS
    In  -->|"API"| CS
    Net -->|"API"| CS
    Sd  -->|"API"| CS

    %% Relationships within Framework and Scene
    CS -->|"uses"| AM
    CS -->|"updates"| SR
    AM -->|"feeds"| SR
    SS -->|"integrates with"| CS

    %% External Libraries integrations
    Phys -->|"integrates"| CS
    Drac -->|"optimizes"| AM
    Base -->|"optimizes"| AM
    Gls -->|"processes"| SR
    Twg -->|"processes"| SR

    %% Build & Development Tools support the engine
    Roll -->|"builds"| CU
    TS -->|"builds"| CU
    CIW -->|"tests"| CU
    CIW -->|"tests"| CS
    CIW -->|"tests"| SR

    %% Style definitions
    classDef core fill:#F8C471,stroke:#000,stroke-width:1px;
    classDef platform fill:#AED6F1,stroke:#000,stroke-width:1px;
    classDef framework fill:#A9DFBF,stroke:#000,stroke-width:1px;
    classDef scene fill:#F5B7B1,stroke:#000,stroke-width:1px;
    classDef external fill:#D2B4DE,stroke:#000,stroke-width:1px;
    classDef tools fill:#F9E79F,stroke:#000,stroke-width:1px;

    %% Click Event mappings
    click CU "https://github.com/playcanvas/engine/tree/main/src/core"
    click Poly "https://github.com/playcanvas/engine/tree/main/src/polyfill"
    click Gfx "https://github.com/playcanvas/engine/tree/main/src/platform/graphics"
    click Au "https://github.com/playcanvas/engine/tree/main/src/platform/audio"
    click In "https://github.com/playcanvas/engine/tree/main/src/platform/input"
    click Net "https://github.com/playcanvas/engine/tree/main/src/platform/net"
    click Sd "https://github.com/playcanvas/engine/tree/main/src/platform/sound"
    click CS "https://github.com/playcanvas/engine/tree/main/src/framework/components"
    click AM "https://github.com/playcanvas/engine/tree/main/src/framework/asset"
    click SS "https://github.com/playcanvas/engine/tree/main/src/framework/script"
    click SR "https://github.com/playcanvas/engine/tree/main/src/scene"
    click Phys "https://github.com/playcanvas/engine/tree/main/examples/src/lib/ammo"
    click Drac "https://github.com/playcanvas/engine/tree/main/examples/src/lib/draco"
    click Base "https://github.com/playcanvas/engine/tree/main/examples/src/lib/basis"
    click Gls "https://github.com/playcanvas/engine/tree/main/examples/src/lib/glslang"
    click Twg "https://github.com/playcanvas/engine/tree/main/examples/src/lib/twgsl"
    click Roll "https://github.com/playcanvas/engine/blob/main/rollup.config.mjs"
    click TS "https://github.com/playcanvas/engine/blob/main/tsconfig.json"
    click CIW "https://github.com/playcanvas/engine/tree/main/.github/workflows"
```
