Porting WeiDU Mods to Mac OS X

[CamDawg]

OK, after a lot of back-and-forth with the folks over at Balduran's Adventurin' Spa & Grille, the local Mac modders, we came up with a pretty good outline for porting WeiDU mods to Mac. Porting, for the most part, is a simple affair if you keep a few guidelines in mind while coding.

• Use / instead of \ in paths.
  In your tp2, / and \ are interchangeable for Windows. However, for Mac, paths using \ will cause an install failure.
   
   
  
• For regexps \ is fine and necessary.
  If you're using regexps, put big fat warnings everywhere not to use Mod Organizer--it's a little GUI app for Mac that calls WeiDU with the proper arguments and replaces any \ with / (in any TP2 in the BG 2 folder!), which is BAD for regexps.
   
   
  
• Don't use EXE installers.
  RAR and ZIP work fine.
   
   
  
• A setup-xyz.exe for Windows doesn't help much; use a copy of Mac WeiDU instead.
  The latest version can be found at the WeiDU page of the Spa and Grill. Do not use a file extension; Setup-xyz will be sufficient. Current version posted there is v155. Whatever you rename the executable, it'll need to match the file called in your .command file (see below).
   
   
  
• For distribution of OGG audio files, you need a little CLI tool called sox and a proper shell script.
  At the moment, I don't have further information on this.
  edit: Updated; see below.
   
   
  
• Tispack is available for OS X, but needs to be called differently
  BAT files do not execute on OS X, so while tispack is now available you'll need to call it with a shell script, as with OGG files.
  edit: Also see below.
   
   
  
• Be nice and include some Mac-specific install instructions.
  WeiDU mods do behave slightly differently on the Mac side. One of the most important differences is that Mac users can not extract a newer version of a mod over an oder, installed one. Unlike Windows, OS X will overwrite the entire contents of a folder rather than the specific files inside. The net effect is that the user will lose the contents of their backup folder. Also, include the bit about incomatibility with Mod Organizer if your mod uses REGEXPs with \. As an example, these are the Mac instructions for the G3 Tweak Pack:
  

Mac OS X

If the mod was previously installed, uninstall it before extracting the new version. Please note that this mod is incompatible with Mod Organizer. The G3 Tweak Pack is packaged and installed with WeiDU. To install, simply extract the contents of the mod into your BG2 folder.  If properly extracted, you should have a G3Tweaks folder, G3Tweaks.tp2, Setup-G3Tweaks, and Setup-G3Tweaks.command in your BG2 folder. To install, simply double-click Setup-G3Tweaks.command and follow the instructions on screen. Also, you'll receive a message informing you that WeiDU can not auto-update--don't worry, this is normal.

• Use VIEW instead of notepad to display a ReadMe at exit.
  VIEW, instead of a specific application name, will use the default viewer set by the system. This will allow your readme to be displayed.
   
   
  
• Use a .command file for double-click installations.
  For double-click installs, uninstalls, and re-installs for the Mac folks, use a .command file with a *nix-executable flag set. You can use the one below; simply copy the text and replace the ./Setup-G3Tweaks with the name of your executable. Generally, naming it in the scheme of your tp2 and WeiDU executable is a good idea, i.e. setup-xyz.command. Be sure to save the file with only Unix-style line breaks, i.e. LF. In ConTEXT, go to Tools > Convert text to... and select Unix (LF).
  

