# excaliburjs/excalibur architecture

> Architecture diagram of the GitHub repository excaliburjs/excalibur, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/excaliburjs/excalibur
- Repository: https://github.com/excaliburjs/excalibur

## Overview

#### Purpose and Package Boundary
Excalibur is a TypeScript 2D HTML5-canvas game engine distributed primarily as an npm package, with NuGet packaging support. Its public engine barrel is `src/engine/index.ts`; runtime orchestration starts in `src/engine/engine.ts`. The core is browser-oriented and exposes game primitives rather than a server or application backend.

#### Runtime Orchestration and Scenes
`Engine` owns the browser game loop, screen/canvas integration, clocking, and per-frame coordination. Game content is organized into scenes and actors; scene changes, asset loading, and visual transitions are managed by the director layer.
- `src/engine/engine.ts`
- `src/engine/scene.ts`
- `src/engine/director/director.ts`

Primary flow: browser frame/input events enter `Engine`; the active scene updates entities and systems; graphics are rendered; diagnostics and lifecycle events are emitted around these phases.

#### ECS and Gameplay Model
The engine uses an entity-component-system foundation. Actors are high-level game entities layered on ECS facilities; `World` manages entities, component queries, and ordered systems. This is the principal extension boundary for gameplay features and engine subsystems.
- `src/engine/actor.ts`
- `src/engine/entity-component-system/world.ts`
- `src/engine/entity-component-system/system-manager.ts`

Actions are a separate behavior pipeline: actionable entities own queues/components, and `ActionsSystem` advances sequential, parallel, movement, easing, and lifecycle actions during updates.
- `src/engine/actions/actions-system.ts`
- `src/engine/actions/action-queue.ts`

#### Physics, Collision, and Input
Physics is integrated as ECS systems over bodies and colliders. The collision system performs broad-/narrow-phase contact processing and delegates resolution to selectable arcade or realistic solvers; collision events feed gameplay code.
- `src/engine/collision/physics-world.ts`
- `src/engine/collision/collision-system.ts`
- `src/engine/collision/solver/realistic-solver.ts`

Browser keyboard, pointer, wheel, and gamepad input are normalized by the input host/systems, then pointer events can be dispatched to scene objects.
- `src/engine/input/input-host.ts`
- `src/engine/input/pointer-system.ts`
- `src/engine/input/pointer-events-to-object-dispatcher.ts`

#### Rendering and Graphics Boundary
Graphics components and `GraphicsSystem` convert scene/entity graphics into draw work. Rendering abstracts a graphics context with Canvas 2D and WebGL implementations; the WebGL backend contains specialized renderers, shaders, materials, post-processing, buffers, and render targets. This boundary isolates public graphics primitives from GPU/browser APIs.
- `src/engine/graphics/graphics-system.ts`
- `src/engine/graphics/context/excalibur-graphics-context.ts`
- `src/engine/graphics/context/excalibur-graphics-context-webgl.ts`

#### Resources, Audio, and Extensions
Resource objects load images, fonts, GIFs, and sound. Audio is backed by the browser Web Audio API through the sound manager/context/instances. Plugins provide an explicit mechanism to add engine capabilities.
- `src/engine/resources/resource.ts`
- `src/engine/resources/sound/sound-manager.ts`
- `src/engine/plugin.ts`

#### Supporting Products and Delivery
The repository also ships a React/Vite interactive playground that executes editable engine examples, a Docusaurus documentation site, and sandbox visual examples. These consume the engine rather than defining its core runtime.
- `playground/src/main.tsx`
- `site/docusaurus.config.ts`
- `sandbox/src/game.ts`

Node.js drives builds, tests, and releases. GitHub Actions publishes npm and NuGet artifacts; BrowserStack supports cross-browser validation. Packaging metadata is rooted in `package.json` and `Excalibur.nuspec`.

