A course on WEIDU - chapter 1: Introductory WEIDU

By DavidW - V1.1 12/14/2023

• Introduction
• Chapter 1 (Introductory WEIDU)
• Chapter 2 (Programming in WEIDU)
• Chapter 3 (Specific WEIDU commands)
• Chapter 4 (More advanced topics)
• Appendix (the WEIDU readme)

This chapter covers the rudiments of WEIDU: you'll learn how to set it up and how to write a basic mod that installs files you've already created in an editor.

WEIDU (created by Wesley Weimer, heavily developed by Valerio Biggiani ("TheBigg") and maintained currently by Wisp) is the standard modding tool for writing and installing IE mods. To set it up:

• Download the latest version of WEIDU. The latest version (v249 at time of writing) is here.
• Unzip the download and extract weidu.exe to the folder in which your IE game is installed. (I’ll be assuming this is BG2 for the most part, but WEIDU works for any of the Infinity Engine games.)
• Pick a name for your mod. By tradition, I’ll use ‘mymod’ for that name, but you should use something unique. The normal convention is to pick a couple of letters or numbers that no-one else has used and to start all your names with those letters; I use ‘dw’, for instance, so I might choose ‘mymod’ to be ‘dwnewmod’.
• Make a copy of weidu.exe and call it ‘setup-mymod.exe’ (where again ‘mymod’ stands in for your mod’s name – I won’t keep saying this).
• Create a new folder, "mymod", in your BG2 directory. In that folder, create a new text file and call it "mymod.tp2".
• Open up "mymod.tp2" in a text editor (Notepad is fine; Context or Notepad++ is better; lots of others exist and everyone has their own favourites). Enter the following text (it doesn’t matter exactly how long the lines of //////// are, or even if you put them in at all; they’re just there for readability):

BACKUP "weidu_external/backup/mymod"
AUTHOR "Myname (my email address)"
AUTO_EVAL_STRINGS

/////////////////////////////////////////////////////////////////////////////////////////////////////
BEGIN "Boring component" DESIGNATED 100
/////////////////////////////////////////////////////////////////////////////////////////////////////
OUTER_SPRINT boring "This is a boring string"
PRINT "The value of the boring string is ‘%boring%’"

//////////////////////////////////////////////////////////////////////////////////////////////////////
BEGIN "Even more boring component" DESIGNATED 200
//////////////////////////////////////////////////////////////////////////////////////////////////////
PRINT "Here is some text"

If you now double-click on setup-mymod.exe, you will be offered the choice of installing the two boring components. If you do, you should see some text displayed.

Let’s look at the basic structure of the file. It starts with a block called the preamble, which specifies some stuff relevant to all components of the mod. In this case, the only information in the preamble is the folder used to back up the mod, the information to display to the user if the mod fails to install, and a somewhat gnomic command, ‘AUTO_EVAL_STRINGS’, that specifies the version of WEIDU we’re using. (If you want to use this guide, do not remove the AUTO_EVAL_STRINGS command: the guide assumes it in many places.)

After that is a list of components, each starting with a BEGIN ~My component name~ (and each being ended, implicitly, either by the next BEGIN line or the end of the file). The BEGIN line also includes a ‘DESIGNATED’ line that assigns a unique number to each component: you can pick these numbers, but it’s a good idea to make them increase by a reasonably large value (10 or 100) between each component. (You can skip the DESIGNATED if you like, and WEIDU will assign a number automatically, but I don’t recommend it.)

In the text following the BEGIN line you put the instructions required to install the component. In this case, the instructions don’t do anything very interesting. All the first component is doing is defining a variable (‘boring’), specifying what the value of that variable is, and then printing it. It’s boring because it isn’t actually doing anything to Baldur’s Gate at all (and if you just want to program without any IE-specific applications, WEIDU is a poor choice). The second component is even worse.

WEIDU comes equipped with a huge range of commands that could be put into the text of the component instead. They are exhaustively detailed in the WEIDU readme. In programming terms the standard WEIDU commands are mostly "low level" – they let you insert or modify bytes in the files on the basis of how far into the file they occur, without much engagement with the high-level interpretation of a given file as (say) a spell or creature.

(Incidentally, the particular choice of backup folder here (weidu_external/backup/mymod) stores the backup information as a subfolder of a folder (“weidu_external”) common to several of my mods and which is shareable with others. A more traditional alternative would be to choose mymod/backup, which stores the backup information as a subfolder of your own mod folder. I am inclined to think that it is better not to do this as (among other reasons) it makes it easy to accidentally distribute a (potentially large) backup folder when you publish the mod, but it’s up to you.)

COPY "%MOD_FOLDER%/SPWI304.spl" override
COPY "%MOD_FOLDER%/SPWI308.spl" override

Let’s break this up.

• 'COPY’ is an instruction to WEIDU: take an existing file, copy it to another location. COPY takes two arguments: you write ‘COPY this that’, and it copies this to that.
• 'this’ (the first argument) is the location of the first thing you want to copy. ‘%MOD_FOLDER%’ is a variable (more on them later) that just stores the name of your mod’s main folder. So you could have replaced it with ‘mymod’, but it’s better practice to use the variable, so that if you ever decide to change your mod’s name you don’t need to edit your code.
• ‘that’ (the second argument) is where you want to copy it to. 99% of the time, this will be ‘override’, the override folder of the main game (files in this space override files in the main game data files).

Before continuing, let’s ask why you’d want to code this super-minimal mod in WEIDU instead of just distributing the files for people to drop into their override manually. The answer is that if you uninstall this change, WEIDU will just roll back the changes and restore the previous versions of Fireball and Lightning Bolt. That matters in particular in case some other mod you installed earlier has also altered those spells: if so, uninstalling this component will restore the other mod’s version of the spells, not the unmodded game’s version.

(To be truthful, with something this simple it doesn’t matter all that much, but it quickly starts to as the mod gets more complicated.)

There are a few variations of the COPY command worth knowing. Firstly, you can list lots of ‘this’ … ‘that’ pairs at once – you don’t need to repeat COPY each time. The following works just as well as our previous code:

COPY
	"%MOD_FOLDER%/SPWI304.spl" override
	"%MOD_FOLDER%/SPWI308.spl" override

Secondly, if you want to change the name of the file, you can do so. Maybe you decided to store the modified spells with easy-to-memorize names? Then you’d do this:

COPY
	"%MOD_FOLDER%/fireball.spl" "override/spwi304.spl"
	"%MOD_FOLDER%/lightning_bolt.spl" "override/spwi308.spl"

Thirdly, you can copy a whole directory at once. Let’s suppose you’ve decided to keep your mod folder tidy by creating a subfolder, overpowered_spells, in which you’ve placed your two spells. (This is generally good practice.) Then you can do the following to copy everything in that folder into the override:

COPY "%MOD_FOLDER%/overpowered_spells" "override"

Scripts (suffix .bcs) are files that tell creatures (or occasionally objects, areas, or the whole game) what to do. For instance, WTASIGHT.BCS says ‘attack the nearest enemy’ and is used by lots of monsters. Dialogs (suffix.dlg) are files that tell creatures (or occasionally other things) what to say when you talk to them. The format of either file is beyond the scope of this course, but what matters here is that both scripts and dialogs are usually written in a human-readable form and then compiled into the form that the game uses. Scripts are stored as .baf files; dialogs are stored as .d files.

(The .baf -> .bcs compilation is built into the core game. The .d -> .dlg compilation is a creation of WEIDU. And d files are much more powerful than baf files, and can encode edits to existing dialogs or create multiple dialogs at once.)

This means that your mod will normally store dialog and script files in uncompiled form. You’ll compile them when you install the mod, like this:

COMPILE 
	"%MOD_FOLDER%/mybaf.baf"
	"%MOD_FOLDER%/mydlg.d"

(You can in principle compile a whole directory, like with COPY. I recommend against this: you should have tighter control of what you’re compiling.)

Often you’ll want not to create an entire new script, but just to add a bit of code onto an existing script. That’s easy to do in WEIDU. This code adds ‘mybaf.baf’ to the top of the existing script ‘wtasight.bcs’:

EXTEND_TOP "wtasight.bcs" "%MOD_FOLDER%/mybaf.baf"

If you want to put your new code at the bottom instead, use EXTEND_BOTTOM.

Sometimes your mod might want to alter an existing file rather than overwriting with a new one. (More sophisticated mods do this almost exclusively.) For instance, maybe you want Minsc to be a fighter with the Berserker kit, not a Ranger. For this, we need the COPY_EXISTING command. Here’s some code that does this (in BG1):

COPY_EXISTING 
	"minsc.cre" override
	"minsc2.cre" override
	"minsc4.cre" override
	"minsc6.cre" override
	"minsc7.cre" override
		WRITE_BYTE 0x273 1
		WRITE_LONG 0x244 0x4001
BUT_ONLY
IF_EXISTS

Firstly, we’re COPYing some EXISTING files: the four creature files minsc.cre, minsc2.cre, minsc4.cre and minsc6.cre that specify Minsc’s stats in BG1. (Which one is used depends on your own level when you meet him.) We’re not copying over our own new files this time; we’re copying existing game files.

Secondly, we’re giving WEIDU some instructions as to what to do to the file when we copy it. The WRITE_BYTE and WRITE_LONG commands alter Minsc’s stats to something new.

Thirdly, we’re telling WEIDU that it should only make the copy if something has actually changed. (‘BUT_ONLY’ is short for ‘BUT_ONLY_IF_IT_CHANGES’).

Fourthly, we're telling WEIDU that it should only carry out the copy if the file exists. ('IF_EXISTS' is short for 'BUT_ONLY_IF_IT_EXISTS'). Without this command, if the file isn't present then WEIDU will give an error message instead of installing.

So the overall form of the command is

COPY_EXISTING 
	file1 override
	file2 override
	…
		[patch commands]
BUT_ONLY
IF_EXISTS

You can also use this syntax with ordinary COPY, incidentally, in case you want to alter the file you’re copying over from your own mod. (The BUT_ONLY and IF_EXISTS flags aren't necessary in this case.) Normally you’ll do this if you want its contents to depend on what other mods are installed.

How do the [patch commands] work? By default, WEIDU treats anything it’s copying just as a binary file. Files like this are lists of numbers, each in the 0-255 range, each with an ‘offset’ – how far through the file it is. The first number has offset 0, the second has offset 1, and so on. WEIDU’s basic patch commands just say: `go to offset this-offset and replace the number at that offset with this-number’.

By convention, in WEIDU we specify offsets, and often numbers, in hexadecimal: so the basic numbers are in the 0x00-0xff range. We do this because we want to deter newbs because the way files are organized makes hexadecimal offset easier to read and manipulate. (But you can skip this if you like and just use decimal: 0x273, for instance, is 627 in decimal.)

There are then four basic patch commands:

• WRITE_BYTE [ind] [number] puts [number] (in the 0-255 range) into offset [ind]
• a SHORT is an integer in the (0-255)2 range (or: two integers in the 0-255 range sequentially); WRITE_SHORT [ind] [number] puts [number] into the two slots following offset [ind]
• a LONG is an integer in the (0-255)4 range (or: four integers in the 0-255 range sequentially); WRITE_LONG [ind] [number] puts [number] into the two slots following offset [ind]
• an ASCII is a string of letters, numbers and other sequences; WRITE_ASCII [ind] ["string"] writes that string at offset ind, converting letters to their code numbers in the process.

In the example, the BYTE at 0x273 stores the creature’s class; setting it to 1 makes Minsc a fighter. The LONG at 0x244 stores the creature’s kit; setting it to 0x4001 makes Minsc a berserker. (You can look these up in Near Infinity or in the IESDP).

There are some subtleties about WRITE_ASCII that arise because a string might be of any length (whereas BYTEs, SHORTs and LONGs are of fixed length). Suppose, for instance, I want to swap Jaheir’s dialog file for a new file, ‘dwjah’, of my own devising. The dialog file lives in the sequence of 8 bytes at offset 0x2cc, so your natural guess as to how to do this might be

COPY_EXISTING 
	"jaheir.cre" override
		WRITE_ASCII 0x2cc "dwjah"
BUT_ONLY

The problem with this is that ‘dwjah’ only has five characters, so WEIDU only writes ‘dwjah’ over those five characters. But a dialog file name can be up to eight characters, and indeed Jaheira’s default dialog file is ‘jaheir’, which has six characters. So if you tried this code, Jaheira’s new script would be ‘dwjahr’ – the last character of the old script is still there. The solution is to specify the length of the ASCII write explicitly, like this:

COPY_EXISTING
	"jaheir.cre" override
		WRITE_ASCII 0x2cc "dwjah" (8)
BUT_ONLY

Two more things about patching files before we move on. Firstly, WEIDU has quite a lot of offsets for the main file type pre-memorized (there’s a full list in section 15 of the main WEIDU readme). For instance, it knows the location of the dialog file is 0x2cc. When you’re writing to one of these offsets, you can use WEIDU’s pre-stored value of the offset instead of entering it manually, like this:

COPY_EXISTING 
	"jaheir.cre" override
		WRITE_ASCII DIALOG "dwjah" (8)
BUT_ONLY

Secondly: you can also clone existing files to make new files. For instance, this code makes a copy of the Baldur’s gate basic hobgoblin with a different combat script.

COPY_EXISTING "hobgob.cre" "override/dwhobgob.cre"
	WRITE_ASCII SCRIPT_OVERRIDE "dwscript" (8)

Let’s talk about altering in-game text: the names of characters and items, the descriptions of items and spells, and so forth. Suppose you want to alter Minsc’s name to ‘Minsc the Awesome’, for instance.

‘Minsc the awesome’ is a string, so you might guess that you need to do a WRITE_ASCII to minsc.cre. That’s not how it works. Text isn’t stored in individual files; it’s stored in a huge table called a dialog file. When the game wants to display Minsc’s name, it looks in the ‘name’ offset of minsc.cre and finds a LONG value, 9501. Then it goes to the dialog file, finds the entry labelled ‘9501’, and sees that it’s ‘Minsc’. There are a bunch of reasons the game works this way, but one main reason is that it makes translations into other languages easier. If you want a sword to be called ‘epee’ in French, you don’t need to alter the sword file itself, you just alter the text in the French version of the dialog file.

(The other main reason is that Minsc’s name might be arbitrarily long, so that if it was stored directly in his CRE file, that file would have to cope with variable-length fields. As it is, the NAME field can be fixed to be four bytes long.)

What all this means is that we need to get ‘Minsc the Awesome’ into the dialog file with a new number, get that number, and then put the number into the right offset in minsc.cre. Fortunately, WEIDU makes this pretty simple: you just do this:

COPY_EXISTING
	"minsc.cre" override
	"minsc2.cre" override
	"minsc4.cre" override
	"minsc6.cre" override
		SAY NAME1 "Minsc the Awesome"
		SAY NAME2 "Minsc the Awesome"
BUT_ONLY

This ‘SAY’ command has the general form ‘SAY [offset] [string]’ (here we’re using WEIDU’s prememorized offsets for the two ‘name’ fields in a .cre file). When you use it, WEIDU looks in the dialog file for "Minsc the Awesome". If it finds it, it writes the number of that string into [offset]. If it doesn’t find it, it adds "Minsc the Awesome" to the dialog file with a new number, and then writes that number into [offset]. In this case, we’re using the same string twice. The first time, it gets added to the dialog file; the second time, it’s already there, so we just reuse the first value.

(Editing the dialog file in a friendly way was the original selling point of WEIDU, 20 years ago. Before WEIDU, mods had to distribute their own copies of the dialog file, which meant that no two mods could both change in-game text.)

Actually, the simple method of entering in-game text mostly isn’t used by well-designed mods. The reason is, again, translation. If you write "Minsc the awesome" into your mod directly, translating your mod into another language means distributing a new version of the mod. It’s better instead to take a leaf out of Baldur’s Gate’s book and use your own version of a dialog file.

Here’s how this works. Firstly, you need to create a file called a ‘tra’ file for each language you’re using. Unless you’re multilingual, probably you’ll only create a tra file for one language; I’ll assume it’s English. The tra file should have a name like ‘setup.tra’, can be created in a text editor, and is going to look like this:

@1="Minsc the Awesome"
@2="Rename Minsc so he’s awesome"
@3="A third string that we don’t need"

Secondly, you need to put this tra file into your mod. There are fairly specific rules as to where to put this file. You should:

• Create a folder inside your mod folder with a name like ‘tra’, ‘lang’, or ‘languages’. (I’ll use ‘lang’ in this course.)
• Create a folder inside ‘lang’ named for your language, in this case English.
Put your tra file inside that folder.

Thirdly, you need to alter your tp2 file to tell WEIDU where the tra file is. Because this applies for the whole mod, it’s done in the preamble, not in a component. (Everything else we’ve done so far is inside a component.) Here’s how we’ll do it:

BACKUP "weidu_external/mymod/backup"
AUTHOR "Myname (my email address)"
AUTO_EVAL_STRINGS

/// Language options
LANGUAGE 
"English"  
"english" 
"mymod/lang/english/setup.tra"

/////////////////////////////////////////////////////////////////////////////////////////////////////
BEGIN "the first component" DESIGNATED 100 
/////////////////////////////////////////////////////////////////////////////////////////////////////
…

The line under ‘LANGUAGE’ has three parts to it. The first is how the language is described to the person installing the mod. The second is the name of the folder in which you’re storing your tra files. The third is the path to your tra file.

(By the way, you can’t (safely) use %MOD_FOLDER% in these LANGUAGE commands, due to a glitch in WEIDU (see here for more). You have to enter ‘mymod’ manually.)

Since there’s only one LANGUAGE command entered here, WEIDU will just automatically pick English when you install the mod. But you can now refer to strings in the tra file in your components, like this:

COPY_EXISTING 
	"minsc.cre" override
	"minsc2.cre" override
	"minsc4.cre" override
	"minsc6.cre" override
		SAY NAME1 @1
		SAY NAME2 @1
BUT_ONLY

When you write @1 WEIDU looks up the first string in your tra file and uses it. So now you’ve moved the string out of your main code and into the tra file. The power of this now comes when someone translates your mod into (say) French. They’ll create their own setup.tra and send it to you, and you’ll put it in a ‘french’ subfolder of the ‘lang’ folder; it will look something like

@1="Minsc le genial"
@2= "renommer Minsc tellement il est genial"

Then you’ll expand your LANGUAGE declaration to look like this:

/// Language options
LANGUAGE 
"English"  
"english" 
"mymod/lang/english/setup.tra"
LANGUAGE
"French (translation by Google Translate)"
"french"
"mymod/lang/english/setup.tra" "mymod/lang/french/setup.tra"

Now we have a second LANGUAGE block that defines French. It includes the text to display to the player, the variable to set, and the path to the French translation. Perhaps surprisingly, it also contains a second path, to the English tra file. This is a backup: in case your translator has missed a line, the English translation gets used instead. (For large mods, or mods that are updated frequently, sometime the translation can get out of sync.) The English backup is listed first, because WEIDU loads tra files in order and overwrites earlier ones with later ones.

Now if someone installs your mod, they’ll be offered the choice at the start of English or French. And WEIDU will use the tra file appropriate to their language.

You can put @ commands into your .d and .baf files, and WEIDU will slot in the correct strings when you compile those files. You can also use @ commands in the names of your components, so that they also get translated. Here’s the complete ‘awesome Minsc’ mod, making this change too:

BACKUP "weidu_external/mymod/backup"
AUTHOR "Myname (my email address)"
AUTO_EVAL_STRINGS

/// Language options
LANGUAGE 
"English"  
"english" 
"mymod/lang/english/setup.tra"
LANGUAGE
"French (translation by Helen)"
"french"
"mymod/lang/english/setup.tra" "mymod/lang/french/setup.tra"


/////////////////////////////////////////////////////////////////////////////////////////////////////
BEGIN @2 DESIGNATED 100  // Make Minsc awesome
/////////////////////////////////////////////////////////////////////////////////////////////////////

COPY_EXISTING 
	"minsc.cre" override
	"minsc2.cre" override
	"minsc4.cre" override
	"minsc6.cre" override
		SAY NAME1 @1
		SAY NAME2 @1
BUT_ONLY

Problems with charsets

One nasty problem in working with multiple languages – or indeed, working with any language that has accents, umlauts, or non-Latin characters, i.e. most languages other than English – is that there are different encoding conventions for how these languages are stored in text files. The Enhanced edition of Baldur’s Gate uses a UTF-8 convention; the original one uses (I think) ISO-8859.

If you are working with only one version of the game (probably the Enhanced Edition) this isn’t too difficult to handle: just make sure your tra files are in that game’s encoding, probably UTF-8. (Your text editor program will have some option to set this.) If you want to make your mod compatible with old and new versions of the game it’s quite a bit more complicated; see here.

Especially as your mod gets more complicated, you may want to break your tra file into multiple components. In particular, it’s common practice for each dialog file to have its own associated tra file.

USING commands

If you’re compiling or extending dialogs or scripts, this is pretty easy: you just specify the tra file you want to use using a ‘USING’ command, like this:

COMPILE "%mymod%/mydlg.d" USING "%MOD_FOLDER%/english/mymod.tra"

When you run this bit of code, WEIDU loads the mymod.tra tra file from mymod/English, and uses those strings in preference to any tra file you’ve already loaded. You can put a USING command at the end of an EXTEND_TOP or EXTEND_BOTTOM too.

You may have noticed a limitation here: by specifying the whole path to the tra file we’ve hardcoded English as our preferred language. That’s easy to work around: just do this:

COMPILE "%mymod%/mydlg.d" USING "%MOD_FOLDER%/%s/mymod.tra"

AUTO_TRA

There is a systematic shortcut specifically for dialog files. If you put ‘AUTO_TRA "[path to your language directory]’ in the preamble of your mod, like this:

BACKUP "weidu_external/mymod/backup"
AUTHOR "Myname (my email address)"
AUTO_EVAL_STRINGS
AUTO_TRA "%MOD_FOLDER%/lang/%s"

More advanced dialog loading

You can also load a dialog file manually. The following code loads ‘awesome.tra’ from your language directory, and also (as a backup) from the English language directory:

WITH_TRA
 "%MOD_FOLDER%/english/awesome.tra" 
"%MOD_FOLDER%/%LANGUAGE%/awesome.tra"
BEGIN
.. some comands
END

awesome.tra is forgotten as soon as you get to the ‘END’ command. If you want to load it permanently, do this instead:

LOAD_TRA
 "%MOD_FOLDER%/english/awesome.tra" 
"%MOD_FOLDER%/%LANGUAGE%/awesome.tra"

The basic editing tools – WRITE_LONG, WRITE_ASCII, SAY, etc – are pretty limited in what they let you do, basically because they only work if you know in advance exactly which offset to edit. That’s fine for fields like names, creature scripts, or soundsets, which always occur at the same offset. But most of the data stored in game files might be stored in different offsets for different files of the same type. For instance, a store can hold arbitrarily many items, so there can’t just be a fixed offset for, say, the 10th item in the store. That means that if, say, you want to add a new item to a store, WRITE_LONG and friends aren’t up to the job.

Systematically learning how to edit these features of game files requires more advanced WEIDU than we’re covering in this chapter. But WEIDU has built-in tools to do many of the most common edits. For instance, adding that item to a store is done like this:

COPY_EXISTING sto4803.sto override
	ADD_STORE_ITEM "dw_wnd01" #10 #0 #0 IDENTIFIED #3
BUT_ONLY

This adds 3 copies of ‘dw_wnd01’ to the store (it’s the Nashkel store, as it happens), each with 10 charges. See the main WEIDU readme for full documentation.

There are lots of these built-in tools. As of WEIDU v249, here’s the list (most have self-explanatory names):

• ARE files
  • ADD_MAP_NOTE
• CRE files
  • ADD_KNOWN_SPELL
  • ADD_MEMORIZED_SPELL
  • REMOVE_KNOWN_SPELL
  • REMOVE_KNOWN_SPELLS (removes all known spells)
  • REMOVE_MEMORIZED_SPELL
  • REMOVE_MEMORIZED_SPELLS (removes all memorized spells)
  • SET_BG2_PROFICIENCY
  • ADD_CRE_ITEM
  • REPLACE_CRE_ITEM
  • REMOVE_CRE_ITEM
  • REMOVE_CRE_ITEMS (removes all items)
• STO files
  • ADD_STORE_ITEM
  • REMOVE_STORE_ITEM

You can go vastly beyond the built-in tools by using the range of functions that ship with WEIDU, but that’s for a later chapter.

Comments

Any text following two or more ‘/’ is ignored. So is any text between ‘/*’ and ‘*/’. You can use this to comment your code and make it easier to read. For instance

/* 
this code
will make Minsc
into ‘Minsc the Awesome’
*/
COPY_EXISTING "minsc.cre" // need to add minsc2, etc, later
	// here’s Minsc’s first name entry
	SAY NAME1 @1
	// here’s Minsc’s second name entry
	SAY NAME2 @1
BUT_ONLY

Inlining files

Sometimes it’s convenient not to have to put text (e.g., a script) into a separate file, but instead to include it in your main TP2. (That’s mostly the case for very short bits of text.) You can do this through ‘inlined files’, basically files that are included in your tp2 but which WEIDU treats as actual files. Here’s an example:

<<<<<<<<.../mymod-inlined/minsc_add.baf
IF
	See(NearestEnemyOf(Myself))
Delay(10)
THEN
	RESPONSE #100
		DisplayStringHead(Myself,@1) // ‘I’m AWESOME!’
END
>>>>>>>>

EXTEND_TOP "minsc.bcs" ".../mymod-inlined/minsc_add.baf"

Breaking up your code with INCLUDE

It can get messy putting all of your code into one very long TP2. To make it more manageable, you can put some bits of your code in separate files. (Normal convention is to have them end in ‘.tph’ or ‘tpa’ but you can do whatever you like.) You can then use ‘INCLUDE [file-path]’ in your main tp2 and WEIDU will just insert the code and treat it as if it was just part of the original tp2.

Here’s an example of a mod where all the content has been moved into INCLUDEd files like this. (That’s my own preferred way of writing mods.)

BACKUP "weidu_external/mymod/backup"
AUTHOR "Myname (my email address)"
AUTO_EVAL_STRINGS

/// Language options
LANGUAGE 
"English"  
"english" 
"mymod/lang/english/setup.tra"

/////////////////////////////////////////////////////////////////////////////////////////////////////
BEGIN @2 DESIGNATED 100  // Make minsc awesome
/////////////////////////////////////////////////////////////////////////////////////////////////////

INCLUDE "%MOD_FOLDER%/lib/awesome_minsc.tph" 

/////////////////////////////////////////////////////////////////////////////////////////////////////
BEGIN @3 DESIGNATED 200  // Make tiax less annoying
/////////////////////////////////////////////////////////////////////////////////////////////////////

INCLUDE "%MOD_FOLDER%/lib/less_annoying_tiax.tph" 

Quote marks

I have been using " for quotations in examples so far. But WEIDU is just as happy using ~ or % to begin and end quotations, which can be useful if you want to include an actual " sign in a string:

~I said, "Minsc is awesome!"~
%Two of the three WEIDU quote marks are ~ and ". %

Very occasionally even that doesn’t work, in which case you can use five consecutive tildes, ~~~~~, as a quote mark:

~~~~~The three basic quote marks in WEIDU are ~, " and %. ~~~~~ 

Here’s an example of a mod that uses most of these techniques:

BACKUP "weidu_external/dw_awesome/backup"
AUTHOR "DavidW (my email address)"
AUTO_EVAL_STRINGS

/// Language options
LANGUAGE 
"English"  
"english" 
"dw_awesome/lang/english/setup.tra"
LANGUAGE
"French (translation by Google Translate)"
"french"
"dw_awesome/lang/english/setup.tra" "dw_awesome/lang/french/setup.tra"


/////////////////////////////////////////////////////////////////////////////////////////////////////
BEGIN @1 DESIGNATED 100  // Rename Minsc to be awesome and make him a berserker
/////////////////////////////////////////////////////////////////////////////////////////////////////

WITH_TRA
	"%MOD_FOLDER%/dw_awesome/english/awesome_name.tra"
	"%MOD_FOLDER%/dw_awesome/%LANGUAGE%/awesome_name.tra"
BEGIN

	COPY_EXISTING 
		"minsc.cre" override
		"minsc2.cre" override
		"minsc4.cre" override
		"minsc6.cre" override
			SAY NAME1 @1
			SAY NAME2 @1
			WRITE_BYTE 0x273 1 // class=fighter
			WRITE_LONG 0x244 0x4001 // kit=berserker			
	BUT_ONLY
END // end of the WITH_TRA command

/////////////////////////////////////////////////////////////////////////////////////////////////////
BEGIN @2 DESIGNATED 200  // give Minsc an awesome battle cry
/////////////////////////////////////////////////////////////////////////////////////////////////////

<<<<<<<<.../dw_awesome-inlined/minsc_add.baf
IF
	See(NearestEnemyOf(Myself))
	Delay(10)
THEN
	RESPONSE #100
		DisplayStringHead(Myself,@1) // ‘I’m AWESOME!’
END
>>>>>>>>

EXTEND_TOP "minsc.bcs" ".../dw_awesome-inlined/minsc_add.baf" 
	USING "%MOD_FOLDER%/%s/awesome_cry.tra"

/////////////////////////////////////////////////////////////////////////////////////////////////////
BEGIN @3 DESIGNATED 300  // give Minsc an awesome new sword
/////////////////////////////////////////////////////////////////////////////////////////////////////

WITH_TRA
	"%MOD_FOLDER%/dw_awesome/english/awesome_sword.tra"
	"%MOD_FOLDER%/dw_awesome/%LANGUAGE%/awesome_sword.tra"
BEGIN
	// make the sword
	COPY_EXISTING "sw1h06.itm" "override/dw_swda.itm" // just a copy of Varscona, renamed
		SAY NAME2 @1
		SAY IDENTIFIED_DESC @2

END // end of the WITH_TRA command

	// give it to Minsc

COPY_EXISTING 
	"minsc.cre" override
	"minsc2.cre" override
	"minsc4.cre" override
	"minsc6.cre" override
		ADD_CRE_ITEM "dw_swda" #0 #0 #0 IDENTIFIED WEAPON EQUIP	
BUT_ONLY