Short introduction to WeiDU and simple mod template
Wisp
Member Posts: 1,102
With the unfortunate proliferation of primitive mods we are currently seeing, I thought it might be helpful to have a simple and straightforward introduction to how to make WeiDU mods. Due to the vast scope of IE modding and WeiDU, this is in no way a comprehensive treatment of what you can do with modern techniques, but it should be serviceable for a fair share of the mods we are seeing posted here. If you then feel like learning more, so much the better.
Short introduction to WeiDU
WeiDU is a mod-distribution tool and mod manager [1] for the Infinity engine. Since shortly after its inception in the earlier half of the last decade, WeiDU is the de facto standard for IE mods (to the point where you had to look under the right rock to find a non-WeiDU mod). Salient features include patching of existing game resources [2], a powerful language for creating (complex) dialogue, automatic backups of game resources for facile mod uninstallations and a scripting system for mod installation and configuration.
You could say that WeiDU has a lot of depth and maybe the WeiDU way (such as it is) can seem opaque and daunting to the novice modder. However, a WeiDU mod need not be complicated. The simplest sort of mod could consist of as little as a file–folder structure and four lines of install script (of which three lines would be largely the same across all mods).
The latest version of WeiDU is normally available from WeiDU.org. It can also be worthwhile to check the forum.
Sample WeiDU mod
A WeiDU mod consists of two things: 1) a mod folder, which houses any files you include in your mod and will house the backups created during mod installation, and 2) a installation script called a TP2 file, conventionally located inside the mod folder. Customarily, the mod is distributed together with a copy of WeiDU itself, but this is not a formal requirement. The copy of WeiDU would be named setup-mod_name.exe, where mod_name is the name of the mod folder.
The mod folder should have a name that is reasonably likely to be unique, since all mod folders exist as sub-folders in the game folder. For example, wisp_item_mod would be a better name for a mod folder than item_mod. [3]
The TP2 file should have the file extension "TP2", have the same name as the mod folder and be located directly inside the mod folder. [4]
Any other files you wish to include should likewise be placed in the mod folder, preferably in sub-folders of their own if the files can be grouped like that.
As a simple example of a WeiDU mod, say I wanted to distribute a few item files for others to enjoy. Maybe I had made some changes, which I felt improved the quality of the game, to these files with my editor of choice. I could call this mod "Wisp's item mod", with a mod folder called wisp_item_mod, containing a TP2 file called wisp_item_mod.tp2 and the sub-folder copy, which would contain my altered item files.
I would write the following TP2 file for this mod (commented for your benefit):
/*
* Note:
*
* Lines starting with double slashes (//) are comments and are completely ignored by WeiDU.
* They are strictly for your convenience (and whoever else reads your TP2 file).
*
* Likewise, text enclosed in matching, reverse pairs of slashes (/) and asterisks (*),
* like this text, is commented, with the difference that this text can span multiple lines.
* These block quotes can not be nested. Starting each line with an asterisk is just
* convention to make the comment look more distinguished.
*
* So-called strings are used to enclose spaces and special characters. They carry some
* significance beyond that, but we need not go into that now. WeiDU has a few notations
* for strings. Pairs of tildes (~) and double typewriter quotes (") are normally used.
* Each can enclose the other, but never itself.
*
*/
/*
* BACKUP declares where WeiDU should put the information it uses to uninstall your mod.
* Conventionally, this is a folder called "backup" located directly inside your mod folder.
* There is no need to create this folder yourself, or take steps to make sure it exists when
* the user tries to install your mod. This is a folder-path declaration, so there are "wrong"
* things to write here, but conventional wisdom applies. Note that WeiDU will automatically
* convert slashes into backslashes and vice versa, as needed. Case is irrelevant (with one
* exception that is only relevant to installing mods on GNU/Linux).
*/
BACKUP ~wisp_item_mod/backup~
/*
* AUTHOR declares what information should be displayed to the user in the event there is some
* error while installing your mod. Normally, it will ask the user to email the mod's debug file
* to whatever AUTHOR declares. This means it should preferably be something useful, like an actual
* email address, or some other way in which you can be reached. This is simple text, so there are
* no limitations on what you can write.
*/
AUTHOR ~Wisp, at some forum~
/*
* BEGIN declares a mod component, which the user can install. A mod can have multiple components, but
* must have at least one. The text is displayed to the user when the mod is installed and is printed
* to the log file. This is likewise simple text, so spaces and special character are completely
* acceptable.
*/
BEGIN ~Wisp's item mod~
/*
* COPY is the substance of this TP2 file. COPY declares that WeiDU should copy a file, or the files in
* a folder to a destination file or destination folder. In this case, every file located in the "copy"
* sub-folder will be copied into the override folder. Should there already be files with the same name
* in the override folder, WeiDU will place them in your backup folder and restore them when the mod
* is uninstalled. This is once again a folder-path (or file-path) declaration, so it needs to be
* written correctly.
*/
COPY ~wisp_item_mod/copy~ ~override~ //Don't forget to delete the existing files, if you make use of this mod template.
This is barely scratching the surface of what WeiDU can do, but perhaps it can serve as a useful starting point. It is certainly preferable to simply handing people a handful of files, for them to manage themselves. For a more hands-on example, the faux-mod itself can be found attached to this post. Poke, probe and prod it to your content. You can use this as a template for any mod which merely places files in the override (or another folder).
Naturally, I will answer any questions you may have about things I left out, did not adequately explain or just took for granted.
Footnotes
1. Yes, it is a mod manager. It may not be graphical, but it will handle your mods for you if you, say, decide to uninstall the second mod of a set of three.
2. Including the TLK file, which is the single resource containing all of the game's text (save a handful of hardcoded exceptions). The TLK file stands out, because without patching you could not use two mods which both added/altered game text.
3. The folder name should preferably not contain spaces and non-alphanumeric characters, though they can sometimes be used without problems. Conventionally, the underscore (among others) carries no special significance and can safely be used. The name does not have to be pretty, just functional.
4. You may occasionally see WeiDU mods that come with a TP2 file prefixed with "setup-" and/or is located outside the mod folder. These are older practices that are unnecessary and not recommended today, respectively.
Comments
I guess one may also install a "top-level" copy of WeiDU. Does the copy local to a given mod take precedence over the top-level one then? In case a particular mod has to rely on a particular version of WeiDU e.g. And where shall we get the last version of WeiDU?You wrote about "installing" and "uninstalling" a mod. What do you exactly mean by that? Where do you put the mod folder in the first place? What exact user action is required to trigger the script to install the mod? Or to uninstall it later?
The latest stable WeiDU is on WeiDU's own website though sometimes beta or WIP builds are released onto their forums. Typically you decide on a file name--in Wisp's example, wisp_item_mod--and then that dictates everything that follows. If you rename a copy of weidu.exe to setup-wisp_item_mod.exe and double-click it, it goes looking for wisp_item_mod.tp2, setup-wisp_item_mod.tp2, wisp_item_mod/wisp_item_mod.tp2, and wisp_item_mod/setup-wisp_item_mod.tp2 (in that order) to execute a mod installation. The mod folder and the setup-wisp_item_mod.exe go into your main game folder. You would install or uninstall by double-clicking setup-wisp_item_mod.exe. Wisp has a beta on the WeiDU forums that I've been using that looks pretty close. I think the only bit left to solve is the non-standard placement of dialog.tlk.
And I created a "mod" based on this - http://forum.baldursgate.com/discussion/10212/a-simple-xp-cap-remover/
I've never done this sort of thing before, so I probably made a mess of it, but please let me know if I'm doing this right.
BTW, I had to create a hard link to dialog.tlk in the game directory (symbolic link wouldn't work) or it would error out saying it couldn't find it (or said it was not a valid file if I used a symbolic link). Is there a better way to do that part or do I need to wait for a newer version of WeiDU?
However, Without going into the whole technical aspect of the constraints on modding the IE engine, it is necessary (or the opposite of extremely impractical) for all mods to use the same version of the same tool. Hence, WeiDU has its autoupdate et al., to try to keep things homogeneous in your game folder. Looks good, but for one minor niggle: you packaged your mod while it was installed, so the archive includes the backup folder and uninstall info from your installed-state. I don't think it can cause any problems, because WeiDU determines installedness from weidu.log and WeiDU would probably either overwrite old backup info or ignore it when someone else installs the mod. But there's the neatness and the formal correctness, as well. Simply deleting the backup folder from the archive, or uninstalling the mod and creating another archive would be enough.
1) If the official version of the file is updated by the developer, your mod will incorporate those changes (as long as they don't conflict)
2) Two mods affecting the same file (say, an NPCs dialog) could both be installed
If you read the WeiDU documentation, half of it talks about dialog scripting, and the other half is about writing these mod scripts. It is some pretty complex stuff, but not too hard to get the hang of. Take a look at some of the mods out there and you'll see the different techniques used.
Here's a Mod that I did to fix some issues with the Fishermen and the Priestess quest, and the TP2 file that will create it. You can use Weidu to convert the files in the zip so you can see the source code and compare them to the files in the released game to see what I changed.
So you could just drop these files in the override directory, but that would replace any modifications already made to these files. This TP2 script takes the existing files from the game and just makes the modifications necessary to implement the fix. Note that in this case the only file in the mod is the tp2, since it doesn't introduce any new creatures / scripts / items, just modifies existing ones.
(This is my first serious TP2, so I welcome any feedback from experienced modders)
The important stuff:
- You must rename the inlined files to something very unique to your mod. Inlined files occupy the same namespace between all mods in stack operations, so there is a potential for conflicts. See here.
- You should call your mod folder something other than "mymod"
- DECOMPILE_BCS_TO_BAF is deprecated these days (informally now; formally as of next version). Use DECOMPILE_AND_PATCH instead.
The fluff:Is it considered better form to inline the actions, or have separate files? Is it just a complexity thing?
Here is a better behaved TP2
COPY_EXISTING JEBADO.CRE override SONNER.CRE override TELMEN.CRE override /* Change alignment to Neutral Evil 035 */ WRITE_BYTE 0x27b 35I never knew about the inline trick though and I still have a bad habit of using DECOMPILE_BCS_TO_BAF... must stop that.
You know how to edit a BCS file using NI or WeiDU
You are familiar with the Fishermen & the Priestess quest
So here's a little snippet from the above TP2 - we're trying to fix two things with Tenya.bcs:
* I gave Tenya an item (minhp1) to prevent her from dying with your first hit. We need to get rid of that item before continuing the fight.
* I gave her the command spell instead of entangle, since she doesn't have any ranged weapons. The PRIEST.bcs script doesn't try to cast Command, so I'm adding it to her personal script.
So, here's the TP2:
<<<<<<<< .../Fisher754-inlined/TENYA1.baf IF See(NearestEnemyOf(Myself)) HaveSpell(CLERIC_COMMAND) !StateCheck(NearestEnemyOf(Myself),STATE_SLEEPING) !StateCheck(NearestEnemyOf(Myself),STATE_HELPLESS) THEN RESPONSE #100 Spell(NearestEnemyOf(Myself),CLERIC_COMMAND) END >>>>>>>> COPY_EXISTING ~TENYA.bcs~ ~override/TENYA.bcs~ DECOMPILE_AND_PATCH BEGIN REPLACE_TEXTUALLY CASE_SENSITIVE EXACT_MATCH ~SetGlobal("TenyaHit","GLOBAL",1)~ ~SetGlobal("TenyaHit","GLOBAL",1) DestroyItem("minhp1")~ APPEND_FILE ~.../Fisher754-inlined/TENYA1.baf~ ENDSkip to the COPY_EXISTING: all we are doing here is telling WeiDU to take a copy of TENYA.BCS from the game data and put it in the override folder. The commands following this apply to this copy.
The next line (DECOMPILE_AND_PATCH) takes the binary-ish bcs and translates it to the baf syntax we know and love. So everything between the BEGIN and END are acting on the human-readable source code. After the END the source is compiled back into BCS, which is stored in the override folder.
The REPLACE_TEXTUALLY command is a simple search and replace. In this case I want to add a command, so I search for the command preceding where I want the new command to go. Then I replace the old command with the old command plus my new command (Destory minhp1)
APPEND_FILE takes the contents of a file and appends them to the active file. The problem is that I don't have a file to append. The first block (between the <<<<<<<<< ... >>>>>>>>>) defines a virtual file that can be referenced by APPEND_FILE. So that if block is just pasted to the bottom of the script.
Simple, right?
Yes, I can write an introduction to simpler patching (and follow with more advanced stuff, should that be desired). I'd focus on WeiDU's pre-built solutions and standard library (functions and higher-level abstractions) rather than arithmetic in base 16 and other things you should not have to do (or do as little as possible of) for everyday modding. Sounds good?
In case someone else would like to know more about how to perform some common task, I'm also open to requests. Already considered are
- patching items (and spells, because they are virtually identical),
- patching stores (adding/removing items) and
- patching creatures (adding/removing items, effects).
Anything else?I was going to make each installment a separate thread. That way you have the material and comments/questions on the material in the same place, and you work with peoples' propensity to comment on a thread, instead of against it. I or someone else can then make a master index thread, to have everything linked to from one place.
- Part One: Limitations of the Engine
- Part Two: Game Files Involved
- Part Three: Installing with WeiDU
- Part Four: Additional WeiDU Functions
The author may even be around to answer questions.However i did design a weidu add_kit template which might make it easier for some people who're just starting out to understand. Download it from here
Credit to the people who made psionics unleashed whose weapon proficiency information layout I copied. If you are unhappy with me using it then just say and I will remove it.
Feel free to contribute what you wrote. I'll gladly look it over.
@CamDawg
I've spent an embarrassing amount of time thinking of how to weave your tutorial into this in a graceful manner. However, now I'm going to bed, so I'll just note that the bit about the backup folder in part 3 is outdated. There are also bits of part 4 I'm not terribly fond of (for an introductory text), what with asking people to grasp bytes, words, offsets and so on. But I know you did your best there, not to mention the current lack of alternatives. (If no one else does it, I'll write a function for altering creatures.)
Patching an existing item: Patching an item into a store: Patching an item onto a creature: I don't comment standard code like SOURCE_SIZE checks, which account for a mostly-deprecated ALLOW_MISSING usage that would create zero-byte invalid resource files if they didn't exist. And BUT_ONLY (short for BUT_ONLY_IF_IT_CHANGES) only executes the patch if there's an actual change. For example, if you were writing an item price of 100 and it was already 100, it wouldn't bother copying and patching the file since there's no change. Anything else that isn't clear, let me know.