You can place a file named
CastleSettings.xml in your
to influence the look of your application.
From the Pascal code (usually, early in the
Application.OnInitialize callback) load it by calling
The Castle Game Engine Editor will also automatically load this file. This way the editor can show (at design-time) your application in the same way as it will appear to the player.
In the future, the
CastleSettings.xml file should be editable by
the CGE editor GUI, for now you just have to edit it directly.
I expect that this file will also get more features in the future.
The LoadSettings call sets
The default value of
so no scaling is done.
If you don't specify
<ui_scaling> element in
we keep using this default.
However, we advise all new cross-platform projects to use some
This is the best practical way to achieve a consistent look
on various screen sizes and devices.
It is useful even for desktop-only applications (since people have
various monitor resolutions), and it is crucial for mobile applications
(where devices have wildly different resolutions).
The "New Project" templates provided by the CGE editor all set up by default UI scaling to the reference sizes of 1600x900 (the most popular aspect ratio in 2018).
This controls the default font look (font file, font size) for all user-interface controls. Note that each control can customize it (using TCastleUserInterfaceFont.CustomFont, TCastleUserInterfaceFont.FontSize).
<?xml version="1.0" encoding="utf-8"?> <castle_settings> <!-- UI scaling settings. The allowed mode values are - None, - EncloseReferenceSize, - FitReferenceSize, - ExplicitScale, - DpiScale. --> <ui_scaling mode="EncloseReferenceSize" reference_width="1920" reference_height="1080" /> <!-- Default font. Properties size, size_at_load, anti_aliased are optional. Their default values are shown below. The difference between size and size_at_load: - `size` determines the `TCastleFont.Size`, it determines how large the font is on the screen. - `sizes_at_load`, if defined, should be a list of font sizes (integers separated by whitespace). The font sizes should represent a spectrum of sizes you plan to use in your application, e.g. "10 15 20 25". Internally, the font is loaded into a number of textures, one for each size, using TCustomizedFont.Load that creates a number of TTextureFont instances. When rendering using this font, the closest size will be used, and scaled to the requested size, to be rendered exactly at requested size. This gives greatest font quality. - `size_at_load` is the font size used to create an internal texture with letters. By default it is equal to `size`, but it can be set to something larger to improve the quality of the font. This is useful if in your game you will often use this font with other sizes. (E.g. your controls leave `TCastleUserInterfaceFont.CustomFont = nil`, but often use large `TCastleUserInterfaceFont.FontSize` or `TCastleUserInterfaceFont.FontScale`). This is used only when the list `sizes_at_load` is empty. Internally, one TTextureFont instance will be created, for given size. When rendering it will be scaled to the requested size. If you try to render font much smaller or much larger than the loaded size, results may look aliased or blurry. --> <default_font url="castle-data:/MyFontFile.ttf" size="20" sizes_at_load="10 20 30" anti_aliased="true" /> <!-- When loading settings (at LoadSettings call), load and keep in cache some resources. It is most useful to cache large images (used in UI or referenced from TCastleScene) or audio files (referenced from TCastleScene). Thanks to keeping them in cache, any loading of them later in the game will be instant. E.g. instantiating UI by "TUIState.InsertUserInterface" will use the cached images, making starting new UI fast. --> <warmup_cache> <!-- Put in cache an image. Loading this image in UI (like TCastleImageControl, TCastleButton or anything else that uses TCastleImagePersistent cache) will be instant. --> <image_ui url="castle-data:/gui/image.png" /> <!-- Put in cache a scene, along with all resources it references (textures, sounds). Loading this scene in TCastleScene will be much faster, since all resources will be already in cache. --> <scene url="castle-data:/gui/space_map/map_big_1.json" /> <scene url="castle-data:/gui/space_map/map_big_2.json" /> </warmup_cache> </castle_settings>
Copyright Michalis Kamburelis. Thanks go to Paweł Wojciechowicz from Cat-astrophe Games for various graphics. Even this documentation is open-source, you can redistribute it on terms of the GNU General Public License.