data subdirectory of your Castle Game Engine
project is somewhat special. For typical games (that are distributed with
read-only data files) it is recommended to put all your data inside the
data subdirectory, and load them using the
In Castle Game Engine >= 6.5 you can also use a special URL
castle-data:/xxx. Loading from
castle-data:/images/my_image.png is equivalent to loading from
We advise to use only
castle-data:/xxx for code targeting the new CGE
versions — it is simpler, can be saved to files better (useful when saving CGE editor designs,
X3D models with URLs etc.),
and it works better in some corner-cases (e.g. FindFiles will work
on Android, thanks to an internal information stored in the data on Android).
This directory is automatically correctly packaged by the
CGE build tool
E.g. it will be correctly added to the Android
iOS or Nintendo Switch application.
It is detected in a smart way. E.g. it allows to place your data files in a system-wide location on Unix.
It can be customized using the ApplicationDataOverride global variable.
Note that you do not have to place your files inside the
subdirectory, or use the ApplicationData function
if you don't want to.
You can always load a file from any filename
or URL, so you can open any file on disk etc.
data subdirectory is adviced for typical cross-platform games.
This way the build tool will automatically package your game correctly.
Example things to put in the
Game 3D and 2D models, loaded e.g. by
See loading 3D models.
2D images, loaded e.g. by
MyImage := TGLImage.Create(ApplicationData('my_image.png'))
See loading images.
Sounds, loaded e.g. by
MySoundBuffer := SoundEngine.LoadBuffer(ApplicationData('my_sound.wav'))
See loading sounds.
... and really anything else you plan to load during the game. Your custom files can be loaded using
MyStream := Download(ApplicationData('my_binary_file'))or
MyTextReader := TTextReader.Create(ApplicationData('my_text_file.txt'))
Note that the data contents should be treated as read-only in cross-platform applications. In some cases it may be writeable (e.g. on desktop, when the application files are owned by the current user) but on some platforms it may be read-only (e.g. in case of Android, it resides in a special area which cannot be modified by code).
Copyright Michalis Kamburelis and others. Particular thanks go to Paweł Wojciechowicz from Cat-astrophe Games for various graphics. Even this documentation is open-source and you can redistribute it on open-source terms, in particular CC BY-SA.