Templates, generated files, and what each folder is for.

Your first project

A DemiEngine project is a folder of versioned JSON documents, Lua scripts, and art sources that describe one game. You do not create that folder by hand: the demi new command generates a complete, valid project from a starter template. This page shows how to pick a template, create the example project "My Game" at games/my_game, and understand every folder the command writes.

List the starter templates

A template is a ready-made project skeleton — scenes, scripts, and settings that already run. List what is available:

demi new --list

• demi — the engine CLI you built earlier (see Install & build).
• new --list — prints the template IDs and short descriptions, then exits. Nothing is written to disk.

Each line names a template ID you pass to --template on the next command:

The platformer template is a small 2D game with a player scene and Lua gameplay — a good first choice.

Create the project

Generate "My Game" into games/my_game from the platformer template:

demi new games/my_game --template platformer --name "My Game"

• new games/my_game — destination directory for the new project. It must not already contain a project.
• --template platformer — the template ID from --list.
• --name "My Game" — the human-readable game name stored in demi.project.json.

On success the command prints the created project path and a short summary of the files it wrote. It returns exit code 0.

Preview the exact file list without writing anything:

demi new games/my_game --template platformer --name "My Game" --dry-run

• --dry-run — runs the same planning and validation steps, prints what would be created, and leaves the disk untouched.

What transactional generation means for you

demi new is transactional. The command first writes the whole project into a temporary sibling directory, then validates every generated file, and only then renames that directory to its final name. Two practical consequences:

• Safe — if anything fails part-way, the destination never appears in a half-written state. You either get a complete, valid project or no project at all.
• Never overwrites — if the destination already exists, generation refuses to touch it. Your existing work cannot be replaced by accident.

Because validation runs before the rename, a project that appears on disk is already known to load.

What is in the generated tree

my_game/
├── demi.project.json
├── demi.packages.lock.json
├── scenes/
├── prefabs/
├── hud/
├── scripts/
├── assets/
├── data/
└── .demi/

Each folder has one job. Know what belongs where and editing stays simple:

Alongside those folders the template writes a Lua entry script that starts the game, a deterministic smoke replay used by headless tests, and project-local Lua language stubs under .demi/ so editors can autocomplete the engine API.

For a deeper look at which of these you edit and which are produced by tools, see Source vs generated. Document shapes are covered in Project & file formats.

Open the project in an editor

Two kinds of editing apply, and you will use both:

• Code and JSON — open the games/my_game folder in any text or code editor. Point the editor's Lua language server at the stubs under .demi/lua (or run demi lua-stubs generate to refresh them) so engine calls autocomplete and type-check.
• Visual scene and HUD work — launch the native editor on the project:

  demi editor

• editor — opens the visual workspace for scenes, HUDs, and prefabs.
• The editor reads and writes the same JSON files you see in the text editor.

Both approaches edit the same source documents. Nothing required to ship the game lives only inside the visual editor.

Next steps

• The development loop — run the game, watch files, and iterate.
• Entities & components — what a scene is actually made of.
• Editor — the visual workspace in detail.

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