Main entry points: [`src/engine/engine.ts`](https://github.com/excaliburjs/excalibur/blob/main/src/engine/engine.ts) (Engine), [`src/engine/index.ts`](https://github.com/excaliburjs/excalibur/blob/main/src/engine/index.ts) (Public engine API), [`src/engine/entity-component-system/system-manager.ts`](https://github.com/excaliburjs/excalibur/blob/main/src/engine/entity-component-system/system-manager.ts) (System manager), [`src/engine/scene.ts`](https://github.com/excaliburjs/excalibur/blob/main/src/engine/scene.ts) (Scene)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_public_api["Public engine API<br/>TypeScript barrel<br/>[index.ts]"]
  node_engine["Engine<br/>runtime orchestrator<br/>[engine.ts]"]
  node_scene["Scene<br/>game content container<br/>[scene.ts]"]
  node_director["Director<br/>scene lifecycle<br/>[director.ts]"]
  node_plugins["Plugins<br/>extension API<br/>[plugin.ts]"]
end

subgraph group_gameplay["Gameplay systems"]
  node_actor["Actor<br/>high-level entity<br/>[actor.ts]"]
  node_world["World<br/>[world.ts]"]
  node_system_manager["System manager<br/>ECS scheduler<br/>[system-manager.ts]"]
  node_actions["Actions system<br/>behavior pipeline<br/>[actions-system.ts]"]
  node_action_queue["Action queue<br/>action state<br/>[action-queue.ts]"]
  node_physics["Physics world<br/>physics ECS<br/>[physics-world.ts]"]
  node_collision["Collision system<br/>contact processing"]
  node_solver["Realistic solver<br/>collision solver"]
end

subgraph group_browser["Browser boundaries"]
  node_input_host["Input host<br/>browser input adapter<br/>[input-host.ts]"]
  node_pointer_system["Pointer system<br/>ECS input system<br/>[pointer-system.ts]"]
  node_pointer_dispatch["Pointer dispatcher<br/>object event dispatch"]
  node_graphics["Graphics system<br/>ECS renderer<br/>[graphics-system.ts]"]
  node_graphics_context["Graphics context<br/>rendering abstraction"]
  node_webgl["WebGL context<br/>GPU backend"]
  node_resources["Resources<br/>asset loading<br/>[resource.ts]"]
  node_audio["Sound manager<br/>Web Audio integration<br/>[sound-manager.ts]"]
end

subgraph group_products["Products &amp; delivery"]
  node_playground["Interactive playground<br/>React/Vite consumer<br/>[main.tsx]"]
  node_docs["Documentation site<br/>Docusaurus consumer"]
  node_sandbox["Sandbox examples<br/>example consumer<br/>[game.ts]"]
end

node_public_api -->|"exports"| node_engine
node_public_api -->|"exports"| node_actor
node_engine -->|"coordinates"| node_director
node_director -->|"activates"| node_scene
node_engine -->|"updates active scene"| node_scene
node_scene -->|"contains gameplay"| node_world
node_actor -->|"participates in"| node_world
node_world -->|"runs systems through"| node_system_manager
node_system_manager -->|"schedules"| node_actions
node_actions -->|"advances"| node_action_queue
node_system_manager -->|"schedules"| node_physics
node_physics -->|"processes contacts with"| node_collision
node_collision -->|"delegates resolution"| node_solver
node_engine -->|"receives browser input"| node_input_host
node_input_host -->|"normalizes input for"| node_pointer_system
node_pointer_system -->|"dispatches pointer events"| node_pointer_dispatch
node_pointer_dispatch -->|"targets objects in"| node_scene
node_system_manager -->|"schedules"| node_graphics
node_graphics -->|"submits draw work"| node_graphics_context
node_graphics_context -->|"implemented by"| node_webgl
node_engine -->|"loads assets"| node_resources
node_resources -->|"loads sound through"| node_audio
node_plugins -.->|"extends"| node_engine
node_playground -->|"consumes"| node_public_api
node_docs -.->|"documents"| node_public_api
node_sandbox -->|"uses"| node_public_api

click node_public_api "https://github.com/excaliburjs/excalibur/blob/main/src/engine/index.ts"
click node_engine "https://github.com/excaliburjs/excalibur/blob/main/src/engine/engine.ts"
click node_scene "https://github.com/excaliburjs/excalibur/blob/main/src/engine/scene.ts"
click node_director "https://github.com/excaliburjs/excalibur/blob/main/src/engine/director/director.ts"
click node_actor "https://github.com/excaliburjs/excalibur/blob/main/src/engine/actor.ts"
click node_world "https://github.com/excaliburjs/excalibur/blob/main/src/engine/entity-component-system/world.ts"
click node_system_manager "https://github.com/excaliburjs/excalibur/blob/main/src/engine/entity-component-system/system-manager.ts"
click node_actions "https://github.com/excaliburjs/excalibur/blob/main/src/engine/actions/actions-system.ts"
click node_action_queue "https://github.com/excaliburjs/excalibur/blob/main/src/engine/actions/action-queue.ts"
click node_physics "https://github.com/excaliburjs/excalibur/blob/main/src/engine/collision/physics-world.ts"
click node_collision "https://github.com/excaliburjs/excalibur/blob/main/src/engine/collision/collision-system.ts"
click node_solver "https://github.com/excaliburjs/excalibur/blob/main/src/engine/collision/solver/realistic-solver.ts"
click node_input_host "https://github.com/excaliburjs/excalibur/blob/main/src/engine/input/input-host.ts"
click node_pointer_system "https://github.com/excaliburjs/excalibur/blob/main/src/engine/input/pointer-system.ts"
click node_pointer_dispatch "https://github.com/excaliburjs/excalibur/blob/main/src/engine/input/pointer-events-to-object-dispatcher.ts"
click node_graphics "https://github.com/excaliburjs/excalibur/blob/main/src/engine/graphics/graphics-system.ts"
click node_graphics_context "https://github.com/excaliburjs/excalibur/blob/main/src/engine/graphics/context/excalibur-graphics-context.ts"
click node_webgl "https://github.com/excaliburjs/excalibur/blob/main/src/engine/graphics/context/excalibur-graphics-context-webgl.ts"
click node_resources "https://github.com/excaliburjs/excalibur/blob/main/src/engine/resources/resource.ts"
click node_audio "https://github.com/excaliburjs/excalibur/blob/main/src/engine/resources/sound/sound-manager.ts"
click node_plugins "https://github.com/excaliburjs/excalibur/blob/main/src/engine/plugin.ts"
click node_playground "https://github.com/excaliburjs/excalibur/blob/main/playground/src/main.tsx"
click node_docs "https://github.com/excaliburjs/excalibur/blob/main/site/docusaurus.config.ts"
click node_sandbox "https://github.com/excaliburjs/excalibur/blob/main/sandbox/src/game.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_engine,node_scene,node_director,node_plugins toneBlue
class node_actor,node_world,node_system_manager,node_actions,node_action_queue,node_physics,node_collision,node_solver toneAmber
class node_input_host,node_pointer_system,node_pointer_dispatch,node_graphics,node_graphics_context,node_webgl,node_resources,node_audio toneMint
class node_playground,node_docs,node_sandbox toneRose
```

## Components

### Core runtime

- [Public engine API](https://github.com/excaliburjs/excalibur/blob/main/src/engine/index.ts): TypeScript barrel · Primary npm-facing engine exports. · `src/engine/index.ts`
- [Engine](https://github.com/excaliburjs/excalibur/blob/main/src/engine/engine.ts): runtime orchestrator · Coordinates browser frames, lifecycle, scenes, and rendering. · `src/engine/engine.ts`
- [Scene](https://github.com/excaliburjs/excalibur/blob/main/src/engine/scene.ts): game content container · `src/engine/scene.ts`
- [Director](https://github.com/excaliburjs/excalibur/blob/main/src/engine/director/director.ts): scene lifecycle · Manages scene changes, loading, and transitions. · `src/engine/director/director.ts`
- [Plugins](https://github.com/excaliburjs/excalibur/blob/main/src/engine/plugin.ts): extension API · Adds engine capabilities explicitly. · `src/engine/plugin.ts`

### Gameplay systems

- [Actor](https://github.com/excaliburjs/excalibur/blob/main/src/engine/actor.ts): high-level entity · `src/engine/actor.ts`
- [World](https://github.com/excaliburjs/excalibur/blob/main/src/engine/entity-component-system/world.ts): ECS world · Owns entities, component queries, and ordered systems. · `src/engine/entity-component-system/world.ts`
- [System manager](https://github.com/excaliburjs/excalibur/blob/main/src/engine/entity-component-system/system-manager.ts): ECS scheduler · `src/engine/entity-component-system/system-manager.ts`
- [Actions system](https://github.com/excaliburjs/excalibur/blob/main/src/engine/actions/actions-system.ts): behavior pipeline · Advances queued and parallel entity actions. · `src/engine/actions/actions-system.ts`
- [Action queue](https://github.com/excaliburjs/excalibur/blob/main/src/engine/actions/action-queue.ts): action state · `src/engine/actions/action-queue.ts`
- [Physics world](https://github.com/excaliburjs/excalibur/blob/main/src/engine/collision/physics-world.ts): physics ECS · `src/engine/collision/physics-world.ts`
- [Collision system](https://github.com/excaliburjs/excalibur/blob/main/src/engine/collision/collision-system.ts): contact processing · Runs broad/narrow phase and collision events. · `src/engine/collision/collision-system.ts`
- [Realistic solver](https://github.com/excaliburjs/excalibur/blob/main/src/engine/collision/solver/realistic-solver.ts): collision solver · `src/engine/collision/solver/realistic-solver.ts`

### Browser boundaries

- [Input host](https://github.com/excaliburjs/excalibur/blob/main/src/engine/input/input-host.ts): browser input adapter · Normalizes keyboard, pointer, wheel, and gamepad input. · `src/engine/input/input-host.ts`
- [Pointer system](https://github.com/excaliburjs/excalibur/blob/main/src/engine/input/pointer-system.ts): ECS input system · `src/engine/input/pointer-system.ts`
- [Pointer dispatcher](https://github.com/excaliburjs/excalibur/blob/main/src/engine/input/pointer-events-to-object-dispatcher.ts): object event dispatch · `src/engine/input/pointer-events-to-object-dispatcher.ts`
- [Graphics system](https://github.com/excaliburjs/excalibur/blob/main/src/engine/graphics/graphics-system.ts): ECS renderer · Converts entity graphics into draw work. · `src/engine/graphics/graphics-system.ts`
- [Graphics context](https://github.com/excaliburjs/excalibur/blob/main/src/engine/graphics/context/excalibur-graphics-context.ts): rendering abstraction · Isolates graphics primitives from browser backends. · `src/engine/graphics/context/excalibur-graphics-context.ts`
- [WebGL context](https://github.com/excaliburjs/excalibur/blob/main/src/engine/graphics/context/excalibur-graphics-context-webgl.ts): GPU backend · Hosts specialized renderers, shaders, materials, and targets. · `src/engine/graphics/context/excalibur-graphics-context-webgl.ts`
- [Resources](https://github.com/excaliburjs/excalibur/blob/main/src/engine/resources/resource.ts): asset loading · Loads images, fonts, GIFs, and sound. · `src/engine/resources/resource.ts`
- [Sound manager](https://github.com/excaliburjs/excalibur/blob/main/src/engine/resources/sound/sound-manager.ts): Web Audio integration · `src/engine/resources/sound/sound-manager.ts`

### Products & delivery

- [Interactive playground](https://github.com/excaliburjs/excalibur/blob/main/playground/src/main.tsx): React/Vite consumer · Runs editable engine examples. · `playground/src/main.tsx`
- [Documentation site](https://github.com/excaliburjs/excalibur/blob/main/site/docusaurus.config.ts): Docusaurus consumer · `site/docusaurus.config.ts`
- [Sandbox examples](https://github.com/excaliburjs/excalibur/blob/main/sandbox/src/game.ts): example consumer · `sandbox/src/game.ts`

## Connections

- Public engine API → Engine: exports
- Public engine API → Actor: exports
- Engine → Director: coordinates
- Director → Scene: activates
- Engine → Scene: updates active scene
- Scene → World: contains gameplay
- Actor → World: participates in
- World → System manager: runs systems through
- System manager → Actions system: schedules
- Actions system → Action queue: advances
- System manager → Physics world: schedules
- Physics world → Collision system: processes contacts with
- Collision system → Realistic solver: delegates resolution
- Engine → Input host: receives browser input
- Input host → Pointer system: normalizes input for
- Pointer system → Pointer dispatcher: dispatches pointer events
- Pointer dispatcher → Scene: targets objects in
- System manager → Graphics system: schedules
- Graphics system → Graphics context: submits draw work
- Graphics context → WebGL context: implemented by
- Engine → Resources: loads assets
- Resources → Sound manager: loads sound through
- Plugins → Engine: extends
- Interactive playground → Public engine API: consumes
- Documentation site → Public engine API: documents
- Sandbox examples → Public engine API: uses
