CastleEngineManifest.xml examples

Michalis Kamburelis edited this page Mar 27, 2018 · 42 revisions

The CastleEngineManifest.xml file is used by the Build Tool to know how to build and package your games (or any other projects using the Castle Game Engine). It should be present at the top-level directory of your project.

When you create a new project, you can generate a new manifest file by running castle-engine create-manifest. Or just manually create a new CastleEngineManifest.xml file, using the samples on this page. It's a trivial XML file, just edit it using your favorite text editor.

Simplest example

This is the simplest example manifest:

<?xml version="1.0" encoding="utf-8"?>
<project name="my-cool-game" standalone_source="my_cool_game.lpr">
</project>

The standalone_source value must point to an existing source file to compile the project for desktop platforms (Windows, Linux, MacOSX...). An example is below. Alternatively, you can specify a list of game_units (see the documentation of game_units attribute), in which case the standalone_source is not necessary (the build tool can internally auto-generate a suitable program file for compilation).

When compiling, the resulting executable file name is derived from the project name (in this case: my-cool-game). So it's my-cool-game.exe on Windows and just my-cool-game on Unix.

The project name is also used for other things:

  • When packaging the project (by the castle-engine package), the archive names are derived from it. For example, packaging the project for Linux (64-bit architecture, x86_64) will result in my-cool-game-linux-x86_64.tar.gz filename.
  • In some cases we assume that the ApplicationName function (from the standard FPC SysUtils unit) returns the same project name at runtime. It's never strictly necessary, but it is helpful e.g. for Android logging (where we need to filter the logs by project name). Therefore, it's advised to assign in your source code the OnGetApplicationName callback, and make sure it returns the same thing as project name. See the example below, and the FPC documentation about ApplicationName and OnGetApplicationName .

To be on the safe side, the build tool requires that the project name is limited to ASCII letters, numbers, underscores and hyphens. No spaces, no dots, no other special characters are allowed.

For example, place these contents in the my_cool_game.lpr file:

uses SysUtils, CastleWindow;

function MyGetApplicationName: string;
begin
  Result := 'my-cool-game';
end;

var
  Window: TCastleWindow;
begin
  OnGetApplicationName := @MyGetApplicationName;
  Window := TCastleWindow.Create(Application);
  Window.OpenAndRun;
end.

Congratulations, you have created a game! Now you can compile the project by running this on the command-line:

castle-engine compile

Then you can run it by simply executing the file my-cool-game.exe on Windows or ./my-cool-game on Unix. Or you can run this:

castle-engine run

You can also package the project by castle-engine package, package source by castle-engine package-source and do everything else mentioned in the Build Tool documentation! To learn how to write games, follow our Castle Game Engine manual.

Example of a larger manifest file (portable to Android and iOS too)

Sooner or later, you may want to add more information about your project. It is used when packaging your project in various formats. Note that everything has sensible default values anyway.

Example information that can be expressed in the manifest file:

  • icon (various alternative formats possible),
  • version number (on some platforms, the version numbers are not only displayed; they are also used to signal possible upgrades to user; in particular, on Android platform, the version numeric "code" should always be increasing),
  • author,
  • screen orientation (for mobile devices; by default, all orientations are OK, and they can change at runtime),
  • additional Android and iOS services (to integrate 3rd party services into your game, like Google Play Games or Apple Game Center; see Android Project Services Integrated with Castle Game Engine and iOS Services for more information).

Below is a sample project manifest with more information:

<?xml version="1.0" encoding="utf-8"?>
<project name="my-cool-game"
  standalone_source="my_cool_game_standalone.lpr"
  game_units="MyGameMainUnit"
  caption="My Cool Game"
  author="My Cool Game Company"
  qualified_name="org.mycoolcompany.my.cool.game"
  screen_orientation="landscape">
  <version value="1.0" code="1" />
  <icons>
    <icon path="icon.png" />
  </icons>
  <android project_type="integrated">
    <services>
      <service name="vibrate" />
    </services>
  </android>
