Projects

A cTurtle game is a folder with a game.json at its root. game.json names your game, opens its window, lists its scripts and points at its assets. Studio opens a .ctproject file, which is a game.json plus the build targets you export with.

File	What it's for
game.json	Your game's settings: window, simulation rate, scripts, UI and packaging.
.ctproject	game.json plus build targets. The file Studio opens and builds.
bt.module.json	Names a folder of BT code so scripts in other folders can include it.

Paths inside these files are relative to the file's own folder. JSON keys are case-sensitive, and keys a page doesn't list are ignored.

File format versions

Every file you write for cTurtle can say which version of its file format it uses, with an optional format section at the top level:

format:
  version: 1.0.0

or, in a JSON file:

{
  "format": { "version": "1.0.0" }
}

You can leave it out. A file without format is read as the current version, so the only reason to write it is to keep a file meaning the same thing after a future cTurtle changes that format.

The version is MAJOR.MINOR.PATCH. cTurtle reads a file whose major version it knows, as long as the rest is no newer than what it reads. A file written for a newer cTurtle fails to load, and the message says which version the file uses and which ones this cTurtle reads:

assets.yaml uses format version 2.0.0; this cTurtle reads format 1.x up to 1.0.0

Update cTurtle to read it. Quotes around the version don't matter in YAML.

File	Current format version
game.json, .ctproject	1.0.0
Asset registry (assets.yaml)	1.0.0
Scenes	1.0.0
Actors	1.0.0
Models (models.yaml)	1.0.0
Motion clips (.motion)	2.0.0 (1.x still loads)
Rigs (.rig)	1.0.0
Effects (.effect)	1.0.0
Mesh pipeline files loaded by cturtle/mesh_pipeline	1.0.0
studio.json and plugin descriptors	1.0.0
Studio editor settings	1.0.0

The version at the top of game.json is different: it is your game's own version, not a file format version. See game.json.

Files from older versions of cTurtle

Older files said "schema": 1 (game.json, .ctproject, studio.json, plugin descriptors, editor settings) or version: 1 (asset registries, scenes, actors, models, rigs, effects). cTurtle no longer reads these keys, and a file that still has one fails to load with a message such as:

assets.yaml: `version: 1` is no longer used; remove it, or write `format:` with `version: 1.0.0` under it to state the file format version

Delete the line. Motion clips are the exception: a .motion file with version: 1 or version: 2 still loads, as format 1.0.0 or 2.0.0.

Checking your own files

Your game's own data files can follow the same rule. Describe the format your code reads with a FileFormat and check each file with yamlFileFormat, yamlAssetFileFormat or jsonFileFormat:

include "cturtle/yaml";

infallible fn levelFormat() -> FileFormat {
    return FileFormat { file: "level file", reads: ["1.0.0"], contentVersion: false };
}

fn checkLevel(string asset) -> void {
    yamlAssetFileFormat(asset, levelFormat())?;
}

Next: Assets and game data for the images, sounds, scenes and actors your game uses.