game.json (game manifest)

game.json describes your game: its window, how often the simulation ticks, where its assets and scripts are, and how it is packaged. Put it at the project root. Every relative path in it is relative to the folder that contains game.json.

A .ctproject is the same file with build targets added. Everything on this page applies to it.

Example

{
  "version": "0.3.1",
  "game": { "name": "Asteroids" },
  "window": { "title": "Asteroids", "width": 1280, "height": 720 },
  "simulation": { "fixed_timestep": true, "fixed_hz": 60 },
  "paths": { "asset_registry": "data/assets.yaml" },
  "module": { "name": "asteroids" },
  "bt": {
    "sources": ["bt/main.bt"],
    "entry": "startGame"
  },
  "ui": { "entry": "ui/main.bt" },
  "package": { "icon": "branding/icon.png", "copy": ["meshes", "licenses"] }
}

Every field is optional. An empty object {} is a valid game.json; each missing section falls back to the defaults below.

Top-level fields

Field	Type	Description
version	string	Your game's version, such as "0.3.1".
format	object	The file format version this file uses; see File format versions. Normally left out.
game	object	Game name.
window	object	Window size, title and graphics options.
simulation	object	How often the game logic runs.
paths	object	Where the asset registry and scene are.
assets	object	Images and sounds declared inline (prefer the asset registry).
ui	object	Script that builds the game's UI.
bt	object	Your BT scripts and how they run.
module	object	Your project's BT module name, used by include.
native	object	Your own C code, if any.
package	object	Extra files and the icon for exported builds.
studio_debug_host	object	Lets Studio's debugger attach to your own C host.

Keys cTurtle doesn't know are ignored. A value of the wrong type (for example a string where a number is expected) is usually ignored and the default is used; the cases that stop the game from loading are listed under Errors.

version

Your game's own version, as a semantic version string: MAJOR.MINOR.PATCH, optionally with a pre-release or build suffix ("1.0.0", "0.3.1", "2.0.0-beta.2"). It is optional; leave it out if you don't number your releases.

{
  "version": "1.2.0",
  "game": { "name": "Asteroids" }
}

Studio's Project page shows it next to your game's name, exported games keep it in their packaged manifest, and scripts can read it from GameManifestInfo.gameVersion. A version that isn't a string in this form (a number such as 1, or "1.0") stops the game from loading with "version" is your game's version and must be a semantic version string such as "1.0.0".

This is not the version of the game.json file format; that goes in the optional format section described in File format versions.

game

Field	Type	Default	Description
game.name	string	"CTurtle Game"	Your game's name.

window

Field	Type	Default	Description
window.title	string	"CTurtle Game"	Window title. Separate from game.name.
window.width	integer	800	Starting window width, in points.
window.height	integer	600	Starting window height, in points.
window.fullscreen	boolean	false	Start in fullscreen.
window.resizable	boolean	true	Not implemented: currently has no effect.
window.samples	integer	4	Multisample anti-aliasing (MSAA) sample count. Web builds always use 1.
window.high_dpi	boolean	true	Render at full resolution on high-DPI displays.
window.vsync	boolean	true	Sync presentation to the display refresh. Doesn't change the simulation rate.
window.alpha	boolean	false	Give the window's framebuffer an alpha channel.
window.clipboard	boolean	false	Allow clipboard copy and paste.
window.clipboard_size	integer	8192	Largest clipboard text, in bytes.
window.drag_and_drop	boolean	false	Accept files dropped onto the window.
window.max_dropped_files	integer	4	Most files accepted in one drop.

simulation

Field	Type	Default	Description
simulation.fixed_timestep	boolean	true	true runs game logic at a steady fixed_hz, independent of frame rate. false runs one logic step per rendered frame.
simulation.fixed_hz	number	60	Logic steps per second. Values of 0 or less are ignored.
simulation.max_catch_up_steps	integer	3	After a slow frame, how many extra logic steps may run in one frame to catch up. Higher values keep time accurate after a hitch; lower values avoid a spiral of slow frames.

paths

Field	Type	Default	Description
paths.asset_registry	string	"data/assets.yaml"	Your asset registry. If you set this and the file is missing, the game fails to start. If you leave it out and data/assets.yaml doesn't exist, the game runs without one.
paths.scene	string	—	A scene file to load instead of the registry's scene entry. Useful for a second manifest that runs a test level with the same assets.

The old fields paths.data, paths.images, paths.audio and paths.tuning are rejected. Declare those files in the asset registry instead; see Tuning and other data files.

assets

Images and sounds declared directly in the manifest, loaded at startup and looked up by name like registry assets. New projects should use the asset registry instead.

Field	Type	Default	Description
assets.images[]	array	[]	Each entry needs name and path. Optional premultiply (default false) premultiplies alpha on load; srgb: false marks a data texture such as a normal map.
assets.audio[]	array	[]	Each entry needs name and path.

ui

Field	Type	Default	Description
ui.entry	string	"ui/game/main.bt"	BT script that defines uiMain, which builds your UI. If the file doesn't exist, the game runs without scripted UI.

When you export, the whole folder that contains ui.entry is packaged.

bt

Your game's BT code. You normally list your scripts in bt.sources. When you export, ctgame decides how the code ships (scripts, bytecode or machine code) from the build target's code mode; see Deployment modes.

