How excaliburjs/excalibur works
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: engine.ts Engine · index.ts Public engine API · system-manager.ts System manager · scene.ts Scene
Components 24
Core runtime
- Public engine API · Primary npm-facing engine exports.
src/engine/index.ts - Engine · Coordinates browser frames, lifecycle, scenes, and rendering.
src/engine/engine.ts - Scene
src/engine/scene.ts - Director · Manages scene changes, loading, and transitions.
src/engine/director/director.ts - Plugins · Adds engine capabilities explicitly.
src/engine/plugin.ts
Gameplay systems
- Actor
src/engine/actor.ts - World · Owns entities, component queries, and ordered systems.
src/engine/entity-component-system/world.ts - System manager
src/engine/entity-component-system/system-manager.ts - Actions system · Advances queued and parallel entity actions.
src/engine/actions/actions-system.ts - Action queue
src/engine/actions/action-queue.ts - Physics world
src/engine/collision/physics-world.ts - Collision system · Runs broad/narrow phase and collision events.
src/engine/collision/collision-system.ts - Realistic solver
src/engine/collision/solver/realistic-solver.ts
Browser boundaries
- Input host · Normalizes keyboard, pointer, wheel, and gamepad input.
src/engine/input/input-host.ts - Pointer system
src/engine/input/pointer-system.ts - Pointer dispatcher
src/engine/input/pointer-events-to-object-dispatcher.ts - Graphics system · Converts entity graphics into draw work.
src/engine/graphics/graphics-system.ts - Graphics context · Isolates graphics primitives from browser backends.
src/engine/graphics/context/excalibur-graphics-context.ts - WebGL context · Hosts specialized renderers, shaders, materials, and targets.
src/engine/graphics/context/excalibur-graphics-context-webgl.ts - Resources · Loads images, fonts, GIFs, and sound.
src/engine/resources/resource.ts - Sound manager
src/engine/resources/sound/sound-manager.ts
Products & delivery
- Interactive playground · Runs editable engine examples.
playground/src/main.tsx - Documentation site
site/docusaurus.config.ts - Sandbox examples
sandbox/src/game.ts
Connections 26
- 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