[Tutorial] Adding crossplatform support to a mod
Erg
Member Posts: 1,756
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.
Credits
@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
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:
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.
Credits
@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%/BG1NPC.tra~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
ACTION_IF GAME_IS ~bgee~ THEN BEGIN
LOAD_TRA ~BG1NPC/TRA/%LANGUAGE%/BGEE_ITEMDESC.tra~ /* Item descriptions for BGEE, i.e. without usability info */
END
Post edited by Erg on
4
Comments
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:
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).