Dusk

A browser engine for worlds worth sharing.
WebGPU rendering · Shared simulation · Visual world building

Get started · Explore the tools · Make a game · Hosting · Documentation

![A white-haired traveler in the warm, furnished Lantern House, rendered by Dusk](docs/evidence/polish-interior.png)

The Lantern House in Darkwind, the reference game built with Dusk. Actual in-engine capture.

Dusk brings a game engine, a world editor and multiplayer hosting into one project. Build a place, give it atmosphere and behavior, then open it in a browser and share it with someone else. The same rendering and content pipeline powers the editor, the player and published worlds. The engine is independently implemented in TypeScript, with its own WebGPU renderer, simulation systems and content compiler. Games supply their own worlds, characters, controls, sound and story through explicit contracts. **Dusk is the engine; Darkwind is its reference game.** ## Get started Use **Node 22.23.4**, pinned in [.node-version](.node-version), and a **WebGPU-capable desktop browser** with hardware acceleration enabled. ```sh git clone https://github.com/jasona/dusk-engine.git cd dusk-engine npm ci npm run dev:darkwind ``` Open **[localhost:5187](http://localhost:5187/)** to enter Darkwind's current house-and-garden preview. Open the same URL in a second browser profile to meet another traveler in the shared room. Walk with **W A S D**, look with the mouse or arrow keys, and press **E** to interact. Speak with the keeper, step into the garden, and take the two-seat cart for a ride together. **Esc** opens the menu; audio is opt-in. [Full controls and game guide →](games/darkwind/README.md) The launcher also prints a **private editor link**, including its access key. Keep that link private. Leave the terminal running, and use **Ctrl+C** to stop. The preview saves to `.data/arrival-art.10`, separately from other local rooms. After updating source, stop the existing process before starting it again. ## What Dusk brings to a world | | Capabilities | | --- | --- | | **Light and atmosphere** | WebGPU rendering, physically based materials, shadows, local lights, skies, particles and adaptive visual quality. | | **Places with life** | Terrain, foliage, water, weather and day/night cycles, with imported GLB models and skeletal animation. | | **Things to do** | Character movement, physics, vehicles, NPC navigation, gameplay resources, combat systems, behavior graphs and 2D tools. | | **People together** | Multiplayer rooms, shared objects, chat, persistent state, portals and travel between hosted places. | | **A place to create** | A browser editor with direct manipulation, asset import, reusable prefabs, collaborative previews, saved undo and playtest publishing. | | **A path to hosting** | Validated content builds, retained engine versions, recovery systems, Docker profiles and optional PostgreSQL-backed services. | These systems have different qualification limits. The [capability matrix](docs/IMPLEMENTATION_STATUS.md) and [release record](docs/RELEASE_CANDIDATE.md) describe their current scope and remaining checks. ## Explore the tools **Dusk World Atelier** is a workspace for shaping and sharing a world. Select and transform objects, import models, arrange materials and light, author interactions, and save your draft. Start a shared development room to try changes together, or publish an invitation to a saved release. ```sh npm run dev:editor ``` Open the private `/editor.html#key=…` link printed in the terminal. The default atelier runs on port **5181**; the Darkwind quick start above includes its own atelier on **5187**. Draft changes are saved separately from published worlds. [World Atelier guide →](docs/BROWSER_EDITOR.md) **Dusk Observatory** is a window into the machinery: run a real rendering scene, inspect browser capabilities, compare main-thread and worker execution, exercise recovery, and export a diagnostic report. ```sh npm run dev:client ``` Open **[localhost:5173/diagnostics.html](http://localhost:5173/diagnostics.html)**. This standalone diagnostics page does not need a multiplayer room. [Rendering and measurement guide →](docs/RENDER_PLACEMENT.md) ![The Dusk Observatory, with its forest-green interface, cream typography and brass accents](docs/evidence/dusk-observatory.png) **Dusk Physics Lab** explores the engine's owned physics implementation in a dedicated browser lab. ```sh npm run dev:physics ``` Open **[localhost:5182/physics.html](http://localhost:5182/physics.html)**. [Owned physics guide →](docs/OWNED_PHYSICS.md) ## Games made with Dusk **Darkwind · The First Light** is the reference game: a cooperative journey through the Lantern House, Rain Garden and Old Sanctuary. Its furnished arrival, keeper, travelers and garden cart bring the engine's systems into a playable world. Darkwind owns its art and story; its implementation lives in [`games/darkwind/`](games/darkwind/README.md). **The Meridian** is an independent cooperative puzzle built through the public SDK. Move the sunstone and moonstone, wake the observatory, and find the star terrace. It runs on the same player, editor and hosting services. ```sh npm run dev:meridian ``` Open **[localhost:5188](http://localhost:5188/)**. The launcher prints a private editor link and uses its own `.data/meridian.1` room. [The Meridian and SDK guide →](docs/GAME_SDK.md#play-and-edit)
More example worlds These examples need PostgreSQL's `initdb` and `pg_ctl` on your PATH; their launchers create separate local databases. | Example | Run | Explore | | --- | --- | --- | | The Lantern Trial | `npm run dev:trial` | Shared resources, abilities and timed interactions. | | The Sentinel Garden | `npm run dev:sentinel` | A shared combat guardian. | | The Watch Garden | `npm run dev:watch` | NPC perception and navigation. | | The Shared Lantern | `npm run dev:extensions` | An installed creator extension. | See the [SDK guide](docs/GAME_SDK.md) for each world's URL, requirements and walkthrough.
## Make a game Start visually in the [World Atelier](docs/BROWSER_EDITOR.md), or work in TypeScript with the [Dusk SDK](packages/sdk/index.ts). The SDK is currently a source API in this repository. The Meridian's [`game.ts`](games/cooperative-puzzle/game.ts) is a complete example that imports only the public entry point. 1. **Define a world.** Create places, objects and interactions with stable identities. 2. **Give it a voice.** An installed presentation adapter supplies the game's title, interface text, controls, traveler and sound. 3. **Build a release.** Compile and validate content into a portable game document. 4. **Share it.** Serve the release through Dusk's player and room services, or publish an invitation from the atelier. Build the included SDK example and inspect the generated API reference: ```sh npm run game:build -- games/cooperative-puzzle/game.ts /tmp/meridian-release.json npm run sdk:reference ``` The build creates a new file and refuses to overwrite an existing release. Published invitations retain their exact engine build, so updating the engine preserves the runtime beneath an existing world. [SDK and presentation adapters →](docs/GAME_SDK.md) · [Authoring and CLI →](docs/AUTHORING.md) · [Engine pinning →](docs/ENGINE_PINNING.md) ## Hosting To try the packaged default reference game locally: ```sh npm run build npm start ``` Open **[localhost:8787](http://localhost:8787/)**. This profile uses `.data/hearth`, separately from the furnished arrival preview. For **Coolify**, the repository includes Docker Compose profiles that build the app, serve HTTP and WebSocket traffic on port **8787**, and declare persistent storage at **`/data`**. Use the [Coolify guide](docs/COOLIFY.md) for setup and the [current release handoff](docs/RELEASE_CANDIDATE.md) for the furnished arrival profile. Public browser access needs **HTTPS** for WebGPU. Configure the exact public origin with `DUSK_ALLOWED_ORIGINS` and a private room passphrase with `DUSK_ROOM_PASSWORD`. Existing `DW_` aliases remain supported; conflicting values fail explicitly. Existing volume names and save identifiers are preserved. [Configuration and compatibility →](docs/DUSK_COMPATIBILITY.md) For PostgreSQL-backed worlds and larger hosting layouts, see [persistent rooms](docs/PERSISTENT_ROOMS.md) and [room routing](docs/ROOM_ROUTING.md). ## Inside the repository | Location | Purpose | | --- | --- | | [`packages/`](packages/) | Engine systems, SDK, renderer, simulation, physics and content contracts. | | [`apps/player/`](apps/player/) | The reusable browser player and game presentation boundary. | | [`apps/editor/`](apps/editor/) | Dusk World Atelier. | | [`apps/probe/`](apps/probe/) | Dusk Observatory and browser capability checks. | | [`services/`](services/) | Multiplayer, persistence, authoring and hosting services. | | [`games/`](games/) | Darkwind, The Meridian and independent example worlds. | | [`tools/`](tools/) | Build, import, authoring, benchmark and development tools. | | [`docs/`](docs/) | Technical guides, capability records and release notes. | | [`llm-docs/`](llm-docs/README.md) | Implementation plans for agent-assisted work. | Engine packages never import games. The reusable player selects game presentation through one trusted installation registry, and the package boundary check enforces those relationships. ## Development and verification ```sh npm run check # Types, package boundaries and generated wire contracts npm test # Native test suite; some profiles require extra services npm run build # Production player, tools, server and retained engine ```
Browser checks, container checks and benchmarks ```sh npx playwright install --with-deps chromium --only-shell npm run test:browser ``` Browser checks build release assets and start an isolated room on port **5174**; they do not use your development room's saved data. `PLAYWRIGHT_EXECUTABLE_PATH` can select an installed Chromium binary. With Docker available, `npm run test:container` checks the production image. `npm run validate`, `npm run bench` and `npm run bench:storage` provide additional content validation and benchmark entry points. Software-rendered checks do not measure hardware frame rates. See the [release record](docs/RELEASE_CANDIDATE.md) for pinned results and outstanding qualification work.
## Project status Dusk is an **early beta**. The fixed [70-feature implementation inventory](docs/FEATURE_COMPLETION.md) is complete, as is Darkwind's five-part visual polish pass. Those milestones are separate from production qualification: broader performance and device checks remain, and the pinned beta's Docker acceptance is still awaiting an external result. The [release record](docs/RELEASE_CANDIDATE.md) is the source for tested commits and known limitations. Darkwind's current shared-play target is **two travelers on desktop WebGPU**. An admission limit is not a measured player capacity; see [room capacity](docs/ROOM_CAPACITY.md) before planning a larger deployment. ## Documentation | If you want to… | Start here | | --- | --- | | Play the reference game | [Darkwind guide](games/darkwind/README.md) | | Build and publish a world | [World Atelier](docs/BROWSER_EDITOR.md) · [Authoring](docs/AUTHORING.md) · [Prefabs](docs/PREFABS.md) | | Create a game in code | [Dusk SDK](docs/GAME_SDK.md) · [Components](docs/COMPONENT_CATALOG.md) | | Bring in models and materials | [GLB import](docs/GLB_IMPORT.md) · [Material graphs](docs/MATERIAL_GRAPHS.md) | | Understand the engine | [Architecture](docs/ENGINE_PLAN.md) · [Core contracts](docs/CORE_CONTRACTS.md) · [Roadmap](docs/IMPLEMENTATION_ROADMAP.md) | | Follow runtime state and recovery | [Simulation time](docs/SIMULATION_TIME.md) · [Checkpoints](docs/SIMULATION_CHECKPOINTS.md) · [Presentation protocol](docs/PRESENTATION_PROTOCOL.md) | | Deploy and operate | [Coolify](docs/COOLIFY.md) · [Persistent rooms](docs/PERSISTENT_ROOMS.md) · [Compatibility](docs/DUSK_COMPATIBILITY.md) | | See what is implemented and qualified | [Capabilities](docs/IMPLEMENTATION_STATUS.md) · [Progress](docs/ENGINE_PROGRESS.md) · [Release record](docs/RELEASE_CANDIDATE.md) | Character source attribution and terms are recorded in [art credits](tools/art/source/README.md). Darkwind's art direction, actual screenshots and motion captures are collected in [Traveler art](docs/TRAVELER_ART.md).