Dusk overview

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

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

_{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, and a WebGPU-capable desktop browser with hardware acceleration enabled.

git clone https://github.com/jasona/dusk-engine.git
cd dusk-engine
npm ci
npm run dev:darkwind

Open 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 →

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

These systems have different qualification limits. The capability matrix and release record 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.

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 →

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.

npm run dev:client

Open localhost:5173/diagnostics.html. This standalone diagnostics page does not need a multiplayer room. Rendering and measurement guide →

Dusk Physics Lab explores the engine's owned physics implementation in a dedicated browser lab.

npm run dev:physics

Open localhost:5182/physics.html. Owned physics guide →

#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/.

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.

npm run dev:meridian

Open localhost:5188. The launcher prints a private editor link and uses its own .data/meridian.1 room. The Meridian and SDK guide →

#Make a game

Start visually in the World Atelier, or work in TypeScript with the Dusk SDK. The SDK is currently a source API in this repository. The Meridian's 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:

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 → · Authoring and CLI → · Engine pinning →

#Hosting

To try the packaged default reference game locally:

npm run build
npm start

Open 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 for setup and the current release handoff 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 →

For PostgreSQL-backed worlds and larger hosting layouts, see persistent rooms and room routing.

#Inside the repository

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

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

npx playwright install --with-deps chromium --only-shell
npm run test:browser

#Project status

Dusk is an early beta. The fixed 70-feature implementation inventory 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 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 before planning a larger deployment.

#Documentation

Character source attribution and terms are recorded in art credits. Darkwind's art direction, actual screenshots and motion captures are collected in Traveler art.