Data directory

The 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 ApplicationData function.

In Castle Game Engine >= 6.5 you can also use a special URL protocol castle-data:/xxx. Loading from castle-data:/images/my_image.png is equivalent to loading from ApplicationData('images/my_image.png').

Advantages:

  1. This directory is automatically correctly packaged by the CGE build tool and upcoming editor. E.g. it will be correctly added to the Android apk file.

  2. It is detected in a smart way. E.g. it allows to place your data files in a system-wide location on Unix.

  3. It can be customized using the ApplicationDataOverride global variable.

Note that you do not have to place your files inside the data subdirectory, or use the ApplicationData function or castle-data:/xxx URLs, 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. However, using 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 data subdirectory:

  • Game 3D and 2D models, loaded e.g. by TCastleScene.Load(ApplicationData('my_model.x3d')). See loading 3D models.

  • 2D images, loaded e.g. by TGLImage.Create(ApplicationData('my_image.png')). See loading images.

  • Sounds, loaded e.g. by 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 Download(ApplicationData('my_binary_file')) or TTextReader.Create(ApplicationData('my_text_file.txt')). See loading from URLs and the CastleDownload unit.