A Course in WEIDU

[DavidW]

This is a course in basic-to-intermediate WEIDU. The level is somewhat uneven: Chapter 1 explains the basics of WEIDU without assuming any prior modding or programming experience, and I hope should be helpful to new modders. Chapter 2 is a more sophisticated and in-depth discussion, focussing on using WEIDU as a programming language (and de-prioritizing specific applications to IE games); I hope intermediate WEIDU users will find it a good way to get to the next step, and even advanced users might learn something. Chapter 3 discusses some specific programming tasks relevant to IE games.

(background: For a while, and in odd moments, I've been writing up some notes for a guide to modding in WEIDU - covering the basics, but then moving on to more advanced, programming-language, aspects. There's certainly more that could be done to improve it but I think it's probably solid enough to be worth posting. Comments welcome.)

Course link (HTML)

Edit, 14/12/23: Version 1.1 of the course is now available. Changelog:

• Moved to HTML.
• New chapter on advanced techniques (immutability, encapsulation, optmization).
• New section on error handling.
• New section on mod component structure.
• New section on the APPEND function.
• Variable section discusses scope.
• Function section discusses macros.
• New appendix that explains what's where in the official WEIDU readme.

 

 

[suy]

Thank you again for making this! My first hint of feedback: note that the code samples have the problem of "smart quotes" (“”), so they can't be pasted into the text editor verbatim, and work. Easy search and replace for me, but probably a problem for newbies.

[DavidW]

That's a pain: noted.

[argent77]

Nice work!

A note about character sets in regular expressions: The expression [%WNL%%LNL%%MNL%] can be shortened to [%WNL%], since %WNL% already contains characters defined by both %MNL% and %LNL%.

Another peculiarity involves the end-of-line character $. The symbol matches only Unix-style line breaks. To include support for the (more common) Windows-style line breaks, you have to add %MNL% as an optional match (e.g. "Minsc%MNL%?$").

I would also suggest to mention that syntax highlighting is available for a couple of text editors, since it greatly improves readability:
- Visual Studio Code: https://github.com/BGforgeNet/VScode-BGforge-MLS
- Notepad++: https://github.com/Argent77/NotePad_PlusPlus_WeiDU
- TextMate (macOS): https://github.com/critto-bg/textmate-weidu

[CamDawg]

5 minutes ago, argent77 said:

A note about character sets in regular expressions: The expression [%WNL%%LNL%%MNL%] can be shortened to [%WNL%], since %WNL% already contains characters defined by both %MNL% and %LNL%.

I know I'm the biggest offender on this, and I still do it even though I know better.

Also, I cannot endorse text highlighters enough. Between NI and the Notepad++ highlighters, @argent77's probably saved me a couple thousand headaches by now.

[DavidW]

How did I miss those highlighters? Good advice, will add.

[Daulmakan]

52 minutes ago, DavidW said:

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.

I noticed you use the weidu_external folder (and I think Cam does in IWDification too), but I'm not following the bolded part, could you elaborate further? Do you mean compressing and shipping your mod after you just uninstalled it after testing? 

Quote

most people learn it by reverse-engineering existing mods, which is a great way to learn the practice but also leads to confusion, and can leave you ignorant of large parts of WEIDU’s capabilities

Bullseye. Many thanks for the guide, will give it a look.

Edited June 7, 2022 by Daulmakan

[Graion Dilach]

If you use mymod/backup, you can't just copy and zip out your last tested mod install for release, but you also need to clean the backup folder first which is prone to human error.

Edited June 7, 2022 by Graion Dilach

[DavidW]

4 minutes ago, Daulmakan said:

I noticed you use the weidu_external folder (and I think Cam does in IWDification too), but I'm not following the bolded part, could you elaborate further?

I had in mind that if you ship your mod once it's installed, its backup folder will be full of cruft.

Actually the more serious reason to use weidu_external is for mods being installed on multiple different games: in development, you can have one copy of your mod that's linked through a virtual directory link to the game folders of many games, and not have the install structure on one game confuse another game.

[suy]

3 hours ago, suy said:

Thank you again for making this! My first hint of feedback: note that the code samples have the problem of "smart quotes" (“”), so they can't be pasted into the text editor verbatim, and work. Easy search and replace for me, but probably a problem for newbies.

A bit of an addenda on this: it also affects things like "COPY_EXISTING –". It's an EN DASH (U+2013) instead of HYPHEN-MINUS (U+002D). That is harder to notice visually.

[jastey]

With the needed ANSI -> utf8 text format transformation, it's not possible to just zip an installed mod (on the EE), anyway, regardless of backup folder. - Just a note that the external backup folder does not prevent a scrumbled mod package to be spread.

[CamDawg]

55 minutes ago, DavidW said:

I had in mind that if you ship your mod once it's installed, its backup folder will be full of cruft.

Actually the more serious reason to use weidu_external is for mods being installed on multiple different games: in development, you can have one copy of your mod that's linked through a virtual directory link to the game folders of many games, and not have the install structure on one game confuse another game.

This is an amazingly understated benefit.

I have 23 different IE game installs for Tweaks. I basically symlink the cdtweaks folder from one main development directory to each game--I can jump between testing on oBG to PsTEE to IWD2 without having to worry about whether I've carried over a backup folder from a different game.

Note that an external backup folder may not be enough on its own--if you're building assets on the fly then those need to be external as well. Tweaks' Random Friendly Drops, for example, uses the weidu_external folder to build dialogues and code for the specific IWD game.

[CamDawg]

1 minute ago, jastey said:

With the needed ANSI -> utf8 text format transformation, it's not possible to just zip an installed mod (on the EE), anyway, regardless of backup folder. - Just a note that the external backup folder does not prevent a scrumbled mod package to be spread.

AL|EN's proposed alternative method--which I'm slowly adopting as I update stuff--places the converted tra files outside of the mod folder, avoiding this issue as well.

Tweaks does this, but a simpler example is the recently-shipped SP Collection. I don't want to hijack David's thread with a semi-tutorial but the process is basically:

1. Ship all tra files as utf-8
2. On the originals, run the converter to turn them into ANSI/other charset as needed, setting the output somewhere in weidu_external
3. Set a variable with the path to the tra files--the original files (EE) or the output path from the converter (weidu_external/whatever) on the originals
4. Change your AUTO_TRA or any other place you're pointing to a tra file to use the path variable

 

[DavidW]

26 minutes ago, CamDawg said:

I have 23 different IE game installs for Tweaks. I basically symlink the cdtweaks folder from one main development directory to each game--I can jump between testing on oBG to PsTEE to IWD2 without having to worry about whether I've carried over a backup folder from a different game.

I hadn't realized you were a convert to external backup - I thought you did it that way in EEFP just to humor me.

If you are using it, my suggestion is to back up to weidu_external/backup/[my_mod], just to control clutter. But of course if you just create a modder-prefixed folder in weidu_external and do everything in there, everything will work fine.

26 minutes ago, CamDawg said:

Note that an external backup folder may not be enough on its own--if you're building assets on the fly then those need to be external as well. Tweaks' Random Friendly Drops, for example, uses the weidu_external folder to build dialogues and code for the specific IWD game.

The way I set up weidu_external, you should be able to do all of this in weidu_external/workspace - the assumption is you should only ever use that subfolder for fire-and-forget on-the-fly creation, so it doesn't need a modder prefix.

 

17 minutes ago, CamDawg said:

AL|EN's proposed alternative method--which I'm slowly adopting as I update stuff--places the converted tra files outside of the mod folder, avoiding this issue as well.

It's my method originally (since 2013) - see this thread. 

Originally it required a bit of hackery, because HANDLE_CHARSETS didn't support choosing a directory. Wisp added it in v247 to accommodate my encapsulation goal, and Alien did a very nice tutorial.

For the 'course in WEIDU' I was inclined to leave multiplatform installation out just on scope-management grounds, but that may have been a mistake.

 

[DavidW]

52 minutes ago, suy said:

A bit of an addenda on this: it also affects things like "COPY_EXISTING –". It's an EN DASH (U+2013) instead of HYPHEN-MINUS (U+002D). That is harder to notice visually.

OK, I think I've fixed this and the smart quotes.