Build your first ExoJS project

Start with a TypeScript project, learn the Scene and rendering model, then move into input, audio, effects, debugging, and deployment.

npm create exo-app@latest my-game

Create a project Start the first guide Open the Playground

Recommended learning path

Follow these in order to go from an empty folder to a deployable game.

What is ExoJS?
See what ExoJS is and how its pieces fit together.
Setup
Scaffold a typed project and run the dev server.
Project structure
Find your way around a create-exo-app project.
Open example ↗
Your first scene
Load a texture, draw a sprite, and animate it.
Open example ↗
Scenes & lifecycle
Update state and render each frame.
Open example ↗
Keyboard & actions
Move something in response to key presses.
Open example ↗
Audio basics
Play sound and music with reliable controls.
Open example ↗
Build Orb Dodge
Combine it all into a complete small game.
Open example ↗
Deployment
Build and host the finished project.

Browse by topic

Build games

Scenes, input, collision, and a full game walkthrough.

Create visuals

Graphics, sprites, text, filters, and particles.

Work with audio

Playback, spatial audio, effects, and beat detection.

Load assets

Declare, load, and cache textures, audio, and data.

Build UI

HUDs, dialog systems, pause menus, and typewriter text.

Debug & optimize

Overlays, profiling, and render-pipeline inspection.

Ship your game

Build, troubleshoot, and deploy to production.

Guides, Playground, and API

Guides

Explain concepts and workflows, step by step.

Playground

Run and edit every example live in the browser.

API reference

Documents every class, method, and option.

All chapters

67 chapters across 13 parts.

01Getting Started

What is ExoJS?

A short tour of what ExoJS is, where it fits, how a project is shaped, and how to read this guide.

Setup

Create a typed ExoJS project with create-exo-app, run the dev server, and produce a production build.

Project structure

Find your way around a create-exo-app project: the entry point, scenes, assets, and how main.ts wires an Application to a Scene.

Your first scene

Build a working scene from scratch — load a texture, position a sprite, draw it, and animate it across frames.

Resize, DPR & the canvas

Fit the canvas to the window, render crisply on high-DPI displays, and re-lay-out content when the size changes.

02Runtime

Application

How the application owns canvas, render backend, resources, input, scene management, and the frame loop.

Scenes & lifecycle

How scenes split runtime work, switch with transitions, layer a UI on top, and the order their lifecycle hooks run in.

Writing your own transition

The scene-transition lifecycle contract from the inside: what the director guarantees, what your transition must guarantee, and a complete custom transition built against it.

Scene graph

Parent-child structure, transform inheritance, render order, masks, and how the tree stays composable.

Coordinates and views

World space, canvas space, and how the active view maps between them — plus camera movement, zoom, and split rendering.

UI & widgets

Build HUDs and menus on scene.ui with Panel, Button, Label, and ProgressBar widgets — anchoring, layout, clicks, and keyboard focus.

Serialization & prefabs

Serialize scenes to JSON and back, capture reusable prefabs, persist save slots with a key-value store, and register serializers for your own node types.

03Assets

Loading and resources

The asset pipeline — how the loader registers, fetches, and resolves resources before your scene starts updating.

Compressed textures and device variants

Ship one texture per GPU family and display density, and let the loader pick what the running device can actually use.

Offline-capable asset loading

Warm a persistent cache ahead of time, and keep the application working - and failing honestly - when the network is gone.

Tiled maps

Load Tiled (.tmj) tilemaps as assets through the official @codexo/exojs-tiled extension.

Aseprite sprite sheets

Load Aseprite JSON sprite sheet exports as AsepriteSheet assets through the official @codexo/exojs-aseprite extension.

LDtk levels

Load LDtk (.ldtk) level files and convert each level to a renderable TileMap through the official @codexo/exojs-ldtk extension.

Worlds and level streaming

Model a multi-level world, load and unload levels on demand with their own asset scopes, and turn the objects authored in a map into game objects with MapObjectSpawner.

04Rendering

Graphics

Draw procedural shapes and mesh-based geometry.

Sprites

Render image-based content from textures, sheets, SVG, and video.

Text

Control layout, styling, and visual effects for runtime text.

Animation

Animate transforms and values with tweens and frame updates.

Render targets

Render into intermediate textures and reuse those outputs in scene composition.

