Treeki's New Super Mario Bros Documentation


  1. File Structure
  2. Level Format
  3. Level Format - Block 6 (Entrances/Exits)
  4. Level Format - Block 7 (Enemies/Sprites)
  5. Level Format - Block 8 (Views)
  6. TSA/Map16 Format (BG_pnl files)
  7. Object Format (BG_unt files)

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.



Back to top

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


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.

Back to top

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 ** ** ** ** **

Known Movement/Animation Types

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

Back to top

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


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.

Back to top

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 ** ** ** ** ** ** ** **

Back to top

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!]

Back to top

Object Format (BG_unt files)

Coming soon.

Back to top