new, doctor, dev, editor, run — with examples.

Create & develop

Every DemiEngine game starts as a project: a folder of JSON documents, Lua scripts, and assets that the engine can validate, run, and ship. This page explains how to create that folder and how to iterate on it every day, using the sample game "Skyforge" at games/my_game. Commands below run as demi, the engine command line you built from source.

What the demi command is

The demi binary is the engine's control surface. Instead of hunting for GUI menus, you type what you want: create a project, check the machine, run the game, validate a scene, package a build. The same binary also launches the visual editor. That single entry point means scripts, continuous integration, and humans all speak the same language.

demi --help

• --help — prints the command groups and their flags. It works on any command and subcommand, for example demi run --help or demi package install --help.
• No arguments and no project — lists usage and exits with code 2, the usage error code.

Exit codes are stable so shell scripts can branch on them: 0 success, 1 validation or test failure, 2 usage error, 3 internal error. Schema and capability exports are written atomically (a complete file or no change at all), and packaging is transactional (a failed or cancelled build leaves the previous artifact intact).

List starter templates

A template is a ready-made project skeleton: scenes, scripts, and settings that already validate and run. Templates exist so your first minutes are spent playing and editing, not assembling boilerplate.

demi new --list

• new — the project scaffolding command group.
• --list — prints every available template ID and a one-line description of each.

Returns the list on standard output and exits 0. The shipped templates are:

Create a project

demi new writes a new project folder from a template. It is the only supported way to start a project, because it guarantees a layout the engine understands: a demi.project.json root, conventional scene and script paths, and a project that validates before you touch it.

demi new games/my_game \
  --template platformer \
  --name "Skyforge"

• games/my_game — the directory to create. It must not already contain a project.
• --template platformer — which skeleton to copy. Use an ID from new --list.
• --name "Skyforge" — the human-readable game name written into the project file and later into desktop entries and store listings.

Preview the same command without writing anything:

demi new games/my_game \
  --template platformer \
  --name "Skyforge" \
  --dry-run

• --dry-run — prints the file list and settings the command would write, then exits without touching the disk. Returns 0 when the plan is valid.

The real creation is transactional and never overwrites an existing project. If anything fails partway, no half-written folder is left behind. If the destination already has a project, the command refuses with exit code 1 rather than replacing your work.

Check the machine with demi doctor

A project can only run when the host machine has the tools and libraries that target needs. Doctor is an environment check: it inspects the project and the platform and reports what is ready and what is missing, using the same diagnostic codes as validation.

demi doctor

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

Android targets need more host tooling (Java, the Android SDK and NDK). Ask for that platform explicitly and, if you want machine-readable output:

demi doctor \
  --platform android --format json

• --platform android — additionally checks the Android toolchain and reports where each tool was discovered.
• --format json — emits the report as JSON instead of text, for editors and automated pipelines.

Doctor exits 0 when the environment is usable and non-zero when a blocking problem was found. Optional missing features are reported with the code DOCTOR_OPTIONAL_FEATURE_MISSING so you can tell "cannot run" apart from "cannot use one extra feature".

Iterate with demi dev

Development mode is the loop you leave open while working: it checks the environment, starts the game, and watches your source files so edits appear in the running game without a restart. The point is a short cycle between "I typed something" and "I see it".

demi dev

• dev — runs the doctor checks, then launches the game runtime with watch mode enabled.

When a watched file changes, the edit is prepared and swapped in at a frame boundary so the game never applies half a change. When an edit is invalid (bad JSON, unknown component, broken reference), the reload is rejected, diagnostics print, and the last good world keeps running — a typo never kills the session. Fix the file, save again, and the corrected version loads.

Open the visual editor

The editor is a native window where you arrange scenes, HUDs, and prefabs visually instead of only editing JSON. It shares the same loaders, validation, and diagnostics as the command line, so what the editor accepts is exactly what the CLI accepts.

demi editor

• editor — launches the docking workspace for this project.

Panel layout and visibility are per-user state stored under the platform data directory; they never enter the project or a shipped build. Start with Workspace & panels, then Authoring scenes & HUDs.

Run the game with demi run

Run launches the game the way a player would see it: window on screen, input live, rendering on the GPU. It is also the command used for automated smoke runs and replays.

demi run

• run — launches the project's main scene (or the scene the project declares as main_scene).

Bound the run or remove the window as needed:

demi run --max-frames 30

DEMI_HEADLESS=1 demi run --max-frames 3

• --max-frames N — runs exactly N frames and exits. Returns 0 if the run was clean.
• DEMI_HEADLESS=1 — an environment variable that starts the runtime with no visible window. Ideal for quick "does it still boot?" checks and continuous integration.

On desktop you can also force the initial window size and profile the session; those flags are covered in Build, cook & test and Replay & profiler.

Run on an attached phone

Android development reuses the same project. demi run android builds, installs, and launches on a connected physical device; it reuses a current APK when your inputs have not changed.

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

• run android — builds the APK when needed, installs it, and launches it.
• --serial <device> — which connected device to target (the adb serial).
• --watch — enables cooked-source hot reload to the device as you edit.

Packaging details, signing, and capability checks live in Android builds.

Command map for daily work

Next steps: manage content with Assets & packages, prove behavior with Build, cook & test, or see every flag on the CLI reference.

Found an issue or missing topic? The full engine sources and markdown notes live in the DemiEngine repository.