command_path=${0%/*}
cd "$command_path"
./Setup-G3Tweaks

 

As mentioned above, the biggest issues facing Mac ports are writing CLI equivalents for OGG and TIZ files, if your mod uses them.

 

For comments and discussion, please use this thread.

[CamDawg]

..and a follow-up to close out the last few odds and ends. I now have more information on using sox and tisunpack for Mac installs.

 

Sox and tisunpack

AKA what to do with those pesky ogg and tiz files

 

Converting ogg and tiz files is something typically handled by an external batch file for Windows installs using command-line programs. Since batch files will not execute on a Mac, we must use a shell script. Tispack and tisunpack do have OS X versions available, though we need to use a program called sox instead of the Windows-only oggdec.exe.

 

The first step is calling the shell script via tp2. This is one area where the tp2 will need to be different between the two versions. You can include everything you need and just comment out lines as appropriate. For example, for G3A:

 

// OS X version
AT_INTERACTIVE_EXIT      ~sh G3Anniversary/install.sh~ 
AT_INTERACTIVE_UNINSTALL ~sh G3Anniversary/uninstall.sh~

// Windows version  
// AT_INTERACTIVE_EXIT      ~G3Anniversary/install.bat~
// AT_INTERACTIVE_UNINSTALL ~G3Anniversary/uninstall.bat~

 

Depending on the version, I just comment out the appropriate lines. The install script itself is as such (slightly generalized from G3 Anniversary):

 

#!/bin/sh

tiz_files="g3g12b.tiz"
ogg_files="G3G12B01.ogg G3G12B02.ogg G3G12B03.ogg g3scamha.ogg"

for file in $tiz_files; do
 echo Converting $file
 G3Anniversary/tisunpack -s -f -o override/${file%.tiz}.tis G3Anniversary/tiz/$file
done

for file in $ogg_files; do
 echo Converting $file
 G3Anniversary/sox G3Anniversary/ogg/$file override/${file%.ogg}.wav
done

 

A shell script is simply a text file, however it must use Unix lie breaks (LF). If you're using ConTEXT, select Tools > Convert text to... > Unix (LF only).

 

The first line is known as a shebang line, and tells the OS what type of interpreter to use for the script. Do not change this line.

 

The next lines contain a list of tiz and ogg files that need to be decompressed into tis wav files, respectively. At first, it was believed we could use wildcards for the ogg files, such as G3*.ogg. However when using wildcards they get sent to sox on a single line, and it spits out errors since sox tries to interpret the additional file names as command-line arguments or flags for sox. Long story short--use individual filenames. I have not tested wildcards with tisunpack, though I suspect a similar issue may exist.

 

The next two blocks of code take the files from the two file lists and execute the decompression routines on them. You'll need to adjust them to the paths in your mod. In this case, sox and tisunpack are in the G3Anniversary folder, and ogg and tiz files are in subfolders named, oddly enough, ogg and tiz. For tisunpack, I have selected the -s flag (which makes it run without a lot of feedback, or 'silently'), -f (this forces an overwrite if the file already exists) and the -o file so that I can specify an output file.

 

Uninstalling

Clean up after yourself!

 

Since the tis and wav files are added by an external program, WeiDU does not know to uninstall them. Using an uninstall shell script will remove the files from the end-users machine and keep everyone happy. From the G3 Anniversary mod, yet again:

 

#!/bin/sh

del_files="G3G12B01.wav G3G12B02.wav G3G12B03.wav g3scamha.wav g3g12b.tis"

for file in $del_files; do
 rm override/$file
done

 

Looking familiar? Unlike the install script, the tis and wav files can be lumped into one group since they're just being deleted.

 

One last note on the command file

 

OS X adds a hidden file in folders that a user views, called .DS_Store. These files are more ur less irrelevant, unless you use a batch compile command in your mod. For example, G3 Anniversary uses

 

COMPILE ~G3Anniversary/compile~

 

to compile an entire directory of dialogue and script files. If the .DS_Store file is present, then WeiDU will try to compile it as well and kill the install since it's not a valid file. Fortunately, the DS_Store files can be remove without consequence, You delete the .DS_Store files via the .command file before executing WeiDU using this:

 

command_path=${0%/*}
cd "$command_path"
./Setup-G3Anniversary

ds=".DS_Store"
rem_ds="$ds G3Anniversary/compile/$ds"
for file in $rem_ds; do
if [ -e $file ]; then
 rm -f $file
fi
done

 

The rem_ds= line will contain paths to the directories you will batch compile; in this case the G3Anniversary/compile folder. Please note this is only necessary if you're batch compiling.

 

Thanks and credits

I would not have been able to sort all this out without the help of many folks. In particular, thanks to Scar/Armin, whose shell scripts are the basis for the ones above and who helped with finding and fixing errors; thanks to Loriel for helping us out with various coding issues here and there; thanks to the community in general at the Spa & Grill; thanks to Idobek for finding all sorts of bugs for me to worry about; and thanks to JPS for letting me send him test after test after test to get this right.

 

For example in action, check out the OS X version of the G3 Anniversary mod. It uses both tisunpack, sox, and the DS_Store removal tricks.

[CamDawg]

...and another follow-up on external scripts. the bigg has added some nifty functionality to WeiDU to make this process even less painless.

 

But first, a few quick maintenance notes: OS X versions of WeiDU are now available from weidu.org directly, instead of just at the Spa & Grill. In the original tutorial, the importqance of using / instead of \ in file paths is now more or less obsolete, as WeiDU will now treat \ in file paths as / for compatibility.

 

WeiDU sets a variable based on the architecture which you can use to detect Mac or Windows; this has been available since v175. However, we could never utilize it for AT_INTERACTIVE_EXIT since these were only evaluated if they were not wrapped in ACTION_IFs. This is not the case anymore:

 

ACTION_IF ("%WEIDU_OS%" STRING_COMPARE_CASE ~WIN32~ = 0) THEN BEGIN // if Windows
  AT_NOW       ~Kivan/audio-install.bat~
  AT_UNINSTALL ~Kivan/audio-uninstall.bat~
END ELSE BEGIN
  AT_NOW       ~Kivan/audio-install.sh~
  AT_UNINSTALL ~Kivan/audio-uninstall.sh~
END

 

We no longer need to comment out tp2 sections depending on whether or not we're on OS X or Windows, as WeiDU (starting with v190) will now execute AT_x commands wrapped in conditional ACTION_IFs.

 

Another groovy approach would be to completely let WeiDU handle uninstallation of your audio/tis files, thanks to the new AT_NOW command. AT_NOW executes your external script immediately, meaning you can decompress your audio during installation and have them available for bogstandard WeiDU COPY commands. Consider this plan of action:

• Place all ogg files in MyMod/ogg
  
• Run an external script to decompress the oggs into wavs in MyMod/wav
  
• Use standard WeiDU COPY command to move wavs into the override folder
  

(A discussion of pros and cons to this approach follow.) This can be done as follows, tp2 code first:

 

ACTION_IF NOT FILE_EXISTS ~MyMod/wav/sound1.wav~ THEN BEGIN
  ACTION_IF ("%WEIDU_OS%" STRING_COMPARE_CASE ~WIN32~ = 0) THEN BEGIN // if Windows
    AT_NOW       ~MyMod/audio-install.bat~
  END ELSE BEGIN
    AT_NOW       ~MyMod/audio-install.sh~
  END
END

COPY_LARGE ~MyMod/wav~ ~override~

 

where audio-install.bat is:

 

@echo off

"MyMod\oggdec.exe" "MyMod\ogg\*.ogg"
"mv MyMod\ogg\*.wav" "MyMod\wav\"

 

and audio-install.sh is

 

#!/bin/sh

ogg_files="*.ogg"

for file in $ogg_files; do
  echo Converting $file
  MyMod/sox MyMod/ogg/$file MyMod/wav/${file%.ogg}.wav
done

 

Basically the scripts check if the wavs are already compressed. If not, the external scripts are invoked and decompress your ogg files from MyMod/ogg to MyMod/wav. Whether they need decompression or not, they are moved from MyMod/wav to the override folder via a bogstandard WeiDU COPY. This can also be used with tiz > tis files as needed.

 

The advantages to this approach:

• Ogg files only need to be decompressed once. Ever.
  
• Uninstall is now handled by WeiDU completely--no uninstall scripts needed.
  
• You can now wildcard your decompressions scripts. (OK, you could before, but it would have been sloppy and lazy.)
  
• Reduced reliance on external scripts, resulting in less possible install flakiness
  

Disadvantages:

• More of the end-user's HDD space is used, as wav files are now stored in MyMod/wav, regardless of whether the mod is installed.
  
• Slight slowdown in install, as WeiDU now copies wav files. This may or may not be negated by not having to run decompression scripts.
  

If any shell scripters have suggestions for improving either the Windows or OS X scripts, I'd love to hear 'em.

 

As before, there's a thread created for comments, questions, and discussion.