CASTLE-ENGINE(1)

📦
version 7.0~alpha.3 · 5 versions
, in ubuntu resolute, ubuntu stonking

✨ NAME ✨

castle-engine — build and package Castle Game Engine programs 🏰💖

🌸 DESCRIPTION 🌸

okay bestie so castle-engine is literally the build-and-package bestie for your Castle Game Engine programs. it does the whole glow-up pipeline: compiling, packaging, installing, running, the works. periodt.

🎀 how you actually call it

run it with your current directory set to your project, like this:

castle-engine [OPTIONS]... COMMAND

👑 the commands (aka the main characters)

  • create PROJECT-NAME — makes you a brand new project based on one of the existing templates. it creates a subdirectory called PROJECT-NAME inside whatever directory you gave as --project-parent-dir, and by default that's just the current directory. new project, who dis 💅
  • compile — compiles your project. by default it builds for your current OS / current CPU (linux / x86_64). wanna build for a different OS / CPU? hit it with --os / --cpu. or use --target to build for a whole collection of OS / CPU combos (like "iOS" or "Android"), slay.
  • package — packages your app into the best archive format for the given operating system (OS) / processor (CPU) / target. the OS, CPU and "target" can be changed exactly like at compile.
  • install — installs the app that your previous package call made. super useful when the OS is "android" — it installs the apk package that the previous package call created for Android. great for quick testing of your app on a device plugged in through USB 🔌
  • run — runs the app. on some platforms you gotta install it first (e.g. Android, where we install and run on a device over USB), so run the install command before. on other platforms (e.g. standalone Windows, Linux, macOS...) it just runs the last compiled app, so just compile first. easy.
  • package-source — packages up the source code of the app. cute.
  • clean — cleans the leftover files from compilation and packaging. heads up: it does not remove the final packaging output.
  • simple-compile — compiles the Object Pascal file (unit/program/library) you pass as a parameter. this does not handle Castle Game Engine projects defined by CastleEngineManifest.xml files. it merely calls fpc with proper command-line options for units/programs/libraries using our engine. only use this instead of compile if there's some good reason you don't wanna use CastleEngineManifest.xml for your project.
  • auto-generate-textures — creates GPU-compressed versions of textures, for the textures mentioned in <auto_compressed_textures> inside the file data/material_properties.xml. ✨
  • auto-generate-clean — clears the auto_compressed subdirectories, which should only contain the output created by the auto-generate-textures target.
  • generate-program — generates the files you need to edit and run this project in Lazarus: lpr, lpi, castleautogenerated unit. depends on game_units being defined in the CastleEngineManifest.xml.
  • editor — runs Castle Game Engine Editor inside this project, with any project-specific components. main character energy fr.
  • editor-rebuild-if-needed — internal. it's the 1st part of the editor command. 🤫
  • editor-run [--wait-for-process-exit PROCESS-ID] — internal. it's the 2nd part of the editor command.
  • output — spits out some project info (from the manifest). the next parameter decides which info:
executable-name name pascal-name search-paths version version-code
  • output-environment — spits out some environment info (independent of any project). the next parameter decides which info:
fpc-exe fpc-standard-units-path
  • cache — creates a cache to speed up future compilations. future you says thank you 🫶
  • cache-clean — removes the cache directory. bye bye 👋
  • create-manifest — (Deprecated) creates a simple CastleEngineManifest.xml with guessed values.

