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 |
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 becomeexample text
- Leading spaces after a line break are removed
- The string literal of
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
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)