CASTLE-ENGINE

NAME

castle-engine - build and package Castle Game Engine programs

DESCRIPTION

castle-engine: Build and package Castle Game Engine programs.

Call with the current directory set to your project, like this:

castle-engine [OPTIONS]... COMMAND

Possible commands:

create-manifest

Creates simple CastleEngineManifest.xml with guessed values.

compile

Compile project. By default compiles for the current OS / current CPU (linux / x86_64). You can use --os / --cpu options to compile to some other OS / CPU. You can use --target to compile for a collection of OS / CPU combination (like "iOS" or "Android").

package

Package the application into the best archive format for given operating system (OS) / processor (CPU) / target. The OS, CPU and "target" can be changed just like at "compile".

install

Install the application created by previous "package" call. Useful when OS is "android", it installs the apk package created by previous "package" call for Android. Useful for quick testing of your app on a device connected through USB.

run

Run the application. On some platforms, it requires installing the application first (e.g. on Android, where we install and run on a device connected through USB). So run the "install" command before. On other platforms (e.g. standalone Windows, Linux, macOS...), it simply runs the last compiled application. So just "compile" the application first.

package-source

Package the source code of the application.

clean

Clean leftover files from compilation and packaging. Does not remove final packaging output.

simple-compile

Compile the Object Pascal file (unit/program/library) given as a parameter. This does not handle the 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. Use this instead of "compile" only if there’s some good reason you don’t want to use CastleEngineManifest.xml to your project.

auto-generate-textures

Create GPU-compressed versions of textures, for the textures mentioned in <auto_compressed_textures> inside the file data/material_properties.xml.

auto-generate-clean

Clear "auto_compressed" subdirectories, that should contain only the output created by "auto-generate-textures" target.

generate-program

Generate files to edit and run this project in Lazarus: lpr, lpi, castleautogenerated unit. Depends on game_units being defined in the CastleEngineManifest.xml.

editor

Run Castle Game Engine Editor within this project, with possible project-specific components.

editor-rebuild-if-needed

Internal. 1st part of "editor" command.

editor-run [--wait-for-process-exit PROCESS-ID]

Internal. 2nd part of "editor" command.

output

Output some project information (from the manifest). Next parameter determines the information:

version version-code

Available options are:

-h / --help

Print this help message and exit.

-v / --version

Print the version number and exit.

-V / --verbose

Verbose mode, output contains e.g. list of packaged files.

--mode=debug|release

Compilation mode, used by "compile" and "package" commands. Also packaging mode on some platforms (right now, Android). By default "release".

--assume-compiled

Do not automatically do "clean" and "compile" before "package". Instead assume that compiled executable for given OS/CPU/mode is already present in the package directory.

--fast

Do not "clean" before "package". Recompile only what changed. This is faster for development, but cannot guarantee that everything is recompiled in a release mode.

--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 this based on regular FPC version. Or you can set this to a particular version, like "3.0.5". Or you can set this to empty "" to avoid passing any -V<VERSION> (suitable for FPC 3.1.1).

--compiler-option=PARAM

Extra parameter for "fpc" command line. For example --compiler-option=-dUSE_MOUSE will add -dUSE_MOUSE. You can use this parameter multiple times.

--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 CastleEngineManifest.xml file.

--package-format=FORMAT

Use with "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 "package" command. The resulting file/directory name will not contain the version number.

--update-only-code

Use with "package" command. Makes the packaging faster, as you guarantee that only the Pascal code have changed since last packaging (so you did not change e.g. data/ or CastleEngineManifest.xml).

--ios-simulator

Use with "package" command when --target=iOS. Allows to run the project on iOS simulator.

--all

Use with "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 and use given "AlternativeManifest.xml" file instead of standard "CastleEngineManifest.xml". Useful if you need to maintain completely different project configurations for any reason.

--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".

--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

Full documentation on https://castle-engine.io/build_tool

castle-engine version 7.0-alpha.2. Using Castle Game Engine ( https://castle-engine.io/ ) version 7.0-alpha.2. Compiled with FPC 3.2.2. Platform: Desktop, OS: Linux, CPU: x86_64 (this exe is using 64-bit architecture).