Concepts

Core concepts

Commands

Command	What it does
vishnu new <name>	Creates the Acorn starter in a new directory. The name must be kebab-case and must not exist.
vishnu check [dir]	Typechecks the project, compiles the cartridge, and simulates its first three steps.
vishnu test [dir]	Runs the project’s *.test.ts files with node --test on the real kernel.
vishnu build [dir] [--out <dir>]	Builds a static game into <dir>/dist (or --out) and prints the kernel digest.
vishnu dev [dir]	Serves the game locally and rebuilds and reloads it on save.

dir defaults to the current directory. --portal <origin> works with every command that needs the kernel. --help prints usage. --version prints only the version.

Projects

A project is a directory with vishnu.json and a cartridge file. vishnu.json names the cartridge file and pins the kernel by SHA-256:

{
  "format": "vishnu-project-v1",
  "cartridge": "cartridge.ts",
  "kernel": "sha256:..."
}

Leave the kernel pin alone. The cartridge file’s default export is the result of defineCartridge.

Cartridges

• World. meadow({ seed }) is a grassy voxel meadow. Same seed, same world.
• Actors are things in the world. Put starting actors in scene: [place(actor, { at: [x, z] })] and list every actor you spawn later in actors.
• Components are typed data on entities, declared with component.
• Rules are system definitions that run each step. They declare what they read and write.
• Commands are what a player can do, declared with command and a Zod input schema. A command validates input and leaves records for rules to act on.
• Windows are declared with gameWindow and built from block helpers such as block.text, block.stat and block.check.

The starter’s cartridge.ts uses all of these in about 200 lines and is the best place to start reading.

The kernel

vishnu.json pins one kernel build. Vishnu looks for it in $XDG_CACHE_HOME/vishnu/kernels (default ~/.cache/vishnu/kernels), then downloads it from the portal. It checks each file’s size and SHA-256 before caching it, and a mismatch stops the command. An installed package never runs Cargo.

Local development

vishnu dev serves the game on port 5173 (set PORT to change it) and watches the project. Each save rebuilds and reloads the running game. Type errors and cartridge-check failures show in an overlay on the page.

Terminal output

The CLI prints a coral wordmark, progress spinners in an interactive terminal, and plain text when piped. Set NO_COLOR for a plain brand name.