Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!


New Premium Module: Tyrants of the Moonsea! Read More
Attention, new and old users! Please read the new rules of conduct for the forums, and we hope you enjoy your stay!

[Tutorial] Adding crossplatform support to a mod

ErgErg Member Posts: 1,756
edited April 2016 in General Modding
This discussion is meant to provide advice for modders willing to

1) add crossplatform support to a new mod, to ensure it will work on as many platforms as possible (e.g. BG:EE, Tutu, BGT, etc.)
2) add EE support to an old mod created before the EEs release

This is a very large topic, so instead of trying to write a gigantic post all at once, I think it it will be best to write short posts, each dealing with a different aspect of the process.

If you have any questions, requests, comments and any other kind of feedback on this tutorial, please use this thread.

Tips from other modders are also welcome, so feel free to contribute your own at any time.


@CamDawg, for his tutorial on Converting existing mods to the EE engine

@Wisp, for implementing HANDLE_CHARSETS in WeiDU and for other encoding-related sample code (Edwin Romance is basically a tutorial disguised as a mod).

@Isaya, for pointing out here some inaccuracies in my second post.

Getting started

First, I recommend reading this discussion. It is a bit outdated, but still very useful to understand the main differences between the enhanced engine and the original one.

Also it is always a good idea to take a look at the code in existing crossplatform mods, especially well coded ones like BG1 NPC Project.

Let's start with something simple, i.e.

Handling differences in item descriptions

This is also covered by CamDawg in the discussion linked above, but to further exemplify let's see how this is handled in BG1 NPC Project:

the item descriptions for Tutu and BGT, and other strings common to all the engines, including BG:EE, are stored in the file BG1NPC.tra (actually is bg1npc_tmp.tra, but for simplicity sake let's call it BG1NPC.tra)

the item descriptions for BG:EE (without usability info and with a slightly different style), and other strings that are different in BG:EE, are stored in the file BGEE_ITEMDESC.tra

As explained by CamDawg, only the strings that are different are present in both tra files. For example, some strings like
@78 = ~Great Shield - White Oak~
are present only in BG1NPC.tra, as they are exactly the same on all engines, while some strings like the item descriptions @79 and @80 are present in both tra files to account for engine-dependent differences.

In other words, BG1NPC.tra contains all the strings and BGEE_ITEMDESC.tra contains only the ones that are different in BG:EE.

Te mod loads BG1NPC.tra first on any engine and, if the engine is BG:EE, it will subsequently load BGEE_ITEMDESC.tra. Therefore, if the engine is BG:EE, strings that are missing in BGEE_ITEMDESC.tra, like @78, will stay the same as Tutu/BGT, but strings like @79 and @80 will be replaced by the EE versions.

To do that, we simply have to use the following code in the tp2 file:
LOAD_TRA ~BG1NPC/TRA/%LANGUAGE%/BGEE_ITEMDESC.tra~ /* Item descriptions for BGEE, i.e. without usability info */
Of course we still need to account for differences in the encoding as EEs use utf8 and vanilla/Tutu/BGT other language-dependent encodings, but I will explain how to deal with this another time :)

Post edited by Erg on


  • ErgErg Member Posts: 1,756
    edited April 2016
    Using the correct encoding (part 1)

    First a mod should be trayfied. This not only allows translations in several languages, but it is a required step to ensure that the correct encoding is used for the various platforms.

    Failing to use the correct encoding can cause several problems ranging from garbled text to CTDs (crashes to desktop).

    The tra files must use the encoding shown in the following table:

    Language     Encoding for EE games     Encoding for non-EE games
    Simplified ChineseUTF-8 without BOMCP936
    Traditional ChineseUTF-8 without BOMCP950
    CzechUTF-8 without BOMCP1250
    EnglishUTF-8 without BOMCP1252
    FrenchUTF-8 without BOMCP1252
    GermanUTF-8 without BOMCP1252
    ItalianUTF-8 without BOMCP1252
    JapaneseUTF-8 without BOMCP932
    KoreanUTF-8 without BOMCP949
    PolishUTF-8 without BOMCP1250
    RussianUTF-8 without BOMCP1251
    SpanishUTF-8 without BOMCP1252

    The easiest way to check the encoding of a text file is to use an advanced text editor like Notepad++.

    Please note that in Notepad++ CP1252 is labelled as ANSI, sometimes some encodings may be mistakenly detected as ANSI/CP1252 (e.g. CP1250, see example below), other encodings are labelled in a slightly different way (e.g. Windows-1251 instead of CP1251), but those names are basically equivalent.

    Here are some examples (the encoding is shown at the bottom right of Notepad++ window):

    Italian CP1252

    Italian UTF-8 without BOM

    Polish erroneously detected as ANSI/CP1252 instead of CP1250 (we can tell that the encoding has been erroneously detected because some characters have been replaced by numbers and/or weird symbols)

    The same polish file after manually setting the encoding to Windows-1250 (to manually set the encoding we can use the menu in Notepad++: Encoding > Character sets > Central European > Windows-1250)

    Russian CP1251

    I will show next how to convert from an encoding to another (part 2), how to use the WeiDU command HANDLE_CHARSETS to ensure that the right encoding is used in a mod (part 3), and an alternate method that does not require HANDLE_CHARSETS (part 4).

    Post edited by Erg on
Sign In or Register to comment.