Packaging
What goes into a build, what comes out, and what to give players.
What comes out
| Build | Output | Give players |
|---|---|---|
| Desktop, most code forms | One executable, for example MyGame.exe | The executable |
| Desktop, Shared AOT | The executable and bin/program.dll (Windows) or bin/program.so (Linux) | The whole output folder, keeping bin/ next to the executable |
| Web | NAME.html, NAME.js, NAME.wasm, NAME.data | Upload all four to your web server (Web) |
The executable contains your scripts (or compiled code), data, images, sounds and everything else the game needs. Players don't install cTurtle. What their computer needs is in Platforms.
To distribute a desktop game, zip the executable (or the output folder for Shared AOT), or wrap it in an installer or store package of your choice.
File collection
ctgame includes what your game.json and
asset registry point to:
| Included | From |
|---|---|
| Your scripts | bt.sources (Source code form only; other forms ship compiled code) |
| Your UI | The folder containing ui.entry (Source code form only) |
| BT modules you depend on | module.dependencies (Source code form only) |
| Scene | paths.scene |
| Asset registry and every file it lists | paths.asset_registry (default data/assets.yaml): images, sounds, fonts, actors, named files |
Images and sounds listed in game.json | assets.images, assets.audio |
| Anything else | package.copy: extra files or whole folders, for example meshes or shaders |
| Icon | package.icon |
Anything your game opens that isn't listed above is not included. If the
game loads a file by path at run time, or a script includes a file outside
the folders above, add the file or its folder to package.copy.
All paths must be relative to game.json and stay inside the project: no
absolute paths and no ... Otherwise the build fails with
manifest package paths must be safe relative paths. A listed file that
doesn't exist also fails the build.
Files cTurtle adds
Every build also includes cTurtle's default window icon (logo-small.png) and
default UI fonts. Builds that ship script source also include cTurtle's UI
library. If your project has a file at the same path, yours is used and the
build prints note: project file 'PATH' replaces the engine default.
Images
Images in the asset registry and in assets.images are converted to a
GPU-ready format (.png.ktx2) during the build, so the game loads them faster.
Mipmaps are generated at that time, following the image's settings in the
asset registry. The original PNGs ship too.
Converted images are cached in your project's .ctbuild folder, so only
changed images are converted again.
| Message | What to do |
|---|---|
required sidecar '<path>' does not exist | A file listed in the registry or manifest is missing. Fix the path or add the file. |
texture cook: could not decode <path> | The file isn't a valid PNG. Re-export it. |
| An error about mipmap settings | The image's mipmap_filter, srgb or premultiply settings conflict. See asset registry. |
Icons and names
| What | Where it comes from |
|---|---|
| Windows executable icon | package.icon (PNG or ICO), else cTurtle's logo. PNGs larger than 256×256 are scaled down. |
| Linux executable icon | None; Linux executables don't carry icons. |
| Game window icon | package.icon if it is a PNG, else cTurtle's logo. |
| Web page icon | package.icon, which must be a PNG. |
| Window title | window.title in game.json. |
A package.icon that doesn't exist fails the build.
The output folder
- On a desktop build, the target's output folder is emptied and replaced with the new build. Keep nothing else in it.
- On a web build, the four files are overwritten and other files in the folder are kept.
- If a build fails, the previous output is left untouched.
- The output folder can't be your project folder or a folder that contains it.
- Build & Deploy (
--deploy) then replaces the deploy folder's contents with a copy of the output folder. The deploy folder must be separate from the output folder. - On Windows, close the game before rebuilding it; a running executable can't be replaced.
Shipped manifest
The game.json inside your build keeps only what the game reads at run time.
Build-only settings are removed: build_targets, package, the C build
settings in native, and bt.debug (kept only for
debuggable builds).
The .ctbuild folder
Builds keep their working files in a .ctbuild folder next to your project
file. Nothing in it ships. Add it to .gitignore. You can delete it at any
time; the next build is then slower because it starts from scratch. Its image
cache is never trimmed, so delete the folder now and then to reclaim disk
space.
When the game starts
A desktop game unpacks its files to a new private folder in the system's temporary folder every time it starts, and deletes it on exit. Large games take a little longer to start because of this. If the game crashes, the folder is left behind and can be deleted.
Not provided
| Item | Status |
|---|---|
| Code signing | Not implemented. Sign the executable yourself if you need to. |
| Installers, zip archives, store packages | Not implemented. Use your own tools. |
| Version information in the Windows executable | Not implemented |
| Linux desktop entries | Not implemented |
| Protecting game files | Not implemented. Players can extract the files in your build. Bytecode and AOT forms don't ship readable script source. |
| Building for another operating system | Not implemented. Build Windows games on Windows and Linux games on Linux. |