Research: Map Matrix Files [Gen. IV]

[esperance]

Matrix Files

Introduction

So matrix files contain data that is really important to the Gen. IV games, and I don't think that a lot of information has been reported on them (a quick Google search reveals limited information). Essentially, matrix files are used to layout how games should be situated in the game world and connect to each other (this makes editing connections between maps much easier than in previous generations). In addition, matrix files are used by the game to figure out which headers go with which maps. The most common matrix you'll encounter is the main overworld one: in Diamond/Pearl it lays out how every outside map connects in Sinnoh. But every matrix file has a purpose, most of them used by indoor locations to create connections and set the headers.

Location of the Data

Like a lot of data in the DS games, the matrix data files are stored within a NARC file within the ROM.
Here are the locations of said files:

Diamond/Pearl/Platinum: root/fielddata/mapmatrix/map_matrix.narc
HeartGold/SoulSilver: root/a/0/4/1

The Format

The format for the matrix files can actually be a little complex, because the format changes depending on a few flags. A matrix can have up to three layers of data, depending on whether these flags have been set. Each matrix has at least one layer.

• 1 byte: Width of the matrix
• 1 byte: Height of the matrix
• 1 byte: Layer 2 flag (if equal to 1, there is a second layer -- otherwise 0)
• 1 byte: Layer 3 flag (if == 1, second layer, otherwise 0)
• 1 byte: Length of the name
• N bytes: Name in UTF-8 characters (length is equal to previous byte)

From there the, the data itself follows. Each layer is a 2D array, arranged by rows. The first layer, which is in every matrix, is made up of a 16-bit unsigned integers. The second layer, given the flag was set, is made up of bytes. The third layer, given the flag was set, is made up of 16-bit unsigned integers.

Meaning of the Data

In a three layer matrix, the first layer describes header numbers and the third layer will describe associated map files. Values of 0xFFFF are considered null. I'm not exactly sure how the second layer is used. This format is used by the overworld.

In a matrix where the third layer is not present, the first layer describes map files. Once again values of 0xFFFF are considered null. By determining the header that uses the matrix, the map and header can be linked. This format is used by most indoor maps.

I hope this helps! :)

 

[esperance]

I don't know if you have already, but recently SDSME went open-source. Perhaps you can take a peek at the source code and find out how it handles the Map Matrix data. It's 2:30 AM so I don't have time to peel through the source, but if you want, here's a link to the github repository.

Edit: Peek at the Matrix Editor region of Form1 Main Window.cs:
https://github.com/Spiky-EaredPichu/SDSME/blob/master/Source/Map_Editor/Form1 Main Window.cs#L6745

Frankly the way that Spiky handles matrixes is a bit poorly done. That's why I posted this.

Here's my own matrix loader:
https://github.com/lost-heart/DS-Map/blob/master/DSHL/Formats/Pok%C3%A9mon/Matrix.cs#L22