MDAT

The MDAT file's primary role is to describe:

• 3D Geometry: Includes the spatial structure of levels, such as terrain, platforms, and other environmental elements.
• UV Mapping: Specifies how textures are applied to the surfaces of the 3D models.
• Vertex Colors: Adds color shading to vertices, often used for lighting effects.
• Face Types: Defines triangles or quads to construct the 3D geometry.

Extraction

The MDAT extraction script is a Python tool designed to export 3D geometry and related data from MDAT files found within DAT files of Tomba! 2: The Evil Swine Return. Here's an overview of its purpose, structure, and how it processes the MDAT data:

Purpose

• The MDAT file contains level geometry data such as:
  • UV coordinates (for texturing).
  • Vertex colors (for per-vertex shading).
  • 3D geometry (constructed from quads and triangles).
  • Headers and metadata for the structure.
• This script extracts that data, interprets it, and exports it into a usable format:
  • OBJ (Wavefront Object) format for geometry.
  • MTL (Material Template Library) format for materials and textures.

Key Features

1. Reads Geometry Data:
   • Processes triangles and quads to extract 3D positions, UVs, and vertex colors.
   • Differentiates between transparent and opaque faces.
2. Handles Textures:
   • Extracts texture data and maps it using the CLUT (Color Look-Up Table) and VRAM.
   • Saves textures as PNG files for use in 3D rendering.
3. Generates Standard 3D Formats:
   • Outputs geometry in the OBJ format, widely supported by 3D modeling tools.
   • Creates accompanying MTL files for material definitions and texture mapping.
4. Modular Design:
   • Functions like printTriangle, printQuad, and createTex handle specific tasks, making the script adaptable and extendable.

Script Breakdown

Initialization

• Imports necessary modules like os, struct, and PIL (Python Imaging Library) for file I/O and image handling.
• Defines constants for geometry types (triangles, quads) and initializes tracking variables.

Data Extraction Utilities

• short and char: Read 16-bit and 8-bit values from the binary file.
• vtx_col: Computes normalized vertex color values from binary data.
• getClutCoords and clutCoords2Address: Convert CLUT values to usable VRAM addresses for texture mapping.

Geometry Processing

• Triangles (printTriangle):
  • Extracts three vertices with positions, vertex colors, and UV coordinates.
  • Handles edge cases where UV coordinates are identical and adjusts them slightly.
  • Outputs triangle data in OBJ format, along with material assignment.
• Quads (printQuad):
  • Similar to triangles but processes four vertices.

Texture Handling

• makePalette:
  • Extracts a color palette from the CLUT, interpreting the 16-bit PS1 color format.
• getTex:
  • Generates a texture image based on the palette and pixel data from VRAM.
  • Saves the texture as a PNG in the specified directory.
• createTex:
  • Ensures textures are created only once for unique combinations of texture page and CLUT address.

Exporting Files

• Writes the OBJ file with vertices (v), UVs (vt), and faces (f).
• Generates an MTL file linking the textures to their corresponding materials.
• Saves textures in a folder hierarchy under tex/<name>.

---

MDAT File Overview

An MDAT file encapsulates:

1. Header: Defines the dimensions of the data (number of triangles, quads, etc.).
2. Geometry:
   • Includes vertex positions, UV coordinates, and vertex colors.
   • Can have both triangles and quads.
3. Textures:
   • UV mappings reference texture pages in VRAM.
   • Colors are resolved through a CLUT.

---

How the Script Works

1. Setup:
   • Takes input parameters like file paths, addresses, and IDs.
   • Creates necessary directories for output.
2. Data Extraction:
   • Reads MDAT geometry and texture data from the DAT file using offsets and pointers.
3. Processing:
   • Interprets binary data into vertices, faces, and materials.
   • Handles transparent and opaque geometry separately.
4. Export:
   • Writes the extracted geometry to an OBJ file.
   • Saves textures as PNGs and references them in the MTL file.

Example Output

OBJ File (example.obj)

v 1.0 2.0 3.0 1.0 2.0 3.0 
v 4.0 5.0 6.0 1.0 2.0 3.0 
v 7.0 8.0 9.0 1.0 2.0 3.0 
usemtl 0-1234ABCD 
f 1/1 2/2 3/3

MTL File (example.mtl)

newmtl 0-1234ABCD 
Ka 1 1 1 
Kd 1 1 1 
map_Kd tex/example/0-1234ABCD.png 
Ks 1 1 1 
Ns 50 
illum 7

Texture (example.png)

A 256x256 PNG image representing the texture page.