docs

Get started

Build the engine, run a game, and make your own with an AI assistant.

Get started

You need Node with pnpm, CMake and a C++20 compiler. Clone the repo and install the JavaScript packages.

git clone https://github.com/apoorvcodes/dreamsy-mono
cd dreamsy-mono
pnpm install

Build the engine

The engine lives in engine/. A release build gives you dreamsy-tool, which validates, packs, runs and playtests games.

cd engine
cmake --preset release && cmake --build --preset release

For the browser player, install emsdk 4.0.11 and build the web preset:

cmake --preset web && cmake --build --preset web --target dreamsy-player

Run a game

Every game is a folder. Run one headless, or get a playtest report with errors, scenes and sounds.

./build/release/dreamsy-tool run ../games/examples/coin-dash --ticks 300
./build/release/dreamsy-tool playtest ../games/showcase/cloud-hopper --seconds 8

Use with Claude Code

Dreamsy ships an MCP server. Your assistant gets the engine as tools: create a game from a kit, edit it, draw sprites, playtest, check and export. No Dreamsy key needed; your assistant does the thinking.

claude mcp add dreamsy -- npx -y dreamsy-mcp

Games are saved in the folder the server starts in; add -e DREAMSY_GAMES_DIR=$HOME/dreamsy-games to keep them in one place. Needs Node 20+; prebuilt for macOS (Apple Silicon and Intel) and Linux (x64 and arm64), and Windows through WSL.

Other clients take the same command in their MCP config:

// Claude Desktop, Cursor, Windsurf, Gemini CLI
{ "mcpServers": { "dreamsy": { "command": "npx", "args": ["-y", "dreamsy-mcp"] } } }

// VS Code (.vscode/mcp.json)
{ "servers": { "dreamsy": { "type": "stdio", "command": "npx", "args": ["-y", "dreamsy-mcp"] } } }
try.txt

Then just ask: “build a cozy frog platformer with dreamsy”.

The game format

A game is a folder you can read and edit by hand, packed into one .dpk file to share.

my-game/
  dreamsy.toml        name, orientation, view, kits
  scenes/*.scene.json entities and their components
  scripts/            Luau: client/ and shared/
  assets/             sprites (svg, png), sounds, music
  data/               content for kits (levels, items, cards)
dreamsy-tool validate my-game
dreamsy-tool pack my-game my-game.dpk

Kits

Kits are tested Luau libraries for whole genres: platformer, rpg, farming, racing and seventeen more. A game opts in with kits = ["platformer"] in dreamsy.toml and require("@kit/platformer") in a script.

Read more