Customize look by CastleSettings.xml

1. Description

You can place a file named CastleSettings.xml in your data directory to influence the look of your application. From the Pascal code (usually, early in the Application.OnInitialize callback) load it by calling Window.Container.LoadSettings('castle-data:/CastleSettings.xml');.

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.

TODO: 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

  • Container.UIScaling, Container.UIReferenceWidth, Container.UIReferenceHeight.

    These settings control user interface scaling. See the UIScaling documentation and manual page about 2D user interface for an explanation what is this.

    The default value of UIScaling is usNone, so no scaling is done. If you don't specify <ui_scaling> element in CastleSettings.xml, we keep using this default.

    However, we advise all new cross-platform projects to use some UIScaling. 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).

  • Container.DefaultFont.

    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).

2. Example

<?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>