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.
  
  
  
• 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.
  
  
  
• 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 attached below; simply open it 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.
  

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 visit the thread at The Gibberlings Three.

[SimDing0™]

• Don't use EXE installers.
  RAR and ZIP work fine.

Unless I misunderstood, I was informed that SFX archives were okay.

[CamDawg]

A non-SFX archive is preferable simply because it is slightly smaller. SFX's are OK, though. We've actually been informed that RAR (or an SFX RAR) is preferable to a ZIP.

[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:

Code: [Select]

// 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):

Code: [Select]

#!/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:

Code: [Select]

#!/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

Code: [Select]

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. Fortunatle, the DS_Store files can be remove without consequence, You delete the .DS_Store files via the .command file before executing WeiDU using this:

Code: [Select]

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.