Skip to content

Short introduction to WeiDU and simple mod template

WispWisp Member Posts: 1,102
edited January 2013 in General Modding

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.

Post edited by Wisp on
Troodon80JamesCuvFeatherErgCerevantBalquoermoSirK8MilochKilivitzAndreaColomboVaylorSCARY_WIZARDWigginnsCrevsDaakHeindrichbrusRik_KirtaniyaStummvonBordwehr
«134

Comments

  • ljboljbo Member Posts: 177
    Thanks for those explanations. I am afraid there are a few points I did not grasp though.


    Wisp said:


    Customarily, the mod is distributed together with a copy of WeiDU itself, but this is not a formal requirement.

    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?

  • mlnevesemlnevese Member, Moderator Posts: 10,214
    @Wisp is there any news of a new version of Weidu for EE?
    bleusteel
  • CamDawgCamDawg Member, Developer Posts: 3,438
    ljbo said:

    Thanks for those explanations. I am afraid there are a few points I did not grasp though.

    Wisp said:


    Customarily, the mod is distributed together with a copy of WeiDU itself, but this is not a formal requirement.

    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?
    WeiDU is self-updating and fully backwards compatible--if you were to download a bunch of mods into your game folder and run any one of the setup-some_mod.exe, it would check all of the other setup-some_other_mod.exe, find which is the most recent version, and update all of them. I don't think weidu.exe itself is checked, but it's very rare that a mod ships with a copy of WeiDU that can't install it.

    The latest stable WeiDU is on WeiDU's own website though sometimes beta or WIP builds are released onto their forums.
    ljbo said:


    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?

    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.
    mlnevese said:

    @Wisp is there any news of a new version of Weidu for EE?

    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.
    mlneveseSirK8Ergermo
  • SirK8SirK8 Member Posts: 527
    Ok, so I gave this a shot. I used the beta version available here - http://forums.pocketplane.net/index.php/topic,28279.0.html

    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?
    mlnevese
  • mlnevesemlnevese Member, Moderator Posts: 10,214
    You'll need a newer version. Final version of weidu should make dealing with dialog.tlk easier.
    SirK8
  • WispWisp Member Posts: 1,102
    To complement Cam's answer:
    ljbo said:


    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?

    All relevant mods are handled by the running copy of WeiDU (the copy you use to install or uninstall mods). Which mods are relevant would depend on what you are doing. If you are installing a mod, only it is relevant. If you are uninstalling a mod, it and all mods installed after it are relevant. As such, it is the user who decides which copy of WeiDU takes precedence.

    However,
    ljbo said:


    In case a particular mod has to rely on a particular version of WeiDU

    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.
    SirK8 said:


    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.

    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.
    SirK8ermo
  • SirK8SirK8 Member Posts: 527
    @Wisp - thanks for the pointer!
  • CerevantCerevant Member Posts: 2,314
    The "next step" for a mod developer is learning how to modify existing game files using Weidu. There are two advantages to this:
    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)

    Erg
  • WispWisp Member Posts: 1,102
    @Cerevant

    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:
    • You don't need to specify the destination file unless you wish to alter the file name. COPY_EXISTING somefile override is enough.
    • You can give COMPILE a list of files instead of calling it once for each file.
    • There is also no need to use multiple inlined files. You can put all your D actions in a single file.
    ermoErg
  • CerevantCerevant Member Posts: 2,314
    Thanks @Wisp, Great feedback! The language is not the most intuitive, but I'm getting the hang of it.

    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
  • BalquoBalquo Member, Developer Posts: 2,746
    edited January 2013
    You can also do this since they are changing the same thing:

    COPY_EXISTING JEBADO.CRE override SONNER.CRE override TELMEN.CRE override /* Change alignment to Neutral Evil 035 */ WRITE_BYTE 0x27b 35

    I never knew about the inline trick though and I still have a bad habit of using DECOMPILE_BCS_TO_BAF... must stop that.
  • CerevantCerevant Member Posts: 2,314
    See, that's an example of one thing that confuses me about Weidu - it is never quite clear when you have to be explicit what you are acting on. My style would probably be to keep it the way I have it so that it is clear what I meant. (like using parenthesis in C code even when you don't need to)
  • WispWisp Member Posts: 1,102
    Cerevant said:


    Is it considered better form to inline the actions, or have separate files? Is it just a complexity thing?

    There is no objective reason to prefer one over the other as far as I am aware. I'd argue that you gain in clarity by having a single inlined file for D, instead of having foreign code throughout your TP2. If your D code is complex enough to warrant splitting up, it really should go into real files. Inlined files are handy, but at some point it weighs over and turns silly.
    Cuv
  • agrisagris Member Posts: 581
    @Wisp @Cerevant Could either of you dissect and comment a tp2 that a) patches an existing item, b) patches an item into a store and c) patches an item into a creature's whatever slot such that it benefits from the bonuses (assume passive bonuses on the item, and it's going into a wearable non-weapon slot) and provide some comments about the syntax usage? I've looked at some of @Miloch's tp2s and I think he's too many levels above me so it's not useful without comments.
  • CerevantCerevant Member Posts: 2,314
    Maybe I'll do a little bit at a time. So, I'm assuming:
    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~ END

    Skip 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?
    agrisErgCrevsDaak
  • agrisagris Member Posts: 581
    Thanks @Cerevant, it isn't as if you're getting paid to do this :) I certainly don't expect anything, but it has been frustrating trying to learn weidu with such diffuse and varied instructional materials.
  • WispWisp Member Posts: 1,102
    edited January 2013
    @agris
    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?
    agris
  • EdwinEdwin Member Posts: 480
    @wisp I think the best format for this would be a dedicated thread with a series of progressive tutorials. I would have really appreciated more of that sortt of thing in the early days.
    Togglebottom
  • WispWisp Member Posts: 1,102
    @Edwin
    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.
    SirK8
  • EdwinEdwin Member Posts: 480
    @Wisp Sounds good. Since there are so many ways to skin the cat via Wedui, I think your impulse to stick with straightforward implementations is spot on. I look back through earlier mods and see some very exotic wedui gymnastics whose methods became deprecated and not just a little confusing.
  • ljboljbo Member Posts: 177
    @Wisp I would really appreciate such tutorials
  • CorianderCoriander Member Posts: 1,667
    @Wisp There seem to be several kits popping up/being requested, so maybe one for adding a kit?
    agris
  • agrisagris Member Posts: 581
    @Coriander Right on, that's a good one. Would cover extending 2das, adding special abilities, dialog strings, and a host of other things I don't know.
  • RequiemRequiem Member Posts: 187
    @wisp I have actually been working on a weidu kit tutorial that should be ready in a day or two if you wanted me to send it your way? Makes sense to have everything in one place.
  • CamDawgCamDawg Member, Developer Posts: 3,438
    Coriander said:

    @Wisp There seem to be several kits popping up/being requested, so maybe one for adding a kit?

    You mean other than the comprehensive, four-part tutorial linked from the WeiDU docs? The author may even be around to answer questions.
    SirK8CrevsDaak
  • RequiemRequiem Member Posts: 187
    edited January 2013
    @camdawg Will leave it then, that was the tutorial I learnt from, no point trying to reinvent the wheel lol.

    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.
  • WispWisp Member Posts: 1,102
    @Requiem
    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.)
    ermo
  • CamDawgCamDawg Member, Developer Posts: 3,438
    Nah, it's pretty dated at this point, and lacks the BGEE-specific stuff like clasiskl.2da or thiefscl.2da. I'm going to make a run at updating at some point.
    ermoEdwinCrevsDaak
  • MilochMiloch Member Posts: 863
    agris said:

    @Wisp @Cerevant Could either of you dissect and comment a tp2 that a) patches an existing item, b) patches an item into a store and c) patches an item into a creature's whatever slot such that it benefits from the bonuses (assume passive bonuses on the item, and it's going into a wearable non-weapon slot) and provide some comments about the syntax usage? I've looked at some of @Miloch's tp2s and I think he's too many levels above me so it's not useful without comments.

    Hey, I comment my code. Usually. Though I'll grant my comments aren't as verbose as Wisp's above; they're more intended as developer pointers than instructional tips. Anyway, examples from Aurora's Shoes:

    Patching an existing item:
    COPY_EXISTING ~misc03.itm~ ~override~ //Small Box
    PATCH_IF SOURCE_SIZE > 0x71 BEGIN
    SAY UNIDENTIFIED_DESC @294
    READ_BYTE 0x18 fl //Flags
    WRITE_BYTE 0x18 (fl BOR 0b00000001) //Unsellable
    WRITE_SHORT 0x1c 0x24 //Item type (bag)
    WRITE_LONG 0x34 100 //Price
    END
    BUT_ONLY
    Patching an item into a store:
    COPY_EXISTING ~dshop01.sto~ ~override~ //Ikert (ar0300 Docks)
    ~wallace.sto~ ~override~ //Wallace (ar2000 Trademeet)
    PATCH_IF SOURCE_SIZE > 0x9b BEGIN
    ADD_STORE_ITEM ~agboot21~ LAST #0 #0 #0 ~IDENTIFIED~ #1 //Everyday Green Boots
    END
    BUT_ONLY
    Patching an item onto a creature:
    COPY_EXISTING ~%tsu%dushai.cre~ ~override~ //Dushai (in Ulgoth's Beard)
    PATCH_IF SOURCE_SIZE > 0x2d3 BEGIN

    ADD_CRE_ITEM ~t-ring05~ #0 #0 #0 ~UNSTEALABLE~ ~LRING RRING~ //Svirfneblin Ring
    REPLACE_CRE_ITEM ~agblun01~ #0 #0 #0 ~UNSTEALABLE~ ~WEAPON1~ //Svirfneblin Club
    ADD_CRE_ITEM ~%tsu%dart03~ #10 #0 #0 ~UNSTEALABLE~ ~WEAPON2~ EQUIP //Dart of Stunning
    END
    BUT_ONLY
    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.
    ErgagrisCrevsDaakelminster
  • CuChoinneachCuChoinneach Member Posts: 105
    edited January 2013
    Nice!
    CrevsDaak
Sign In or Register to comment.