![]() |
Castle Game Engine supports many platforms: desktop (Windows, Linux, Mac OS X, FreeBSD, Raspberry Pi...), mobile (Android, iOS), Nintendo Switch. The engine hides as much as possible differences between these platforms, exposing a nice cross-platform API.
To create a game that works on all platforms, write a simple
platform-independent main game unit.
This unit is usually called GameInitialize
(in file
gameinitialize.pas
) in our example projects,
although you can of course use any name you like.
See the simplest initial project code in engine examples: castle_game_engine/examples/portable_game_skeleton/ . In particular see the GameInitialize unit inside, showing a cross-platform initialization. You can use it as a start of your projects.
This is a short implementation of a cross-platform "Hello world!" application:
{ Game initialization and logic. } unit GameInitialize; interface implementation uses CastleWindow, CastleControls, CastleLog, CastleUIControls, CastleApplicationProperties, CastleColors; var Window: TCastleWindowBase; Status: TCastleLabel; { One-time initialization of resources. } procedure ApplicationInitialize; begin { For a scalable UI (adjusts to any window size in a smart way), use UIScaling } Window.Container.UIReferenceWidth := 1024; Window.Container.UIReferenceHeight := 768; Window.Container.UIScaling := usEncloseReferenceSize; Status := TCastleLabel.Create(Application); Status.Anchor(vpMiddle); Status.Anchor(hpMiddle); Status.Color := White; Status.Caption := 'Hello world!'; Window.Controls.InsertFront(Status); end; initialization { Set ApplicationName early, as our log uses it. Optionally you could also set ApplicationProperties.Version here. } ApplicationProperties.ApplicationName := 'my_fantastic_game'; { Start logging. Do this as early as possible, to log information and eventual warnings during initialization. } InitializeLog; { Initialize Application.OnInitialize. } Application.OnInitialize := @ApplicationInitialize; { Create and assign Application.MainWindow. } Window := TCastleWindowBase.Create(Application); Application.MainWindow := Window; { You should not need to do *anything* more in the unit "initialization" section. Most of your game initialization should happen inside ApplicationInitialize. In particular, it is not allowed to read files before ApplicationInitialize is called (in case of non-desktop platforms, some necessary things may not be prepared yet). } end.
The initialization
section at the bottom of the GameInitialize
unit should only assign a callback to Application.OnInitialize,
and create and assign Application.MainWindow
.
Most of the actual initialization (loading images, resources, setting up player
and such) should happen in the callback you assigned to Application.OnInitialize.
At that point you know that your program is ready to load and prepare resources.
This GameInitialize
unit can be included by the main program or library
(the .lpr
file for Lazarus, .dpr
file for Delphi).
The build tool
will automatically generate a main program or library code using this unit,
you only need to indicate it by writing game_units="GameInitialize"
in the
CastleEngineManifest.xml.
Usually, all other game units are (directly or indirectly) used by this
initialization unit. Although you can also extend the game_units
attribute
to include more units.
Create a CastleEngineManifest.xml file to compile your project using the build tool. It can be as simple as this:
<?xml version="1.0" encoding="utf-8"?> <project name="my-cool-game" game_units="GameInitialize"> </project>
Compile and run it on your desktop using this on the command-line:
castle-engine compile castle-engine run
If you have installed Android SDK, NDK and FPC cross-compiler for Android then you can also build and run for Android:
castle-engine package --target=android castle-engine install --target=android castle-engine run --target=android
If you have installed FPC cross-compiler for iOS then you can also build for iOS:
castle-engine package --target=iOS # Now open in XCode the project inside # castle-engine-output/ios/xcode_project/ # to compile and run on device or simulator.
This is not necessary, but optionally,
to be able to run and debug the project from Lazarus,
you can create a desktop program file like my_fantastic_game_standalone.lpr
to run your game from Lazarus.
It may be as simple as this:
{$mode objfpc}{$H+} {$apptype GUI} program my_fantastic_game_standalone; uses CastleWindow, GameInitialize; begin Application.MainWindow.OpenAndRun; end.
You can even generate a simple program skeleton (lpr
and lpi
files)
using
castle-engine generate-program
You can customize the desktop xxx_standalone.lpr
file to do some desktop-specific things.
For example initialize window size or fullscreen or read command-line parameters. See examples how to do it:
darkest_before_dawn program file (simple)
or hotel_nuclear (more complicated).
To make our build tool use your customized program file (instead of the auto-generated
one), be sure to set standalone_source
in the CastleEngineManifest.xml
.
Note that you can edit and run the desktop version using Lazarus, to benefit from Lazarus editor, code tools, integrated debugger... Using our build tool does not prevent using Lazarus at all!
lpi
file using
castle-engine generate-program
, you can create it manually:
Simply create in Lazarus a new project using the New -> Project -> Simple Program
option. Or (if you already have the xxx.lpr
file) create
the project using Project -> New Project From File....
castle_base
and castle_window
(from Project -> Project Inspector, you want to Add a New Requirement).
my_fantastic_game_standalone.lpi
.
my_fantastic_game_standalone.lpr
file using the Project -> View Project Source option in Lazarus.
Developing for mobile platforms requires installing some special tools. Everything is explained on these platform-specific pages:
Compiling and packaging cross-platform games is greatly simplified if you use our build tool. For Android and iOS, our build tool nicely hides from you a lot of complexity with creating a platform-specific application.
xxx.apk
file.
To create portable games you have to think about different types of inputs available on mobile platforms vs desktop. The engine gives you various helpers, and abstracts various things (for example, mouse clicks and touches can be handled using the same API, you just don't see multi-touches on desktop). But it's not possible to 100% hide the differences, because some concepts just cannot work — e.g. mouse look cannot work on touch interfaces (since we don't get motion events when you don't press...), keyboard is uncomfortable on touch devices, multi-touch doesn't work on desktops with a single mouse and so on.
To account for this, you can adjust your input handling depending on the
ApplicationProperties.TouchDevice value.
It is automatically initialized to true
on touch devices without keyboard / mouse (like mobile),
and false
elsewhere (like on typical desktops).
For navigation in 3D on mobile, we have a special UI control TCastleTouchNavigation. This allows to easily navigate (examine / walk / fly) in the viewport by dragging on special controls in the corners.
Do not call Window.Open
or Window.Close
or
Application.Run
inside the cross-platform unit like gameinitialize.pas
.
These methods should never be explicitly called on non-desktop platforms.
Even on the desktop platforms, they should only be called from the main program file
(xxx_standalone.lpr
), which may be auto-generated by the build tool.
Do not call Application.Terminate
on platforms
where users don't expect it. Use
ApplicationProperties.ShowUserInterfaceToQuit to show or hide the appropriate user interface,
like a "Quit Game" button.
Mobile applications generally don't have
a buttton to quit — instead, mobile users just switch
to a different application (or desktop) using the standard buttons.
Also, the Application.Terminate
may not be implemented
on some platforms where ShowUserInterfaceToQuit
is false
.
Do not create more than one TCastleWindowBase
instance.
If you want your game to be truly portable to any device —
you have to limit yourself to using only one window.
For normal games that's probably natural anyway.
Note that the engine still supports, and will always support,
multiple-window programs.
See e.g.castle_game_engine/examples/window/multi_window.lpr
example.
However, it only works on normal desktop systems.
It is not possible to do portably (to seamlessly work on mobile and console systems)
since other platforms don't have a concept of "window" that works like on desktops.
Copyright Michalis Kamburelis and other Castle Game Engine developers. We use cookies
for analytics.
Like every other frickin' website on the Internet.
See our privacy policy.
Thank you to Paweł Wojciechowicz from Cat-astrophe Games for various graphics.
This documentation is also open-source and you can even redistribute it on open-source terms.