String Tables

From C4 Engine Wiki

String tables are used by the C4 Engine to store human-readable text strings in resources that are external to the engine code and game code. Storing strings separately makes localization easy, and it allows text to be changed without needing to recompile your game.

String Table Files

String table files have the .str file extension, and reside in a subdirectory of the Data directory under the C4 root directory. These files are stored in a binary format and are created by using the string importer tool to import text files (with the .txt file extension) from a subdirectory of the Import directory.

The string importer tool can be run by choosing Tools > Import String Table, or by invoking the istring command from the Command Console.

The names of the .txt and .str files are the same, and by convention are named to match the name of your game DLL.

Here is an example of how to format strings in a text file, that will be imported by the string importer tool:

'type' "String"
{
    'sub1' "Substring"
    'sub2' "Other Substring"
}

In the above example, when the string loading function asks for the string 'type', it will get back a pointer to "String". If the function requests a string using a string ID formed from the pair 'type' and 'sub1' it will get back "Substring". Substrings are useful when the top-level type is a controller fourcc, for example, and the subtypes are various strings used by that controller. Strings may be nested up to four blocks deep.

String Table Usage

The code usually calls StringTable::GetString as follows:

stringTable->GetString(StringID('type', 'sub1'));

This call will search the string table to look up the string based on the type and subtype specified, and return a pointer-to-char to that string constant. Declare your string table in your Game class as follows:

class MyGame : public Application, public Singleton<MyGame>
{
    StringTable    stringTable;
    ...
}
 
MyGame::MyGame() : Singleton<MyGame>(TheGame), stringTable("MyGame"), ...
{
    ...
}

In this case, the constructor of the StringTable loads the string table resource from a file named "MyGame.str" in a subdirectory of the Data directory.