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"
  />
</castle_settings>