What to edit, what to ignore, and where saves live.

Source vs generated

A DemiEngine project contains three kinds of data, and knowing which is which tells you what to edit, what to commit, and what to ignore. This page defines the three buckets, maps them onto the project's folders, and explains why game saves deliberately live outside the project tree.

The three buckets

• Source — the documents and files you author: scenes, prefabs, scripts, asset manifests and their sources, game data, and project files. These are the game. You edit them, you review them, you commit them.
• Generated — output produced by tools from source: cook output under generated/, installed package contents under .demi/, and derived geometry such as fracture data. Never hand-edit these; regenerate them instead.
• Writable — data the running game creates for the player: saves and caches. These live in the platform user-data and cache directories and never inside the project.

Folder map

HUD documents conventionally live beside the scene that uses them (scenes/*.hud.json); reusable UI prefab trees live under ui/. A project may also keep HUD files in their own folder, but the examples put them next to scenes.

A generated tree from a new project is described in Your first project; the source document shapes are in Project & file formats.

What to commit and what to ignore

Commit every source file. Reviews then show real design changes — a moved entity, a new asset, a retuned value — as small diffs in readable JSON.

Ignore generated and writable paths in version control. They are reproducible from source or per-player, so committing them would only add noise and merge conflicts. Typical ignore rules cover generated/, .demi/, build output directories, and packaged artifacts such as *.apk, *.aab, and cooked bundles.

Two habits keep the split clean:

• Never hand-edit anything under generated/ or .demi/. Your changes would be overwritten the next time a tool runs. Fix the source and let the tool produce new output.
• Never write gameplay content into generated folders. If a tool seems to want that, the content belongs in scenes/, data/, or assets/ first.

Why saves never live in the project tree

Saves are per-player runtime data, not game content. They are written to the platform user-data directory — on Linux $XDG_DATA_HOME/<game>, falling back to the usual per-user data location — and caches use the matching cache directory. Keeping them out of the project tree matters for three reasons:

• Updates stay safe — installing a new build of the game replaces content, not player progress. Saves that lived beside the content would be overwritten or deleted with it.
• Packaging stays honest — a shipped package must contain the audited game content and nothing else. Player files mixed into the source tree risk being packed into a release or blocked by the content audit.
• Multiple users stay separate — two accounts on one machine must not share or clobber one another's progress. Per-user directories give each player their own slots.

Read and write slots through the save API rather than raw file paths; that is what routes them to the right directory on every platform. See Data & save API. Save document shape and migrations are described with the other formats in Project & file formats.

How cooking creates generated/

Cooking is the step that turns source into runtime-ready content. You ask for a platform, and the engine validates the project and every reachable source, then writes cooked output under generated/cooked/<platform> together with a cook.manifest.json listing every included path and hash:

demi cook --platform linux

• cook — validates and cooks platform content.
• --platform linux — which platform to cook for. Output lands under generated/cooked/linux.

The manifest's hashes make the output checkable and rebuilds incremental: content that did not change is not redone. That is also why you never edit cooked files — they are derived from source by a deterministic step, and the next cook would replace them. The pipeline and hash inputs are described in Cooking.

Release builds reuse the same cooked content. Shipping & builds covers packaging a cooked project into a Linux bundle or an Android APK/AAB, and the Build, cook & test page lists every related command.

Next steps

• Cooking — what cook produces and how rebuilds stay fast.
• Data & save API — reading and writing saves from Lua.
• Assets & stable IDs — what lives in assets/ and how it is named.

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