Field	Type	Default	Description
bt.sources	array of strings	[]	Your scripts. Each entry is a .bt file or a package path. Listing a file loads every .bt file in its folder, plus every package it includes.
bt.program	string	—	A precompiled .ctbt bytecode file to run instead of bt.sources. You can't use both.
bt.entry	string	"gameMain"	Function with no arguments that starts your game. It runs once, after the engine is ready and before the UI and the first frame. It's fine if it doesn't exist.
bt.workers	integer	0	Number of worker threads for BT tasks. 0 means the default (1).
bt.jit	string	"auto"	"auto" turns on the JIT, which compiles your code to machine code while the game runs. "disabled" runs the bytecode interpreter only, which is slower.
bt.debug	object	—	Lets a debugger attach to a running game.
bt.build_target	string	—	Studio only. CMake target Studio builds before Play for a project with native code.
bt.build_manifest	string	—	Studio only. Manifest Studio Play runs after that build, relative to Studio's native build folder.

bt.debug

Starts a debug server so bt-dap or an editor can attach. Studio Play and Debug Play ignore these values and set up debugging themselves.

Field	Type	Default	Description
bt.debug.enabled	boolean	false	Start the debug server.
bt.debug.wait	boolean	true	Pause at startup until a debugger connects.
bt.debug.port	integer	—	Required when enabled. Local TCP port, 1–65535.
bt.debug.token	string	—	Required when enabled. Password the debugger must send.

Debugging isn't available for AOT (machine-code) builds.

Fields written by builds

Exported games carry a rewritten manifest. You don't normally write these yourself:

Field	Description
bt.execution	How compiled code is loaded: "aot-embedded", "aot-linked" or "aot-required".
bt.module	For "aot-required": the machine-code library beside the executable, as { "windows": "bin/program.dll", "linux": "bin/program.so" }.

These can't be combined with bt.sources, bt.program or bt.jit.

module

Names your project's BT module, so your scripts can include each other as include "my-game/ui";. Same fields as bt.module.json; the module root is the folder containing game.json.

Field	Type	Default	Description
module.name	string	—	Required when module is present. Your module's name.
module.dependencies	object	{}	Other BT modules you use, as name → folder (relative to game.json).

native

Use native when your game includes C code. See Native SDK.

Field	Type	Default	Description
native.sources	array of strings	—	Your .c files. Exported games compile them into the executable.
native.include_directories	array of strings	[]	Extra include folders, relative to the project. The project root and engine headers are always included.
native.compile_definitions	array of strings	[]	Preprocessor definitions, such as "FEATURE=1". Your C code is also always compiled with CT_GAME_MODULE=1.
native.link_libraries	object	{}	System libraries to link, per platform: { "linux": ["m"], "windows": ["ws2_32"] }. Keys: windows, linux, macos, webassembly.
native.windows, native.linux, native.macos	string	—	A prebuilt game module (DLL/SO) for running the project directly or in Studio Play.
native.build_target	string	—	Studio only. Default CMake target for Studio's native build.

If native is present, running the game in Studio Play or directly needs the module path for your platform (for example native.linux). Exports only need native.sources: they compile your C code into the executable.

Exported games link your C code into the executable, so you don't ship a DLL or SO.

package

Used only when exporting with ctgame.

Field	Type	Default	Description
package.copy	array of strings	[]	Extra files or folders to ship with the game (for example meshes, licenses). Each must exist.
package.icon	string	—	Executable icon. Windows accepts ICO or PNG. Web builds need a PNG and use it as the page icon. On Windows and Linux a PNG is also the window icon. The --icon option of ctgame overrides it.

Every path ctgame packages (assets, scripts, package.copy, the icon and so on) must be relative to the project and must not use ...

studio_debug_host

For projects that run BT inside their own C program and want Studio's Debug Play to attach to it. Studio edits this under Build Settings > Debug Host.

Field	Type	Default	Description
studio_debug_host.port	integer	0	Port your host listens on. 0 turns this off.
studio_debug_host.token	string	—	Required when port is set. Password for that host.

Debug Play passes these to your host in the environment variables BT_DEBUG_PORT and BT_DEBUG_TOKEN.

Events

There is no events field. You declare each event in BT and register it with eventRegister. A manifest with an events key fails to load.

Errors

Most problems are reported as manifest '<path>' has invalid settings. Check for:

• paths containing data, images, audio or tuning;
• an assets image or sound without name or path;
• both bt.program and bt.sources;
• bt.jit set to something other than "auto" or "disabled";
• bt.debug enabled without both port and token, or a port outside 1–65535;
• an invalid module name, or a module name that points to two different folders;
• native present without a module for the platform you're running on;
• studio_debug_host.port set without a token, or a token without a port.

Message	What to do
could not resolve the declared asset registry	The file named by paths.asset_registry doesn't exist. Fix the path.
"events" is not a manifest field	Remove events; register events in BT.
"schema": 1 is no longer used	Delete the schema line.
"version" is your game's version and must be a semantic version string	Write version as a string such as "1.0.0", or remove it.
uses format version X; this cTurtle reads format …	The file was written for a newer cTurtle; see File format versions.
manifest package paths must be safe relative paths	ctgame found an absolute path or .. in a path it needs to package. Move the file inside the project.

See also

• .ctproject: build targets
• Asset registry, Scene
• ctgame, Deployment modes