Treeki's New Super Mario Bros Documentation

File Structure

NSMB uses the NitroROM file system to store its data, like pretty much all DS games. While I won't go into depth about it in this document, I will describe the parts of it specific to NSMB.

Warning: Unlike most games, NSMB's code is rather sensitive! If the file IDs are changed, the game will not work, since it seems to refer to files by IDs rather than names. This means that tools like NDSTool/DSLazy will not work to edit the ROM, since they rebuild the file system. NDSTS works fine, but it can only replace files that are the same size as the original. My own tool Nitro Explorer can replace any size file, so it is recommended for hacking NSMB.

File Hierarchy

I'm not covering all the folders in complete detail. See later in this document for more info about some of them.

Files:

00DUMMY
This file seems to be a dummy file. It is 0 bytes.
BUILDTIME
This file seems to contain the date for the final build of NSMB: UROM2006-03-29 09:48:19nitro-mj - Rather interesting that it was built on the 29th March but released in May 3 months later, right?
mgvs_sound_data.sdat
Contains music and sounds for the multiplayer minigames imported from Super Mario 64 DS.
sound_data.sdat
Contains music and sounds for the main NSMB game.

Folders:

ARCHIVE
Contains NARC files with all the minigames, plus other things. It's rather hard to explain every single thing (especially as for a lot of them, I haven't identified the use) but I will try.
Dat_2D.narc, Dat_enemy.narc, Dat_Init.narc:
These archives contain files needed for Download Play in the Mario vs. Luigi mode.
Dat_Basement.narc, Dat_Field.narc, Dat_Fort.narc, Dat_Ice.narc, Dat_Pipe.narc:
These archives contain the data needed for each specific multiplayer level.
ARC0.narc:
Unknown. I seriously don't see what this file is for..
Everything else:
All the other files here are NARC files which contain the SM64DS minigames and a few other multiplayer things.
BG_chk
Contains a lot of .bin files named [TilesetName]MainUnitChangeData.bin. There seems to be one for each tileset. I don't understand the purpose of them.. They're obviously not LZ compressed, as they're all 3072 bytes. It also contains a few for tilesets which aren't in the actual game (like Sunset and Wood) and ScrollControl files which I don't see the use of.
BG_ncg
Contains most of the level graphics. Everything is LZ77 compressed, and 8bpp linear. Once uncompressed, they can be read in Tile Molester using 4bpp linear, reverse-order.
d_2d_A_J_jyotyu_ncg.bin:
Tileset for stuff that needs to be in every level - question/brick blocks, flagpoles, etc. Rather interestingly, the varying palettes in overworld/underground levels are done just by changing the palette used - they all use the same graphics file.
d_2d_..._back_..._ncg.bin:
Tileset for backgrounds. Backgrounds are a total pain to edit since they're stored as tilemaps, not plain bitmaps.
d_2d_..._free_..._ncg.bin:
For multi-layered backgrounds (which is most - for example, the hills in 1-1 that scroll at a different speeds), these store the tileset for the top layer.
d_2d_..._tikei_..._ncg.bin:
Tileset for level objects. The most useful part, undoubtedly.
d_2d_TEN_..._ncg.bin:
These are animated tiles.
BG_nsc
Contains tilemaps in files matching the names of the backgrounds in the BG_ncg folder. They are all LZ77 compressed. Note that they do not exactly match - a few backgrounds (the "mame" bonus set, most noticeably) have multiple tilemaps which use the same tileset.
None of them exist for tilesets, except for one - d_2d_I_M_tikei_demo_castle_nsc.bin. This file is used for the short cutscene at the start of the game when a new file is created.
This page on the Tahaxan website describes the format: http://tahaxan.arcnor.com/index.php?option=com_content&task=view&id=33&Itemid=36
BG_pnl
These files all contain data similar to the TSA files in NES games. Basically, they take 8x8 tiles from the tilesets and assemble them into more manageable 16x16 blocks. Note that the level format does not work with these directly, either. Each file corresponds to one tileset.
The format is described later in this document.
BG_unt
This format had me stumped for ages (and still does). I still don't know the use for everything here. Basically, it describes how the game translates objects into sets of 16x16 blocks (as described in the files in BG_pnl).
The format is described later in this document.
course
Level files. Here's how they work:
A01_1.bin:
Main level data file. Split up into 14 blocks inside the file; this format is described later in the document.
A01_1_bgdat.bin:
Object layout file. This format is also described later in the document.
Naming Scheme:
The first letter (from A to J) defines the world. However, this is not entirely specific - I (world 9) contains the mushroom houses. J (world 10) contains 10 levels: the first 5 are the multiplayer levels; the last 5 are the NSMB lost levels I discovered a while ago. Take that, all the people who commented on my youtube videos screaming they're fakes. :P
The first number defines the level number, but be aware that these are not exactly equal to 1-1, 1-2, 1-3, etc - since castles, towers, and other levels with no numbers must be accounted for.
The second number defines the area number. Each level has multiple areas, although I'm not sure if there's a way to change the number of areas (or if it's even possible).
As an example for the area system: A01_1.bin is the main level for 1-1. A01_2.bin and A01_3.bin are the bonus areas, and A02_1.bin would be the main level for 1-2.
demo
This entire folder contains stuff related to the NSMB ending. The most interesting part is probably the staffroll####.enpg files! These all store the screenshots of levels which are seen during the ending.
To read one: Decompress it as LZ77. Open it in Tile Molester. Set the block size to 32x24, codec to 8bpp linear, and mode to 2-dimensional. To load the palette, go to Palette => Import From => This File. Enter offset 65536, size 256, format 15bpp.
ending
This folder contains two graphics files in tilemap folder. The UI_credit_....bin file contains the "The End" screen with the Luigi code; the UI_koopa_....bin file doesn't seem to have anything useful in it.
enemy
Everything 3D is here. Don't ask me, I have no idea how it works.
ipl
Graphics and palette file (4bpp as usual) for the icon used on the DS menu.
map
3D models for the world maps.
obj
Graphics and palettes for lots of stuff. If you're looking for something, you're sure it's 2D, and it's not a tileset/background or in uiStudio it's most likely somewhere here. That's literally the only thing in common with the files here - they vary between as much as goombas/koopas, to switches, to messages!
particle
I have no idea what this folder is for. I'm suspecting the spl_b##_....spa files have something to do with the bosses, since the short names and the numbers make sense.
player
Seems to contain 3D models for Mario/Luigi.
polygon_unit
Lots of 3D texture files. No idea as to their use.
script
Text for the game in the standard BMG format so many DS games use.
uiStudio
Pretty much everything you ever see on the touchscreen is inside here in some form, plus a few misc UI things. The in-game bottom screen stuff, the minimaps, main menu, etc.

Level Format

NSMB's level format is a little confusing, but quite flexible. It's also split into two files. I'll cover the bgdat file first, since it's simpler, then I'll move on to the main level file.

BGDat Files

The bgdat files (See the course folder in the File Structure section) store every static object in the level. They're quite easy to edit.

To read a bgdat file, just keep reading objects until you reach a tile type of FF FF. Note that the FF FF object doesn't have an accompanying X, Y, width, or height, so watch out for that!

Object Format

OT OT XX XX YY YY WW WW HH HH

OT: Object type (unsigned short)
You may wish to store the object type in a different way, if you create an editor or other tool that makes use of this.
The lower 12 bits of the object type decide which object will be loaded. The higher 4 bits decide which tileset will be used: 0 = generic (named Jyotyu in the tileset files), 1 = level-specific, 2 = special case.
Tileset type 2 only seems to be used in overworld levels. If you look at the BG_chk folder, you'll notice all the tileset ChangeData files (use unknown) are described as MainUnit, except for one which is NoharaSubUnitChangeData.bin. This file matches together with d_2d_I_S_tikei_nohara_ncg.bin in the BG_ncg folder. I'm not sure if this tileset is loaded outside the overworld levels (which use the Nohara tileset), but it only contains two things: the stone walls (seen in cannon levels) and the end-of-level castle.
X: X position in 16x16 tiles (unsigned short)
Y: X position in 16x16 tiles (unsigned short)
W: Object width in 16x16 tiles (unsigned short)
H: Object height in 16x16 tiles (unsigned short)

Main Level File

Inside each level file, there are 14 blocks. The header of the file describes the offset and size of each block. Not all blocks may have data in, and I haven't identified the purpose of every block.

The format is simple enough: The offset and size for each block are at the start of the file, stored as unsigned ints. After the offset and size for the 14 blocks, the data for each block will be there.

I haven't figured out what most of the blocks do, but here are documentation on some. Note that I am using 1-based indexes for block numbers, so if you are coding an editor or other tool and using 0-based indexes for block numbers, you should subtract 1 from mine.

Level Format - Block 6 (Entrances/Exits)

Block 6 is simple - it's basically a continuous string of entrance/exit structures. While the two structures are similar (and treated the same way by the game, I believe) I have listed them separately here for clarity. I had the entire entrances/exits section done and Notepad++ crashed and ate it. :(

Entrance Format

XX XX YY YY ** ** ** EN DA ** ** ** DE ** ET ** ** ** ** **

Exit Format

XX XX YY YY ** ** ** EN 00 ** ** ** 00 ** ET ** ** ** ** **

X: X position in pixels (unsigned short)
Y: Y position in pixels (unsigned short)
EN: Entrance number - My old documentation says "Don't change this, or the game may misbehave", but I'm not sure how accurate that is. Or knowing me, this might not even be the proper use of that byte.
DA: Exit only; 00 for entrances Destination area. Each level has multiple areas (See the section for the course folder under File Structure), this byte defines which area you will be sent to when going through this exit. You can go to another entrance in the same area by entering the number of the current area.
DE: Exit only; 00 for entrances Destination entrance. After entering this exit, you will be sent to the entrance listed in this byte.
ET: Movement/animation type. This allows you to create different types of entrances/exits. See below for a list. While each type should work for entrances and exits, I have only tested them on entrances, so try them before you use them on exits.
**: The purpose of these bytes are unknown; any information would be appreciated. I suspect one of them might have something to do with views, but I don't really know :/

Known Movement/Animation Types

This is a possibly incomplete list of all the types I could find.

0, 1, 7, 11-15 = Normal
2 = Door
3-6 = Pipes, facing: 3 = up; 4 = down; 5 = left; 6 = right
8 = Ground pound
9 = Ground pound (No dust)
10 = Normal (with swimming pose?)
16-19 = Mini pipes, facing: 16 = up; 17 = down; 18 = left; 19 = right
20 = Jump out (Like in World 8's vertical volcano level)
21 = Climbing vine
22 = Glitch mode. From my old documentation:
really weird movement mode, possibly used for debug testing? starts at very right of level. pressing left/right lets you accelerate the camera moving (and Mario display on the bottom screen) but it never slows down. pressing Down stops it, but you can only start moving again after pressing up.
23-26 = Same as 22, but starts at the very left of the level. I didn't test any more after 26.

Level Format - Block 7 (Enemies/Sprites)

To read block 7, just keep reading objects until you reach the end. After the last object, you'll see FFFF FFFF.

Sprite Format

ET ET XX XX YY YY AD AD AD AD AD AD

ET: Enemy type (unsigned short)
X: X position in pixels (unsigned short)
Y: Y position in pixels (unsigned short)
AD: Additional data (6 bytes)
This data is not used for every object. Some just ignore it - but it always must be included, even if it's only zeroes. Others use it for data or settings that change how the object works. The only object I know about the data for is Koopa Troopa/Paratroopa - 4th byte can set the colour. 0 = green; 1 = red; 2+ = blue. Thanks to Tanks for the discovery of Koopa colours.

Not all the enemy types are known. Some enemy types don't work in all levels - I have no idea why; I'm sure there has to be some control byte for this somewhere in the level format.

Level Format - Block 8 (Views)

Views are rather confusing, and also the one area I've done least research into. Anyway, this is what I know! Similar to entrances/exits, the format is simply a continuous string of view structures.

View Format

XX XX YY YY WW WW HH HH ** ** ** ** ** ** ** **

X: X position in pixels (unsigned short)
Y: Y position in pixels (unsigned short)
W: View width in pixels (unsigned short)
H: View height in pixels (unsigned short)
**: The purpose of these bytes are unknown; any information would be appreciated.

TSA/Map16 Format (BG_pnl files)

The TSA/map16 format is a pain to work with, but it's needed if you want to render levels or edit objects. [Incomplete!]

Object Format (BG_unt files)

Coming soon.