</project>

Specify the main game units for a cross-platform game

To create a cross-platform game (that easily compiles to standalone, Android, iOS and other targets) you should use the game_units attribute in your manifest file. Like this:

<?xml version="1.0" encoding="utf-8"?>
<project name="my-cool-game" game_units="MainCoolGameUnit">
</project>

The above example is a complete CastleEngineManifest.xml file, that allows to compile your game to any platform.

  • You can specify multiple unit names, separated by commas, like game_units="OneUnit, TheOtherUnit". All the listed units will be automatically compiled into the game. But typically it is enough to specify a single main unit, and this unit can pull the other units by using them by a uses SomeOtherUnit; declaration in the Pascal source code.

    The initialization section of one of your units must create an instance of the class TCastleWindowCustom, and you must set it as Application.MainWindow. See the example code in the examples/portable_game_skeleton/game.pas.

  • The main program (or library) file, suitable for each platform, will be created automatically before every compilation, if you don't set appropriate xxx_source attribute for your platform. So if you don't set android_source / ios_source / standalone_source / plugin_source, but request compilation to a given platform, we will automatically generate a program (or library) file as necessary.

    This is an important attribute to use when making a game portable to both standalone and mobile. It allows you to avoid writing any Android or iOS specific code. And you don't need to maintain the main program / library files. (These are the files typically with .lpr extension for FPC / Lazarus or .dpr for Delphi.)

  • Note: In order to use the Lazarus IDE, to develop and debug your application, it is often useful anyway to create the main program file for the standalone platform. You can even create and maintain it automatically using castle-engine generate-program command, see the documentation.

    In this case you should specify the generated my_cool_game.lpr file in the standalone_source attribute. The other platforms (Android, iOS) can still use an auto-generated library file.

    The standalone program file can be customized to initialize a specific window size or fullscreen mode, to parse command-line options and so on. These are features not available on mobile devices.

  • Note: make sure that the compiler can find the units mentioned in game_units (just like every other unit necessary). For example, you can add these lines to add code/ subdirectory to your unit search path:

    <compiler_options>
      <search_paths>
        <path value="code/" />
      </search_paths>
    </compiler_options>
    

Complete documented example

This section documents the complete manifest file, with every possible attribute documented.

Basic project information

<?xml version="1.0" encoding="utf-8"?>
<project name="my_game"
  caption="My Game Title"
  qualified_name="net.domain.my.my_game"
  executable_name="my_game"
  standalone_source="code/my_game.lpr"
  android_source="code/my_game_android.lpr"
  ios_source="code/my_game_ios.lpr"
  plugin_source="code/my_game_plugin.lpr"
  game_units="MyMainGameUnit, MyOtherGameUnit"
  android_project="android_application/"
  screen_orientation="any"
  fullscreen_immersive="true"
  author="My Name">
...

