Preparing and Running Previewer on Retail Hardware (+ Tutorial)

After my research in getting previewer running on my iBook, I found that the models from A Wonderful Life could only be viewed on HW2 systems (retail hardware or equivalent dev kits).

Through some more research, I am now able to compile a version of previewer to run on retail hardware.

Here’s how I did it…

1. Create a folder to serve as the dvd root, in this case I used C:\defroot. This folder will contain the files to be previewed in a folder called “preview”, including the required prevload.txt file.

2. Convert the HW2 version of previewer.elf to .dol format using makedol.

3. Create a new file in Notepad the following settings and save as
previewerD.ddf.

4. Use the NPDP program OdemMakeDlf to compile our ddf file into a dlf file.

5. Download a retail-patched version of makegcm.dll and put the appropriate SDK folder C:\DolphinSDK1.0\X86\bin, overwriting the original makegcm.dll file.

6. Run makegcm.exe to compile the dlf file to a functional gcm (gamecube disc image).


The resulting gcm file can run on a retail Gamecube, or be opened in the Dolphin fan emulator.

Zebra, now on Gamecube

I haven’t tried out any of the AWL files yet, but that will be the next step.

Overall, I’m leaps and bounds beyond where I was just a couple months ago.


Update

I’ve tried using the above method to preview some gpl files from A Wonderful Life. Unfortunately, the program freezes on a black screen immediately after the Gamecube logo.

I’m not sure what the error is since the retail method of loading doesn’t provide any output. To get that, I’d need to be using a development system (e.g. GDEV, TDEV) that could be hooked up to a PC for console output.

The alternative would be to try using an entirely different piece of software, dspin.

This software (I have version 0.94) allegedly has experimental gpl import support.

I’ll do some tests with this software tomorrow to see if I can get anywhere.

If dspin doesn’t work, I’ll just have to shift focus back to dialogue editing until a workaround can be found, such as a more updated previewer for Mac (i.e. newer than the version included with the April 2001 Character Pipeline).


Update II:

dspin didn’t seem to work. I renamed the file and put it in the dvdroot folder, but the program didn’t seem to do anything with it.

I’m not sure what I’m doing wrong. Further research needed.

GPL Model Trial and Error and Error and Error

I tried running some of the .gpl files from A Wonderful Life through the previewer program on my iBook.

I attempted to load farm.gpl, since it’s texture configuration is one of the simplest (one tpl + one gpl) amongst the AWL gpl models.

Unfortunately, all of the gpl files from AWL caused a version-mismatch error and I’m not well-versed enough to recompile the program for mac at this point.

Error when attempting to load gpl files from AWL.
Occurs on both SheepShaver and iBook.

Fortunately, after examining the gpl files, I was able to find that the version number can actually be changed in a hex editor by setting the view options to display as decimal, group by double words, and use a big endian byte order. In this case, the version of the gpl was 6012001. I changed the version field to what previewerD requires (version 12012000), and reran previewer.

Changing the gpl library version from 6012001 to 12012000.

This allows the file to open, but leads to a new error:


GXSetVtxAttrFmt(): Only valid scale for 8b pos or texcoord data is 0 on HW1 in “GXGeoVert.c” on line 263.
Occurs on both SheepShaver and iBook.

This is likely due to the gpl being initially exported for HW2 (retail Gamecube) which uses an updated graphics driver compared to HW1 (initial dev kits). Since the mac version of previewer appears to be built on the HW1 code, it leads to the error above.

It might be possible to get around this error by running the HW2 version of previewer.elf via Dolphin (fan emulator) or Swiss (Gamecube homebrew loader), but it would take some time to figure out the proper configuration. Further research will be needed.


I also attempted to load a more complex 3d model (boy_0.gpl, extracted from boy_0.arc). This file has multiple textures associated with it (boy_0_b0.tpl, boy_0_f0_e.tpl, and boy_0_f0_m.tpl).

Unfortunately it seems that the gpl is improperly configured. When loaded through previewer on iBook, it looks for a single nonexistent boy_0.tpl texture.

It’s worth noting that the files from this version of boy_0.arc aren’t actually used in-game (the actual models/textures are loaded from one of the clz archives). These are likely leftovers from some point in the games development.

For now, I’ll be sticking to research on the simpler models first (e.g. farm.gpl, grass.gpl, and various fish models) to see if I can get past the HW1/HW2 limitations.


I also attempted to change encoding of farm.gpl from big to little endian (grouped by double-words).

I ran it through my Windows version of previewerD.exe (recompiled with version-check removed). However, I got a new “component count” error.

This is likely due to some sort of error when I attempted to convert the file’s endianness. Further research will be needed.

Decompiling the Game

Good news!

Avast has released the source code for their Retargetable Decompiler (RetDec for short).

Why am I excited about this?

Because can decompile PowerPC binaries (i.e. elf files) into a programming language (C or Python).

The main executable program in any Gamecube/Wii game is a Start.dol file, which is a variant of the elf format.  Also, the GC/Wii are both based on the PowerPC architecture.

Most decompilers will only break a game down into what’s called Assembly.  This is a type of machine code that is difficult at best to reverse-engineer.  And those that support recompiling to other programming languages typically only support the x86 architecture.

Previously, one could try RetDec online, but it had a very small limit on decompilation time (which was not enough for a file as large as the game’s main program code).  But now, I can run it on my own machine for as long as needed to run the decompilation process.

I’ve been able to successfully install RetDec and it’s dependencies.  I was then able to convert AWL’s Start.dol file into a Start.elf file using DolTool 0.3 and begin the decompilation process.

Unfortunately the decompilation failed part-way through due to not having enough memory (my laptop only has 4GB RAM).  My roommate offered to let me try on his laptop (which has 8GB), so once I’m able to try on that, I’ll post an update.

From the partial decompilation, I can tell that I’m on the right track though.  I’ve been able to find a few lines in the LLVM code that reference CLZ files and could be the key to their decompression algorithm.

@global_var_80298180.828 = constant [22 x i8] c”mainchapter%d.arc.clz\00″

%v4_800131f8 = call i32 @function_80238268(i32 %v2_800131f0, i32 ptrtoint ([22 x i8]* @global_var_80298180.828 to i32), i32 %v0_800131e8)

It appears that the clz file is passed through to a variable, which is them passed through some sort of function (possibly to be decompressed).

I’ll be analyzing this code as much as I can to try and figure out how the files work.

On a separate note, decompiling the game’s primary source code could create a better understanding of the game overall and could open the door for additional future mods from other authors..


Update

I tried running the decompilation on my roommate’s 8GM RAM machine, but it still failed after running out of memory (though at a later point).

But on the bright side, I was eventually able to get the decompilation to work by turning off code optimizations with the –backend-no-opts flag in retdec.

The main downside to this is that the code is much larger and complicated than it would be if I had been able to run the optimizations.

function_80238268(v105, (int32_t)“mainchapter%d.arc.clz”, v35);

At least it’s somewhat easier to follow now than the partially-decompiled LLVM code obtained previously.


If anyone has a machine with higher memory (e.g. 32GB) you could try running RetDec to decompile the binary yourself.  I’ve made a downloadable [folder] with all of the needed files, including an installation guide to get everything set up.

[Please PM me if you’d be able to help out with this]


For anyone else that feels like helping out, I’ve uploaded the decompiled source code [link].

The code is unfortunately fairly large and unoptimized.

I have versions written in both C and Python.

Please feel free to take a look and see if you can find any useful information.