💖 OPTIONS 💖

  • -h / --help — print this help message and exit.
  • -v / --version — print the version number and exit.
  • -V / --verbose — verbose mode. the output contains e.g. a list of packaged files. nosy mode: ON 🔍
  • --mode=debug|release — compilation mode, used by the compile and package commands. also the packaging mode on some platforms (right now, Android). default is "release".
  • --assume-compiled — do not automatically do clean and compile before package. instead, assume that the compiled executable for the given OS/CPU/mode is already present in the package directory. trust fall 🤝
  • --fast — do not clean before package. recompile only what changed. faster for development, but it cannot guarantee that everything is recompiled in a release mode. ⚠️ speed vs. certainty, bestie.
  • --plugin — compile/package/install a browser NPAPI plugin. DEPRECATED. 💀
  • --fpc-version-iphone-simulator VERSION — when compiling for iPhone Simulator, we pass -V<VERSION> to the fpc command-line. this is necessary if you use the official "FPC for iOS" package (see the "Getting Started - iOS.rtf" inside the "FPC for iOS" dmg for explanation). you can set this to "auto" (this is the default) to auto-detect it based on the regular FPC version. or you can set it to a particular version, like "3.0.5". or you can set it to empty "" to avoid passing any -V<VERSION> (suitable for FPC 3.1.1).
  • --compiler-option=PARAM — extra parameter for the fpc command line. for example --compiler-option=-dUSE_MOUSE will add -dUSE_MOUSE. you can use this parameter multiple times. stack 'em up 🧚
  • --output=DIR — where to place the output executables, packages, and the "castle-engine-output" directory with temporary generated files.
  • --project=DIR — where to search for the project (CastleEngineManifest.xml file). by default we search in the current directory. the argument can either be a directory, or a filename of a CastleEngineManifest.xml file.
  • --package-format=FORMAT — use with the package command to customize the result. available FORMAT values:
    • default (platform specific; on most platforms creates a zip/tar.gz archive; on Android creates APK; on iOS creates Xcode project)
    • zip (pack all files into zip)
    • tar.gz (pack all files into tar.gz)
    • directory (put all files into a new subdirectory)
    • android-apk (only on Android: create APK)
    • android-app-bundle (only on Android: create AAB)
    • ios-archive-ad-hoc (only on iOS: archive using "ad-hoc" method to IPA file)
    • ios-archive-development (only on iOS: archive using "development" method)
    • ios-archive-app-store (only on iOS: distributes the application to the TestFlight and the AppStore)
  • --package-name-no-version — use with the package command. the resulting file/directory name will not contain the version number.
  • --update-only-code — use with the package command. makes the packaging faster, as you guarantee that only the Pascal code has changed since last packaging (so you did not change e.g. data/ or CastleEngineManifest.xml). pinky promise edition 🤙
  • --ios-simulator — use with the package command when --target=iOS. allows to run the project on the iOS simulator.
  • --all — use with the auto-generate-clean command. indicates to clean everything auto-generated. by default we only clean unused files from "auto_generated" directories.
  • --manifest-name=AlternativeManifest.xml — search for and use the given "AlternativeManifest.xml" file instead of the standard "CastleEngineManifest.xml". useful if you need to maintain completely different project configurations for any reason. so valid, lowkey genius.
  • --wait-for-process-exit=PROCESS-ID — internal, useful with "editor-run".
  • --gui-errors — show errors as GUI boxes. on Unix, requires "zenity" installed.
  • --compiler=COMPILER — select compiler: "autodetect", "fpc", "delphi".
  • --guid-from-name — use with the generate-program command. will generate a stable GUID (in Delphi DPROJ) from the project's qualified name.
  • --windows-robust-pipes — only on Windows (ignored on other systems): force using a less performant, but more robust, way to run child processes with "passthrough", like for castle-engine run. useful to run castle-engine run from PowerShell, outside of the CGE editor.
  • --target=<target> — the target system for which we build/package. available <target> values:
    • "custom" (default): build for a single OS and CPU combination, determined by the --os and --cpu options. these options, in turn, by default indicate the current (host) OS/CPU.
    • "ios": build for all the platforms necessary for iOS applications. this includes both 32-bit and 64-bit iOS devices and iPhoneSimulator.
    • "android": build for all the platforms necessary for Android applications. this includes both 32-bit and 64-bit Android devices.
    • "nintendo-switch": build an application for Nintendo Switch. 🎮
  • --os=<os> — set the target operating system for which we build/package. this is ignored if you used --target=<target>, with <target> being something else than "custom". available <os> values:
linux go32v2 win32 os2 freebsd beos netbsd amiga atari solaris qnx
netware openbsd wdosx palmos macosclassic (classic MacOS, that ended with
MacOS 9)
darwin (modern macOS 10.x, caled also Mac OS X) emx watcom
morphos netwlibc win64 wince gba nds embedded symbian haiku
iphonesim aix java android nativent msdos wii aros dragonfly
win16 ios
  • --cpu=<cpu> — set the target processor for which we build/package. this is ignored if you used --target=<target>, with <target> being something else than "custom". available <cpu> values:
i386   m68k powerpc sparc x86_64 arm powerpc64 avr armeb mips mipsel jvm
i8086 aarch64 (64-bit ARM) sparc64

🦋 DEFAULTS 🦋

android.compile_sdk_version = 34 android.min_sdk_version = 21
android.target_sdk_version = 34

📖 full documentation

full documentation lives on https://castle-engine.io/build_tool — go read it, iykyk ✨

🌈 deets

castle-engine version 7.0-alpha.3. using Castle Game Engine ( https://castle-engine.io/ ) version 7.0-alpha.3. compiled with FPC 3.2.2. platform: Desktop, OS: Linux, CPU: x86_64 (code compiled for 64-bit architecture).

and that's the whole page bestie 💖 this was Castle Game Engine, April 2026 — go build something iconic with it, no cap. 🏰👑💅

📦 where this page comes from