Skip to content

String Tables (.xml)#

String Tables are XML documents which are used to store many types of text, used throughout the game engine as well as the editing kit. The specific usage of strings can vary depending on the string, but most will follow the same general format.

Currently, these cannot be overridden without replacing the file, and there is no support for other languages besides English - however there are plans to change this in the future.

Default String Tables#

Currently, the game engine makes use of the following string tables:

Table Name Description File Location (relative to engine directory)
config_strings Used to store configuration information strings, such as setting display names and descriptions. ./data/config_strings.xml
editor_strings Used to store strings used primarily within the Editing Kit, such as Guerilla, Sapien, Tool, or Foundry ./data/editor_strings.xml
game_engine_text Used to store strings used primarily within the game engine itself ./data/game_engine_text.xml
shared_strings Used to store strings used across both the engine and one or more of its tools. ./data/shared_strings.xml

String Table File Specification#

Root Node#

<strings lang="en_US">

The root node is named strings, and contains only a single attribute.

Attribute Name Description Expected Data
lang The language of the string table. For english, this would be en_US string

String Entries#

<string id="editor_copyright">Copyright (c) Elaztek Studios 2013-2022</string>

<string id="feedback_info_description">
    Thank you for trying out the Blamite Game Engine! We appreciate you trying out the software and giving us feedback to make Blamite better.\n
    \n
    If you've got any feedback to share with us, do let us know! Any feedback submitted via this form is public, and will be posted on the
    suggestions tracker on our website.\n
    \n
    Please note that if you are reporting a bug, or have a specific suggestion to make, you should instead do that via our website.
</string>

<string id="no_parse_test" noparse="true">THIS STRING IS
NOT PARSED AT ALL</string>

Each string within a string table is stored within a single string node, which by default only requires the id attribute. However, there are additional attributes which can be optionally provided. All possible attributes for a string are listed below. The contents of the node contain the actual string content.

Attribute Name Description Expected Data
id The ID of the string, used within game engine code. string
error_code Only used within the error_strings table. Contains the error code the string is associated with. This will often map directly to the BlamResult enum. int
noparse Whether or not to disable string parsing. Defaults to false if the attribute is not provided. bool
html Whether or not parse the string as HTML. Defaults to false if the attribute is not provided. bool

String Parsing#

By default, strings are parsed in a number of ways to ensure that they display as intended within the engine, while also allowing the string tables to be easy to read. All parsing can be disabled by including the noparse attribute and setting it to true. The parsing operations done to parsed strings are as follows:

  • Both CRLF (\r\n) and LF (\n) line breaks are stripped from the string
  • The string literal of \n is parsed to a LF line break
  • Any adjacent spaces greater than 1 are reduced down to 1 space - for example, the text example text would become example text
  • Leading spaces after a line break are removed
  • The string literal of &nbsp; is converted to a space - this is performed after the removal of extra spaces, and as such, can be used when multiple adjacent spaces are desired
  • Other HTML entities are converted to their literal string representations, as outlined below:
  • &#9; -> \t
  • &quot; -> "
  • &apos; -> '

When creating a string that needs to contain any HTML or XML child nodes, the html attribute MUST be set to true in order for this string to be parsed correctly. If the html attribute is not set, then the start of the first child node will be treated as the end of the string.

Additionally, some of the above parsing will be output differently (ie, \n will not display as a new line - you'd need to use <br> instead).

Using Strings#

Currently, strings can be used only within C++ code, however this will be expanded in the future as the game engine is developed.

C++ Code#

Usage of strings is done using the Strings library. These strings can be accessed using one of several functions and/or macros.

Any string can be accessed with its ID by using BlamStrings::Resources::Strings::LookupString(), or the associated STRING_TEXT() macro. Error strings can be accessed from their error code by using BlamStrings::Resources::Strings::LookupErrorString, or its associated ERROR_TEXT() macro.

If an invalid string ID is specified when looking up a string by ID, then Invalid universal string specified. is returned. If an invalid error code is specified when trying to access a string from an error code, then the fallback string with the ID error_string_lookup_failed is used instead.

Usage#

std::string my_cool_string = STRING_TEXT("my_string_id"); // Accessing a string from its ID

std::string error_string = ERROR_STRING(BlamResult::Error_FileNotFound); // Returns the string for Error_FileNotFound
std::string error_string = ERROR_STRING(-2); // Identical to above, but using the numeric error code directly (generally not recommended)