demi dev, watch mode, hot reload, and smoke tests.

The development loop

Day-to-day work in DemiEngine is a short cycle: edit a file, see the change running, fix what broke. The CLI supports that cycle with environment checks (demi doctor), a watch-and-run command (demi dev), and two test levels for when you want proof rather than a look. This page walks each piece using the example project "My Game" at games/my_game.

Check the environment with demi doctor

Before running anything, ask the engine whether this machine can. demi doctor inspects your environment and the project and reports what is ready and what is missing:

demi doctor

doctor — runs environment and project checks and prints a diagnostic report.

The report covers toolchain and runtime requirements for the current platform, project readability, and anything the project needs at startup. Diagnostics use stable codes and the same text format as validation, so they are easy to grep in scripts.

Android targets need more on the host machine. Ask for that platform explicitly:

demi doctor \
  --platform android --format json

--platform android — additionally checks the Android toolchain: Java, the Android SDK, and the NDK, including where they were discovered.
--format json — emits the same report as JSON instead of text, for editors and continuous integration.

Doctor returns 0 when the environment is usable and a non-zero exit code when a blocking problem was found. Read the report's codes to learn exactly what to install.

Run the loop with demi dev

demi dev is the command you leave open while working. Step by step it:

Finds the nearest demi.project.json from the current directory upward.
Runs the same environment and project checks as doctor and prints the result.
Starts the game runtime with watch mode enabled.

cd games/my_game
demi dev

cd games/my_game — run every command from inside the project.
dev — starts checks, then the game, then watches project files for changes.

From outside the project tree pass the path explicitly: demi dev --project <path>.

On an attached Android device the same watch flow is:

demi run android \
  --serial <device> --watch

run android — builds, installs, and launches on the device; a current APK is reused when inputs are unchanged.
--serial <device> — which connected device to target.
--watch — enables cooked-source hot reload to the device as you edit.

What hot reload covers

Hot reload means applying your edits to the running game without restarting it. Watch mode covers:

Lua scripts under scripts/
Scene documents under scenes/
HUD documents under hud/
Game data under data/
Asset sources and manifests under assets/

Changes are prepared in the background and swapped in at frame boundaries, so the game never applies a half-finished edit mid-frame. Build output, save files, .git, and generated content are not watched — they are not authored source, so editing them has no effect on the live world (see Source vs generated).

When an edit is invalid — a JSON syntax error, an unknown component, a broken reference — the reload is rejected. Diagnostics print to the console in the usual format, and the last good world keeps running. Fix the file, save again, and the corrected version loads. You never lose the running game because of a typo.

Headless smoke versus desktop E2E

Two test levels sit next to demi dev. Use the cheap one constantly and the thorough one before you trust a change.

Headless smoke

DEMI_HEADLESS=1 demi test

DEMI_HEADLESS=1 — environment variable that runs without opening a window. Suitable for terminals and continuous integration.
test — loads the project and runs its smoke checks, including the generated smoke replay, without a display.

Return value 0 means the project loads and the smoke path completed. Exit code 1 means a validation or test failure; 2 is a usage error and 3 an internal error.

Desktop E2E

demi test linux

test linux — runs the project's end-to-end test script through the real desktop runtime, with rendering and input active.

E2E exercises real gameplay behavior — touching HUD nodes, loading scenes, waiting for state — and always prints a final pass/fail summary. Writing those tests is covered in E2E tests.

A typical edit-run-fix cycle

Start demi dev once and leave it running.
Edit a Lua script, scene, or HUD file in your text editor and save.
Watch the game window apply the change at the next frame boundary.
If diagnostics appear, read the first one, fix the file, and save again — the running game was never broken.
When behavior looks right, run the headless smoke test in a second terminal.
Before merging or shipping, run demi test linux and validate the project.

That loop — edit, see, fix, prove — is the whole workflow. Everything else in the CLI is a deeper form of the same steps.

Next steps

Create & develop — full flags for new, doctor, dev, and run.
Testing & debugging — E2E, replay, and profiler workflows.
Lua scripting — what you will be editing most often.