ctgame

ctgame builds your game into something players can run: a single desktop executable, or a web build that runs in a browser. Studio's Build command runs ctgame for you; run it yourself to build from a script or CI.

Common commands

Build a target defined in your project file:

ctgame build --target "Linux Release" MyGame.ctproject

Build the target and copy the result to its deployment folder:

ctgame build --target "Linux Release" --deploy MyGame.ctproject

Build straight from a game manifest, without a project file:

ctgame -o dist/MyGame game.json
ctgame build --wasm -o web/index.html game.json

On success ctgame prints Target NAME ready: PATH (for --target) or built PATH.

Two ways to build

From a build target (recommended). A .ctproject file lists named build targets in build_targets. Each target says which platform to build for, how BT code ships (code_mode), where the output goes, and where --deploy copies it. --target NAME builds one of them. All settings come from the project, so -o, --icon, --wasm and --wasm-build-dir are not allowed with --target. See .ctproject build targets.

From a manifest. Pass a game.json (or a .ctproject) without --target. The game is built with its scripts bundled as source, for the computer you are building on, or for the web with --wasm.

The output folder of a target (the folder that holds output) is replaced on every build, so keep nothing else in it. It must not be your project folder or contain it.

Options

Option	Default	Description
--target NAME	none	Build the named entry of the project's build_targets.
--deploy	off	After building, replace the target's deployment folder with a copy of the output folder. Needs --target.
-o, --output PATH	Manifest name in the current folder (.exe on Windows, .html with --wasm)	Where to write the executable or web page.
--icon FILE	package.icon from the manifest	Executable icon. Windows accepts PNG or ICO; Linux and macOS executables have no embedded icon. For --wasm it must be a PNG.
--wasm	off	Make a web build instead of a desktop executable.
--wasm-build-dir DIR	inside the project's .ctbuild folder	Folder for intermediate web-build files. Needs --wasm.
-h, --help		Print usage.

Native toolchain options

Only needed when the build compiles C code: a game with a native section in its manifest, or code_mode aot_linked. They tell ctgame which CMake, C compiler and native SDK to use. Each has a matching environment variable that is used when the option is not given. See Toolchains.

Option	Environment variable	Default
--native-cmake FILE	CTGAME_NATIVE_CMAKE	The CMake that built the engine
--native-compiler FILE	CTGAME_NATIVE_COMPILER	The C compiler that built the engine
--native-sdk DIR	CTGAME_NATIVE_SDK	The engine build's native-sdk folder
--native-config NAME	CTGAME_NATIVE_CONFIG	The engine's build type, for example Release
--native-generator NAME	CTGAME_NATIVE_GENERATOR	The engine's CMake generator
--native-make-program FILE	CTGAME_NATIVE_MAKE_PROGRAM	The engine's make program

CTGAME_WEB_SDK points ctgame at the web SDK used for --wasm and web targets, when it is not in the web-sdk folder next to ctgame.

What you get

• Desktop: one executable that contains the game's scripts, data and assets. code_mode aot_shared also writes bin/program.dll (Windows) or bin/program.so (Linux) next to it, which must ship with the executable. Players do not need cTurtle installed; the system libraries a player needs are listed in Platforms.
• Web: NAME.html, NAME.js, NAME.wasm and NAME.data. Serve all four from a web server that sends the headers described in Web; use wasm-serve for local testing.

ctgame includes everything the manifest lists: scripts, the scene, the asset registry and every file it references, the UI folder, module dependencies, the icon, and package.copy files. It also converts registered images to a GPU-ready format, so the game loads faster. See Packaging for exactly what ships.

Desktop builds can only target the operating system you build on, and the AOT code modes need x86-64 Windows or Linux. See Deployment modes and Platforms.

If a build fails, the previous executable or output folder is left in place. Build files are kept in a .ctbuild folder in your project; you can delete it at any time to force a clean build.

Errors

Message	What to do
unknown build target	Check the target name and that the project has a build_targets array.
duplicate build target name	Give each target a unique name.
build target platform does not match this host	Build that target on the operating system it names, or set platform to desktop.
target output must be an executable in a separate package directory	Point output into its own folder, not the project folder or a folder that contains it.
deployment must be a separate folder outside the output folder	Set deployment to a folder that does not overlap the output folder or the project.
--target uses project build settings	Remove -o, --icon, --wasm or --wasm-build-dir; set them in the target instead.
--deploy requires --target / --wasm-build-dir requires --wasm	Add the missing option.
unknown code deployment mode	Use one of the code_mode values listed in .ctproject.
WebAssembly supports loose scripts and bytecode; ... / WebAssembly cannot load desktop BT AOT code; ...	Web builds accept only source or bytecode.
loose-script mode requires source inputs in the project	A source target needs bt.sources in the manifest, not a precompiled bt.program or bt.module.
required sidecar 'PATH' does not exist	A file the manifest or asset registry refers to is missing. Fix the path or add the file.
manifest package paths must be safe relative paths	Paths in the manifest must be relative to it and must not use ...
web SDK is missing or incomplete at 'DIR'; ...	Install Studio's web-sdk package next to ctgame, or set CTGAME_WEB_SDK.
wasm icons must be valid PNG images	Use a PNG icon for web builds.
code build failed; see compiler output ...	The C compiler or CMake reported an error above this line. Fix it, or check the native toolchain options.
could not prepare project input staging in 'DIR'	The .ctbuild folder is not writable or belongs to another project. Delete it and build again.
a debuggable build (bt_debug_runtime) needs ctgame-debug-stub in the same folder as ctgame; ...	The ctgame folder is incomplete. Reinstall cTurtle or Studio, or keep ctgame in the folder it came in.
note: executable icons are not embedded on this platform	Information only.