Pixel snapping

Keep sprites, panels, and tilemaps crisp by snapping rendered output to the device-pixel grid — render-only, camera- and DPR-aware.

Immediate-mode rendering

Draw procedural geometry without a scene node using drawGeometry, and instance thousands of like items as a single draw call with RenderBatch.

Declare a large, mostly-static subtree as a RetainedContainer so it replays as O(batches) and moves as a single GPU-matrix update — and learn the group-local space, invalidation, and lifecycle rules the tier trades for that speed.

Infinite maps

Leave width and height off a TileLayer and let a ChunkStreamer keep only the chunks near the camera resident — procedurally sampled on the main thread, off-thread in a Worker, or re-sliced from a Tiled infinite map.

05Effects

Filters

Stack shader and color effects to control final image style.

Particles

Spawn and tune particle systems for environmental and reactive effects.

Lighting

Light a 2D scene with lights that are scene nodes, normals nobody authored, and shadows read out of the world you already described.

Post-processing

Build multi-pass render flows for bloom, trails, and mirror effects.

Custom mesh shaders

Attach a custom GLSL or WGSL shader to a Mesh through a MeshMaterial for backend-portable visual effects.

06Input

Keyboard & actions

Capture keys, support configurable bindings, and map multiple devices to the same intent-driven actions.

Mouse and pointer

Work with pointer events across mouse and touch-compatible devices.

Gamepad

Read controller input and support multiple connected gamepads.

Chords & sequences

Define simultaneous shortcuts and ordered command patterns on top of the frame-accurate action journal.

07Audio

Audio basics

Play sounds and music with reliable runtime controls.

Spatial audio

Place listener and sources in space for directional sound behavior.

Audio effects

Shape sound with filters and bus-level processing.

Beat detection

Drive visuals from beat and frequency information.

Audio-reactive visualization

Bridge audio analysis and beat-detection state into the render pipeline via DataTexture and BeatDetector polling.

08Physics

Physics basics

Add 2D rigid-body physics with the @codexo/exojs-physics library: build a PhysicsWorld, drop bodies onto colliders, and step it from Scene.fixedUpdate.

Joints, sleeping & CCD

Connect physics bodies with distance, revolute, weld, prismatic, wheel and mouse joints, let resting bodies sleep to save CPU, and stop fast projectiles tunnelling with continuous collision.

09Pathfinding

Grid pathfinding

Route agents over a weighted grid with @codexo/exojs-pathfinding: build a GridSpace from your own map data, read a PathResult, and shape the route with costs, diagonals, clearance and smoothing.

Waypoint graphs

Model traversal a grid cannot express — jumps, falls, ladders, teleports — with WaypointGraph, and implement NavigationSpace for a world of your own.

10Recipes

HUD overlay

Compose gameplay and UI layers without coupling scene logic.

Camera follow & parallax

Create depth and motion parallax from camera and pointer movement.

Pause menu

Pause scene updates while keeping clear visual context for players.

Split screen

Render multiple viewpoints in a shared scene timeline.

Audio reactive scene

Map audio analysis to movement, particles, and camera response.

Game feel

Add feedback cues that make interaction feel responsive.

UI patterns

Build reusable dialog and text-flow UI behavior in-scene.

Cinematics

Coordinate timing, camera, and audio for scripted scene beats.

Collision detection

Validate collision flow and response with interactive shapes.

Build Orb Dodge

Build a complete small game from scratch: player movement, spawning orbs, collision, scoring, a HUD, and a game-over screen — all without external assets.

11Debugging & Performance

Debugging & inspection

Inspect scene state and runtime behavior with overlay layers, and trace filter chains and render passes with the in-engine inspector.

Performance

Measure scene limits with focused stress examples.

Backend comparison

Compare backend behavior and decide what to ship.

Custom renderers

Extend rendering with custom passes and backend-specific logic.

Authoring extensions

Package custom renderers, asset handlers, and node serializers as a distributable ExoJS extension — the descriptor model, per-application selection, and the package policy the official extensions follow.

The renderer SDK contract

What the engine promises a renderer, and what a renderer must promise back, at each seam of the render path.

12Integrations

React integration

Mount an ExoJS Application inside a React tree and drive scenes declaratively with the @codexo/exojs-react bindings.