The <project> attributes:

  • name: Required name of your game. It determines the names of various output files/packages of your game. It should not contain spaces or non-ASCII characters. It's best to also specify it as OnGetApplicationName inside your code.
  • caption: User-visible game title. Optional (by default equal to name). Here you can use spaces, any special characters and so on.
  • qualified_name: Unique identifier of your game for some purposes (right now: for Android application store, like Google Play store). It is optional (by default equal to `"unknown." + "). Convention is to base this on the website address of your project. For example, for games hosted on http://castle-engine.sourceforge.net/castle.php , a sensible qualified name would be "net.sourceforge.castleengine.castle". Note that this is just a convention, the only important fact is to make this string really unique. Note that some special characters (like dash) should be avoided, to make parts of it suitable as Java identifiers. Don't worry, you will get a clear error in case your name is invalid.
  • executable_name: Binary name (without platform-specific extension, like .exe on Windows). Optional, by default equal to just name.
  • standalone_source: Main file for standalone (desktop -- Windows, Linux, MacOSX...) targets. Optional. You need to provide this, or the game_units, to compile for standalone platforms.
  • (Deprecated) android_source, ios_source, plugin_source: Main file for a specified target. Optional. Using these attributes is discouraged: it's much better to specify only game_units, and let the engine auto-generate the appropriate main file for you. You need to understand a little the engine internals to create a valid xxx_source for Android, iOS or web plugin.
  • screen_orientation: Desired screen orientation on devices that support it, e.g. on Android. Allowed values are any (default), landscape, portrait.
  • fullscreen_immersive: Indicates whether you want to have the status bar and navigation buttons hidden on Android and iOS . Allowed values are true (default), false.
  • author: Author and/or company name. Optional. Used where suitable in the metadata information in the final package or binary.
  • game_units: List of game units. To be included in the auto-generated library or program of your application. See the section above for more information.

Version

...
  <version value="1.0.0" code="1" />
...

The <version> element declares program version. It is used when packaging for some formats (Android package, Windows executable information, iOS project). Attributes:

  • value: User-visible version name. Any string representing your version. We advise, but do not require, to use the major.minor.release format for version numbers, with all components being simple integer numbers.
  • code: Optional (by default 1) version number. This must be a positive integer number specifying the version as a simple number that always grows. This may be used by some platforms (like Android) to compare your applications versions to decide when to automatically upgrade.

Icons

...
  <icons>
    <icon path="icon.svg" />
    <icon path="icon.png" />
    <icon path="icon.ico" />
  </icons>
...

You can provide an optional icon of your application, in various formats, by listing them inside <icons> element. Each platform will use the most suitable icon format and size.

For now, Windows will use the .ico version, and Android and iOS will use any version readable by our engine (like .png or .jpg). We take care to use the best icon format in the best possible way, resizing it (with good quality algorithm) if necessary.

Launch images (for now only for iOS)

...
  <launch_images>
    <image path="launch-image-640x1136.png" /> <!-- Will be used on iPhone (Portrait) -->
    <image path="launch-image-1536x2048.png" /> <!-- Will be used on iPad (Portrait) -->
    <image path="launch-image-2048x1536.png" /> <!-- Will be used on iPad (Landscape) -->
  </launch_images>
...

Some platforms enable to show a launch image (aka "splash screen") when the application starts. This is shown before the actual application has a chance to draw anything. To enable you to customize this, we will use the images defined as <launch_images>. As the platform (like iOS) may require a couple of image sizes, with various aspect ratios, we will scan the list of your <launch_images> and choose the one with closest aspect ratio (width / height proportion), and use it (eventually resizing if needed). Only if you don't define any <launch_images>, we will use a default one.

Right now, this is only used for iOS applications. The suggested sizes, and their usage, is shown in the example above. Note that there's no iPhone Landscape launch image (for some reason, Apple doesn't want it).

Note: if you want to adjust the loading image displayed by your application (this feature is used on all platforms), then you're not interested in this setting. Instead, adjust the tiLoading image in the Theme defined by CastleControls units. Adjusting the theme images is documented in the manual.

Android information

...
  <android
    project_type="integrated"
    compile_sdk_version="23"
    build_tools_version="23.0.2"
    min_sdk_version="9"
    target_sdk_version="23"
  >
    <services>
      <service name="google_play_services" />
      <service name="google_play_games">
        <parameter key="app_id" value="XXXX" />
      </service>
    </services>
  </android>
...

The <android> element provides various extra Android-specific information.

  • See Android services for a description of project_type, and what services are available inside the <services> element.

  • compile_sdk_version: The Android SDK platform version used to compile the project. You must have this version installed in the Android SDK. For example, if this is 23 (the current default), then you must install the "SDK Platform" and "Google APIs" components of the "Android 6.0 (API 23)" section in your Android SDK. Note that this does not determine the minimum (or maximum) Android version your application supports. It is optional, the default value is shown above.

  • build_tools_version: The Android SDK build tools version used to compile the project. You must have this (exact) version of the "Android SDK Build-tools" installed (from the "Tools" section of Android SDK).

  • min_sdk_version: The minimum supported Android version. It is a hard limit on where the application is installable, it also limits for which devices it appears in the Google Play store. Default is "9", you can only increase it.

  • target_sdk_version: Which Android version of Android Java APIs you can use. Don't worry about it, unless you use a specific Android service that requires increasing this version. Default is "18", you can only increase it.

    Note that with earlier FPC versions, you cannot increase target_sdk_version above 22. That's due to missing PIC support. See http://lists.freepascal.org/pipermail/fpc-devel/2015-September/035948.html and http://fpc-devel.freepascal.narkive.com/tMJHK2Hw/fpc-app-crash-with-has-text-relocations-android-6-0 . Compiling with -fPIC doesn't help, your app will crash then with java.lang.IllegalArgumentException: Unable to load native library:... This is fixed is latest FPC 3.1.1, that supports -fPIC on Android.

iOS information

...
  <ios 
     team="..." 
     override_qualified_name="com.example.ios.qualified.name"
     override_version_value="1.0"
     uses_non_exempt_encryption="true|false"
  >
    <services>
      <service name="apple_game_center" />
    </services>
  </ios>

...

The <ios> element provides various extra iOS-specific information.

  • team is the identifier of your Apple team, used to sign the application. See how to find my Apple Developer Id. You can also set the Development Team using the XCode GUI before compiling the project.
  • override_qualified_name overrides the qualified name (by default taken from qualified_name) for iOS. This allows you to use different qualified names for Android and iOS applications, in case you need it.

  • override_version_value overrides the version name (by default taken from <version value="..." /> attribute) for iOS. This allows you to use different version name for iOS release than the other platforms (Android, desktop etc.), in case you need it.

  • uses_non_exempt_encryption says whether your application uses an encryption that requires you to do some legal things when it is distributed from U.S. This is important for distributing your application internationally from the Apple AppStore, which qualifies as exporting your application from U.S..

    By default this is true, which is consistent with the default of the Apple iTunes Connect setting. If your application does not use encryption at all (unlikely, in modern times, as even reading stuff through HTTPS qualifies as "using encryption"), or if you fall under some exemptions (e.g. you only use HTTPS), then you can set this to false. This way Apple iTunes Connect will no longer bother you about this.

    Please read the Apple documentation on this issue. Setting this to false is equivalent to using <key>ITSAppUsesNonExemptEncryption</key><false/> in the xxx-Info.plist file in your XCode project.

  • See the iOS Services for information what can you use within the <services> element.

File type associations (Android and iOS)

...
  <associate_document_types>
    <document_type name="VRML Scene" icon="">
      <file_extension extension="wrl" mime="model/vrml" />
      <file_extension extension="wrz" mime="model/vrml" />
    </document_type>
    <document_type name="ZIP Archive">
      <file_extension extension="zip" mime="application/zip" ios_type_identifier="com.pkware.zip-archive" />
    </document_type>
    ...
  </associate_document_types>

...

The <associate_document_types> element allows to tell the operating system to associate the given document types to your application. Each document type can specify several file extensions.

The <document_type> element defines the document type to associate.

  • name: string visible to the user on iOS when user taps the file with this type.

  • icon: icon file shown next to the name. When none supplied, the application icon will be used.

The <file_extension> element specifies the actual file extension to match.

  • extension: file extension string without leading dot.

  • mime: mime type used on iOS.

  • ios_type_identifier: In case you are associating the well known document type on iOS, you have to set this attribute to one of the system-declared uniform type identifiers, see Apple documentation

To make URL opening work on Android, you need to set <android project_type="integrated"> in the manifest, see Android information.

To handle the actual URL to be opened, you have to implement Window.OnDropFiles event in your source code.

Dependencies

...
  <dependencies>
    <!-- read font files like .ttf -->
    <dependency name="Freetype" />
    <!-- read .gz files -->
    <dependency name="Zlib" />
    <!-- read .png files -->
    <dependency name="Png" />
    <!-- play sound -->
    <dependency name="Sound" />
    <!-- read .ogg (OggVorbis) compressed audio files -->
    <dependency name="OggVorbis" />
    <!-- ability to download using https (not only http) -->
    <dependency name="Https" />
  </dependencies>
...

The <dependencies> element allows to explicitly declare dependencies on various libraries. These dependencies are applied on all platforms. On some platforms (for now: Windows, Android, iOS) the necessary libraries are automatically bundled with your binary when packaging.

(Note for Android: It is necessary to use project_type="integrated" to have some of the dependencies applied -- like Sound and OggVorbis.)

Note that it's often not necessary to specify these dependencies. The build tool automatically adds the dependencies when it detects a particular file format in your game data. For example, if you have a file music.ogg, we will automatically add the OggVorbis and Sound dependencies.

Packaging (exclude and include files)

...
  <package>
    <include path="documentation/*" recursive="True" />
    <include path="README.txt" />
    <include path="COPYING.GPL2.txt" />
    <exclude path="*.xcf" />
    <exclude path="data/internal/*" />
  </package>
...

The <package> element allows to fine-tune what files to include in the final package.

By default, the build tool includes the data/ subdirectory. It excludes some files known to be useful only for development, currently: *.xcf (GIMP), *.blend* (Blender), *~ (backup files from various applications).

The <package> element allows to list additional files/directories to include or exclude.

  • <include>: Add given files to the package. The path is actually split (by last /) into a subdirectory (relative to the project directory) and the mask within it (with wildcards * and ?). We include the files matching the mask within the given subdirectory, possibly recursive (if recursive="True").
  • <exclude>: Exclude files whose whole path (relative to project directory) matches given mask. You can use wildcards * and ?, where * matches any number of any characters, including slash (directory separator). For example:
    • Use "*.xcf" to exclude all GIMP xcf files.
    • Use "data/internal/*" to exclude all files inside data/internal/ subdirectory.
    • Use "data/internal/*.xcf" to exclude all GIMP files inside data/internal/ subdirectory.

The order of including and excluding: first we include everything specified, then we remove excluded stuff.

Above are just some examples of including and excluding.

Compiler options and paths

...
  <compiler_options>
    <search_paths>
      <path value="code/subdirectory/"/>
      <path value="code/another_subdirectory/"/>
    </search_paths>
    <custom_options>
      <option>-dMY_CUSTOM_SYMBOL</option>
    </custom_options>
  </compiler_options>
...

The <compiler_options> element contains optional configuration for the compiler (FPC):

  • <search_paths> provide additional source code locations. These are used to search for units and include files by FPC (correspond to -Fi, -Fu options of FPC). By default, all of the source code is assumed to be placed in the same directory as main program file (indicated by standalone_source or other xxx_source attribute, or just in the main project directory if you don't specify the xxx_source attribute for your platform).

  • <custom_options> are custom compiler options, passed directly to the compiler (FPC).

    For example -dMY_CUSTOM_SYMBOL means that the symbol MY_CUSTOM_SYMBOL will be defined (and can be queried in your code using {$ifdef MY_CUSTOM_SYMBOL} ). You can use this also to define some symbols recognized by the engine, e.g. -dCASTLE_PNG_DYNAMIC instructs the engine to use dynamic library to load PNG images (which may be much faster, see castleconf.inc comments ).

    Note that custom option may also be @my-custom-config.cfg in which case FPC reads my-custom-config.cfg file, and you can put more options inside (using features like #IFDEF MSWINDOWS for platform-specific options).

The end

...
</project>

End of the manifest file.