Font configuration files

Font configurations for Scaleform Studio projects are defined in two files FT2FontLib.json and FontMap.json.

FT2FontLib.json defines the mapping between font name and .ttf file for the FreeType 2 library.

FontMap.json defines higher level font mapping and can be used to define different Localization and/or platform configurations.

Both files are optional. The user can decide to use only FT2FontLib.json, only FontMap.json, or neither and use .tff filenames explicitly.

In the Scaleform Studio Editor, when the user adds text to the project that does not have any fonts in the project folder, the default font configuration files and several OpenSans ttf files will be copied to the project folder.

As an example, let's take a look at the default FT2FontLib.json

{
    "fonts" : [
    {"name" : "Sans",  "style" : "Regular", "file" : "OpenSans-Regular.ttf"},
    {"name" : "Sans",  "style" : "Bold", "file" : "OpenSans-Bold.ttf"},
    {"name" : "Sans",  "style" : "Italic", "file" : "OpenSans-Italic.ttf"},
    {"name" : "Sans",   "style" : "BoldItalic", "file" : "OpenSans-BoldItalic.ttf"}
    ]
}

The file has a mandatory "fonts" section that contains an array of font mapping entries. Each entry defines the link between font name and style and the .ttf file. In this case there is only one font name - "Sans". Valid style values are "Regular", "Bold", "Italic", and "BoldItalic".

The "Style" parameter is optional, if omitted "Regular" is used by default.

Here's an example of the default FontMap.json

{
    "configs": [
    {
        "name": "Default",
        "map": [
        {
            "Normal": {"font": "Sans", "style": "Original", "scaleFactor": "1.0"}
        },
        {
            "Title": {"font": "Sans", "style": "Bold", "scaleFactor": "1.0"}
        }
        ]
    }
    ]
}

The json file has a mandatory "configs" section that describes one or more font configurations. Each configuration may represent a different localization or platform.

Currently, the Scaleform Studio Editor uses the "Default" configuration, and the only way to switch configuration in the runtime is to call C++ VGx::FontMap::SetFromJSON. We may add UI and Lua API for font configuration in the next version of Scaleform Studio.

Each configuration has a name ("Default" in this case) and a set of mappings between the virtual font ("Normal" and "Title" in this example) and the actual FreeType 2 or system fonts (in this case, "Sans").

Please note, that the "style" parameter in FontMap.json is different than "style" in FT2FontLib.json. It is optional and has the default value "Original".

With the default value, the font will obey the style (set by text formatting buttons in the editor, or html tags, like <b>). However you can override the style and set it explicitly to Regular, Bold, Italic, BoldItalic.

In our default FontMap.json, the "Title" font is set to always be Bold. It may be beneficial to use virtual fonts like "Normal" and "Title" even if a project does not require localization or per-platform customization. For example, if the artist decides to use a different font set it will be easier to update FontMap.json instead of modifying each textfield.

You can double-click the FT2FontLib and FontMap JSON files to edit them in the Scripts panel to organize fonts into folder or map to different fonts.