Building a Level Viewer for The Legend Of Zelda - Twilight Princess

This project is definitely one of the most advanced of mine. I started programming a web BMD viewer for Twilight Princess (Nintendo GameCube) because I love this game and as a game producer, I am fascinated by analyzing levels and immersing myself in the details of how they were made. This project is a way for me to explore that passion and gain a deeper understanding of the game I love. It's a challenging and rewarding learning experience. I am excited to see where this project will take me and what new discoveries I will make along the way. Until now this project took me months and months of research. Research that is based on the work of more than 20 other people who investigated and shared their knowledge and findings about rarc, bmd, gcm yaz0, j3d, tev etc. I came across some person that I wrote down to give them Credit:

Thanks goes out to: ("LordNed", "thakis", "Jasper St. Pierre", "Kiwi", "Dolphin Emulator Team", "Gamma", "Zan") - for their pioneering efforts!

Water, Fog, animated Textures are features currently on the roadmap

Demonstration

The program was programmed using three.js and webGL. It runs at a constant 60fps in the chrome browser. Unfortunately I can not share the interactive Viewer (models, rooms etc.) with you, cause I don't want to see how far the limits for fair use of research are. Enjoy my montage:

https://api.fenixfox-studios.com/assets/d43523dd-5cbe-4da4-9c7d-2d275690050a

Specifications

BMD and BDL are the file formats used by Nintendo for storing model data in its GameCube and Wii games. They are part of Nintendo's J3DGraph library, which is a component of the larger JSYSTEM toolkit. BMD first appeared in the game Luigi's Mansion. It was then the only model format used in Super Mario Sunshine. The Wind Waker further introduced the BDL format, which is an extension of BMD with an additional section for material FIFO instructions called MDL3. MDL3 is used to improve rendering efficiency. Super Mario Galaxy 2 was the last game to use this model format.

JSYSTEM is a proprietary game development toolkit used by Nintendo to create games for its consoles. It includes various libraries and tools for tasks such as 3D modeling, animation, and physics. J3DGraph is a library within JSYSTEM that provides functions for handling 3D graphics and is responsible for the BMD and BDL file formats. BMD stands for Binary MoDel and BDL stands for Binary Display List.

The JSYSTEM toolkit was discovered by reverse engineers and game modders in the early 2000s, when they began to analyze and decompile the code of Nintendo GameCube and Wii games. They found that many of the games shared similar code structures and libraries, which led them to suspect the existence of a common development toolkit. After much research and experimentation, they were able to identify and extract the JSYSTEM libraries from the games, and began to document and reverse-engineer its various components, including the J3DGraph library and the BMD and BDL file formats.

As the understanding of JSYSTEM grew, modders began to develop their own tools for working with the JSYSTEM format and started to create their own custom models, textures and even create new games using the JSYSTEM libraries. This led to the creation of a vibrant modding community that continues to exist today, with many modders sharing their findings and tools online.

Development

In the beginning, I wasn't really interested in the actual *.dol or *.gcm container formats because other people had already done a great job providing ready-to-use tools (created gcm reader later myself). After a bit of searching, I found folders that looked like they might contain some interesting stuff, like rooms and other elements. Large areas, such as Faron Woods, were divided into chunks and saved into separate files, which would later be merged to form the complete area.

But I wanted to start easy. Maybe something simple! After unpacking most of the stuff in the folder, I sorted the files by size and found a super simple object. When I checked the file in HexWorkshop, I stumbled upon markers like VTX, INF, DRW, and SHP. From the vertex positions, I could tell it was a flat box with a simple door knob. I soon realized it was the door from the lake bed temple.

I knew what the object might look like, and I knew where to look for the basic information like vertex coordinates as well as texture information.

BMD-Format Documentation

You have to be careful since some of the information are simply incorrect for your case. Certain attributes were just different from what those docs are telling. But having a format sheet like that is all you need in order to extract a 3d model and its texture!

After my successful attempt to extract at least on simple object, I thought that it would be time to dig further and tackle a complete area! Armed with the same algorithm that I just wrote I picked the file named R00_00. I was hoping that it would be Ordon Village or Faron Woods. But that didn't matter cause all I got was a pile of garbage. Clearly a case of wrong vertex order. Can you tell by looking at this image what room it is?

Shape by shape, I slowly tested the waters. Here and there, cliffs and gravestones started to appear. It became clear that I was looking at the Kakariko Graveyard area.

After quite some time, I was able to produce this result: certain objects were missing, some faces were inverted, and not a single texture seemed to be correctly applied.

The solution was somewhat confusing. Although certain shapes had specific material indices defined, they didn't have a straightforward 1:1 relationship. Instead, you had to look at the Scene Hierarchy defined in the INF section of the BMD file. This hierarchy consisted of a tree of nodes that could represent either a shape or a material. Typically, the hierarchy would start with a material, followed by some shapes. For example, you might see something like (mat1, shp2, shp5, shp6, mat2, shp1, shp12...). In this case, shapes 2, 5, and 6 would all use material 1, and so on.

Well, great, but everyone who ever played that game might notice that materials are looking off. Colors are off, there is no blending between the materials, and it looks quite dark in general. At this point, I would have dived into the most mind-blowing part of all this. The GameCube uses TEV stages, or Texture Environment stages, to handle these tasks. TEV stages are responsible for blending textures, managing colors, and applying transparency effects. Note the fact that GameCube did not really support transparency effects like we know them today with two render passes and faraway objects rendered first. There are some GitHub repos, some articles, some forum threads. Get your hands on as much information as you can!

One more important part that I needed to add were the atmospheric effects like fog, bloom, and clouds. Until this point in time I'm couldn't successfully create the fog and bloom effects, but I found the cloud shadow and put them in a blending TEV Stage. I'm still looking for the correct UV coordinates for the clouds.

The final result of that room would like this: (It took quite some time to come this far actually)

Conclusion

This project has been an incredible journey. Spending my time on figuring out how smart people solved technical limitation of the past helped me appreciate the complex beauty of Twilight Princess. I've made good progress, but there is still a huuge list of things to explore and implement. I plan to keep working on this viewer, adding features like fog, BTK (Texture Animation), and other atmospheric effects to make it as accurate and immersive as possible.