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 installBuild 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 releaseFor the browser player, install emsdk 4.0.11 and build the web preset:
cmake --preset web && cmake --build --preset web --target dreamsy-playerRun 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 8Use 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-mcpGames 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"] } } }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.dpkKits
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
- DREAMSY.MD · the overview and the map of the spec
- docs/format.md · the package format
- docs/engine.md · how the engine works
- docs/harness.md · how games get built
- format/LUAU_API.md · the scripting API