Mario 64 Level Importer v16 (download and documentation)

This tool replaces Super Mario 64 levels with external Wavefront .OBJ 3D models and also lets you control
many aspects of the game. It works with the "Super Mario 64 (U)" ROM, and coupled with Toad's Tool 64
should enable you to create a full hack of  Mario 64 with minimal technical knowledge.

Here is a list of the currently supported features:

- Replace any of the original levels
- Select Object Banks available in the level 
- Choose “weather” effects (lava, snow, etc) 
- Set global terrain type (slide, sand, snow) 
- Use Custom Background image 
- Set Fog effects 
- Set Camera Presets
- Map textures to specific collision types 
- Set multiple Water/Toxic Haze/Mist boxes (still a big buggy) 
- Alpha support
- Change hard-coded star positions (Bosses)
- Change hard-coded trajectories (Moving Platforms, Koopa-the-Quick, etc)
- Change act selector settings
- Custom Music tools: insertion, extraction, changing instruments sets 
- Numerous other tweaks
- 3D Preview
- User-friendly interface 

Download Video Tutorial (expanding + patching the ROM)

Download Mario 64 Texture Pack (with most textures from Mario 64)

The information contained on this page will help you getting better results out of it, please
take the time to read everything carefully if you are serious about hacking the game.

You can seek further help on the Justus League SM64 Hacking Forum (be sure to read the
forum info and post on the proper threads).

Getting Started (preparing your ROM)

Before using the importer, you'll need to to do some changes to your ROM so it can be properly used
by the importer. Just follow these three steps:

1) Extend a Mario 64 ROM with VL-Tone's Mario 64 ROM Extender. 
2) Drag-and drop the extended ROM  into "rom_expand.exe".
3) Apply the obj_import6.ppf patch into the "expanded" ROM using PPF-o-Matic.

There's a video tutorial showing this process step-by-step.

To run the importer, the  .NET Framework 3.5 is required (but most likely it's already installed on 
your computer so you won't have to worry about it). To make sure textures will work, also download
 the Visual C++ 2008 Redistributable Package (x86). If you are using a 64-bit Windows, those are 
needed as well: Visual C++ 2008 Redistributable Package (x64). Those two packages are needed
because an external utility (ImageMagick) is used to support a wide range of texture formats.

Important: to open the ROM in Toad's Tool 64, first open a regular extended ROM (not the one you just
modified), go into the Preferences menu and toggle the "Skip Checksum Check" checkbox. This only
has to be done once.

Setting up your emulator

In order to play your hacked ROM, you may need to change some settings in your emulator, especially
if you are using Project 64. That's because, unlike the original Mario 64 ROM, the imported levels use
extended memory for more flexibility.

Other emulators such as MupenPlus,
1964 and 
 SixtyForce (MAC) 
should work without any special setting.

So, In Project 64, you'll have to change the "Default Memory Size" to 8MB. To do this, click on
Options -> Settings -> Options and uncheck "Hide Advanced Settings".

Click OK and now do Options -> Settings -> Advanced Settings -> Default Memory Size -> 8MB.

Now load the ROM with the imported level. Once the ROM has been loaded, go to
Options -> Settings -> ROM Settings -> Memory Size -> 8MB. 

Modelling guidelines and limitations

Among the Mario 64 hacking community, Google SketchUp seems to be the most widely used 3D modeller, 
closely followed by Blender (both are freeware). In my opinion, SketchUp's ease of use is unmatched and may
be the best choice for newbies on 3D modelling. 

In either case, you'll need to export your model to the Wavefront .OBJ file. The free version of SketchUp
doesn't support exporting to this format, so you'll need this Obj Exporter Plugin. Even if you are using
the "Pro" version of SketchUp, I highly recommend this plug-in over the native exporter.

Some limitations you'll have to keep in mind:

- Keep it very low-polygon, just like the original Mario 64 levels. Use simpler shapes, like hexagons over spheres.
Mario 64 collision system was not designed to work with detailed models.

- Texture mapping has very limited precision in the N64. If your texture repeats more than 32 times in a single polygon
(easy to happen when using 32x32 textures), you can either adjust the texture scaling so it gets stretched or subdivide
the faces. On the other end, if your texture require very detailed mapping, such as spheres or other hi-poly objects, results
will very poor. If any of those scenarios happen, you'll get a "textures coordinates out of range" error.

-External textures in a wide variety of formats are accepted, however due to the very limited N64 texture cache
the maximum texture size is 64x32 pixels. If your texture exceeds the texture cache size (such as, 64x64), it
will be automatically resized so that it can work properly. For best results, the recommended texture sizes
are 32x32, 32x64 or 64x32. 

- Your .obj file should only contain triangles. Usually the .obj exporter already does that for you, but if only half of
the faces are shown when you import the model. In SketchUp, you'll need a "triangulation" plug-in, and in Blender
make sure you check the "triangulation" option when exporting the .obj file.

-The maximum number of triangles a model can contain is 6500, if your model exceeds that it won't be imported.

- The level playing field is limited. The X and Z axis range is from -8192 to +8192 (internal game scaling), but the
Y axis can be used more freely.


The level importer interface is separated into tabs, each covering specific aspects of the level that will be imported
as well as additional settings. There also five main buttons in the interface:

Load Settings: This will load previously saved settings.
Save Settings: This will save all the current settings in the "Import Settings", "Level Settings", "Objects Banks"
and "Water Boxes" tabs.
Import Level: Imports the level currently loaded into the selected ROM. When you import (and re-import) a level
object lists aren't lost (even if you change the 3D model) so you can work incrementally on your level.
Revert Levels: Use this to switch back to the original levels in the game.
About: shows information about the program.

1. Import Stettings

Level to replace

Any level in the game be replaced, however you may have problems replacing the following levels: "Castle Grounds",
"Inside Castle" and "Picture at The End". If you want to replace the Castle Grounds, it's recommended to go to the
ROM settings tab and apply the "Skip Peach intro" and "Skip Lakitu bridge sequence" patches. If you want to avoid
any complications, you can use the "Set Start Level" in the ROM Settings to change the initial level and disable its 
act selector.

At the bottom of the list you'll see a level called "First Screen". This was intended to replace the logo in the first
screen, however it doesn't work properly yet.

Scaling Value

The scaling value will differ widely depending on how your .obj is laid out and the measurement unit used. If your scaling
is too big, the program will warn you and you should try using a smaller value. If the scale is too small, the importer won't
warn you however you may end up in an empty level surrounded only by the background image.

Floats are supported: for instance, if you want to scale down your objet to 70%, use a value of 0.7.

Offset model position

Once imported, your model gets automatically centered around the (0,0,0) coordinate so it can best use the limited
playing field of a Mario 64 level. If for any reason you don't want this, you can use this option to compensate it. 

Enable death floor

Toggling this will create a "death at the bottom" floor at the specified height covering all the level. There's another
useful side effect in using that option:  Mario is now free to walk in the entire playing area. If you don't use it,
your 3D model will determine the level boundaries (this is best understood by experimenting importing the same
level with and without this option).

Don't use textures from material file

External textures from your material file won't be imported. This feature can be used if you run into #texture problems when opening
your level in TT64. Toggle it, do the necessary edits in TT64 and them re-import the level with the correct textures.

Vertically flip textures

This will correct the problem of textures looking up-side down.

2. Level Settings

Terrain Type

Sets the global terrain type, which affects not only the collision but also which particles Mario produces (sand, snow, grass, etc).
I'm not sure what's the difference between the first two settings "Normal" and "Normal (?)", if you notice any striking difference please
contact me and describe it.

Environment effect

Additional effects. The "Lava" setting only produces lava bubbles on parts of the terrain assigned the Lava collision type.
I'm not sure what's the effect of the two "Water-related" settings, I named them this way because they are only used on
water levels.

Camera Preset

Changes the basic camera preset used.

Custom Background

You can use any image file as background, however it will be automatically resized to 256x256  (a grid of 8x8 
32x32 textures). 


Enables fog in the entire level. Adding fog to specific groups or materials isn't possible yet.

Set Mario Initial Position

This option was designed with a specific purpose: to replace Mario's initial position on levels such as the Castle Grounds
or Inside Castle. Usually the object "Warp: Mario Start" is used to set Mario's position, however some levels hard-code them
in the level script, overriding that Warp Object.

When entering any level through the Level Select menu, warps are ignored and the position set by this method is used instead,
so it may be a good idea to specify it in all levels.

3. Object Banks

Select the object banks which will be available in the level. Objects from Bank 0x0E (level specific objects) will all be
described  as "Unknown" in Toad's Tool 64.

4. Water Boxes

Water box positioning requires a pair of coordinates. Open your level in TT64 and use the "Top View" camera 
mode to place two opposing points of a rectangle, as in this diagram:

(Point 1)
|             |
|             |
|-------------x (Point 2)

Remember to keep them at ground level, otherwise perspective will trick you. While multiple water boxes
are supported, this feature is still experimental.

5. Collision

This interface lets you assign collision types to materials (textures). The first collision type, "Normal", is very flexible
and should be your primary choice most of the time. Not all Collision Type descriptions may be right.

6. ROM Settings

Hardcoded camera settings

These settings lets you enable/disable some level-specific Lakitu camera settings, such as specific positions and
turns. The effect will vary greatly depending on the level. The "Inside Castle" and "Castle Grounds" are full of
hard-coded positions, so this option will have major effect on those levels camera. Other levels, on other hand,
may simply have a static camera when disabling it.

Be sure to experiment the interaction of this option with camera presets in order the find the most suitable camera
for your custom level.

Set Act Selector

Set act selector settings for specific levels. Enabling act selectors on levels that originally didn't have them
(such as the Peach Slide) 
may crash the game because of the missing text data.

Set Pause Menu Warp

Sets the destination level and Warp ID of the "Exit Level" function in the pause menu. The destination Warp ID
must probably use the same behavior as the original Inside Castle warp 
(this needs to be tested).

7. Misc Settings


To change the paths of Moving Platforms, Koopa-the-Quick and other objects, you'll need to make a simple text
file with the coordinates. Each line should contain a X,Y,Z coordinate separated by commas (,). For instance: 

1532, 397,  -2432
1748, 397,  -2173
1335, 364,  -1839

Trajectory files can contain a maximum of 240 coordinates, but keep in that mind that they don't have to be that
detailed. Most objects in the game use from 10 to 30 coordinates.

Item Box contents

This feature lets you change the Item box contents. Here is the format (everything in hexadecimal):

[entry number], [behavior param], [model ID], [behavior].   

Each value is separated in a comma. Each line is one entry.

Included with the importer, there is a file named ItemBoxDefaultContents.txt, which you'll modify to add
new items:

00, 0000, 87, 13003DB8
01, 0000, 86, 13003DD8
02, 0000, 88, 13003E1C
03, 0000, BE, 13001F3C
04, 0000, 74, 130009A4
05, 0000, 00, 13000964
06, 0000, 00, 13000984
07, 0000, D4, 13003FDC
08, 0000, 7A, 130007F8
09, 0000, D4, 13004010
0A, 0001, 7A, 130007F8
0B, 0002, 7A, 130007F8
0C, 0003, 7A, 130007F8
0D, 0004, 7A, 130007F8
0E, 0005, 7A, 130007F8

After this, include a new entry:

0F, 0000, 7A, 1300472C

This entry tells that, if the Item Box parameter (set in Toad's Tool) is 0x0F, an object with behavior 0x1300472C 
(a Goomba), with model ID 0x7A (actually, this is the Star model ID) and behavior parameter 0x0000 will be created.

Use this document for reference on Behaviors:

8. Music Settings

This menu will let you add custom music to the game, as well as change instrument sets and rename
the sequences. Custom music files (.m64) are limited to a size of about 13000 bytes, importing sequences
bigger than that may crash the game. 

Since v15, you can enable a hack in this menu to override sequence size limitations. This hack is experimental
and can be turned on/off at any time.

Technical information: the sequence bank has ben moved to 0x2F00000 in the ROM, and the NIst table
to 0x7F000. Sequence names are saved in the ROM at 0x7F100.

Troubleshooting and FAQ

Level looks "mirrored"

If you are using SketchUp, try selecting everything (Control+A) then turning it in the red or green axis direction.

ROM in Project 64 gets blank/white screen or "Microcode" error
You haven't properly enabled extended memory. Read again "Setting Up your Emulator".

The Level Importer says my ROM is not valid

Refer to the "Getting Started" guide above, your ROM won't be accepted until
you do all the necessary steps.

Textures don't work (textures from the game are assigned):

Mostly likely there's a problem with ImageMagick's converter tool. First, try downloading the
Visual C++ 2008 Redistributable Package (x86), which are required by ImageMagick. If you are
using a 64-bit Windows, those are needed as well: Visual C++ 2008 Redistributable Package (x64).

Textures look wrongly mapped:

If you get a "texture coordinate out of range" warning, you'll probably need to subdivide faces
so that the number of times a texture is repeated in a single triangle will decrease. In Google
SketchUp, you can do that by using the line tool (the "pencil" in the interface) to subdivide 
your faces. Here is an example:

Before (very large area with repeating texture would result in errors):

After (large area is subdivided, texture mapping problems are gone):

Another way to get rid of this problem is "stretch" your texture so that there
are less repetitions of it in the same face. (In Google SketchUp, you can change
that on the Edit menu).

Another source of problems are textures sizes which aren't squarish (such as 8x8, 16x16,
32x32). Unfortunately, the importer still doesn't handle correctly texture sizes such
as 32x64, 64x32 and so on. Just change to a 32x32 texture and it should work fine.

Level crashes:

Some levels such as "Castle Grounds", "Inside Castle" and "Castle Courtyard" can be
very tricky to replace and very likely will crash upon replacing. The best way to properly
replace the Castle Grounds is to go to the ROM settings menu and enable the "Skip Peach
Intro" and "Skip Lakitu bridge intro" settings.

As for the "Inside Castle" and "Castle Courtyard" levels, try using the same bank layout
as found in the original levels or simply not replacing it.

Alpha channel doesn't work correctly:

Alpha only works if you are using .PGN textures.

Part of the level doesn't show up in TT64

Currently, Toad's Tool v0.5.994b supports a limited number of GBI commands in each level, which
is enough to render all original levels but may be insufficient for custom levels, resulting in missing
parts. You can always use the "Collision" viewer as a guide, since it will show the entire level geometry.

Textures are wrongly assigned in TT64
For some reason, TT64 can't correctly decode the GBI texture commands I am using, which may
result in erroneous textures. Just ignore it.

Q: How do I add "Special/Macro 3D Objects" to my level?

They aren't available in imported levels, however you don't actually need them. They are only more limited
versions of the flexible 0x24 objects (which can be assigned any Behavior and Model ID).

Q: Can the importer produce new 0x24 objects from custom model files?

Sorry, this is not possible yet and won't be for a while.

Q: Where can I find I the plug-in folder for Google SketchUp 8 ?

C:\Program Files (x86)\Google\Google SketchUp 8\Plugins    (x64 Windows )


C:\Program Files\Google\Google SketchUp 8\Plugins

Q: I imported a level, and all I see is the sky.

Increase (a lot) the scaling.

Q: How can I change Mario's start position in the Castle Grounds?

Check the reference for "Set Mario Initial Position" feature (Import Settings).

Half of the faces are missing:

You haven't triangulated your .obj file. The importer only supports triangles, not quads
or polygons with more than three vertices. Re-check your .obj exporter settings.

Water/toxic/mist doesn't work right:

Multiple waterboxes are a new feature included in v13 which is still a big buggy. 

TT64 says my ROM isn't valid:

Open a regular extended ROM, go into the Preferences menu and check the "skip Checksum check" box.

Custom music mutes SFX or crashes the game

Your custom music file has exceeded the maximum size. You can try enabling th experimental hack to get rid
of music size limitations on the "Music Settings" menu.

Change Log


- Major collision improvement: 6500 collision triangles are now supported, getting rid of the "invisible walls" glitch 
on levels with more than 2300 faces. 
- Experimental music hack to get rid of sequence size limitations (sequences 3x bigger than the previous limit can 
now be imported)
- Camera hack to get rid of hard-coded Lakitu positions/turns can now be enabled/disabled on a level-basis
- Change the Warp settings when you use the "Exit level" function in the pause menu
- Every imported level will also contain these shared bank objects: Bubly Tree, Snowy Tree, Spiky Tree,
Metal Door, Hazy Maze Door, Castle Door (1, 2 and 3 stars) and Castle Door with Lock.
- Fixed problems when setting Bob-omb star position
- Corrected camera presets (the selection wasn't saved in the ROM correctly)
- Fixed broken trajectory function in v14
- Corrected false "nothing is selected" warning when setting Peach's Slide timer
- Improved documentation!


- Fixed a bug with the "Disable Lakitu hardcoded camera settings" feature
- Added a few instrument sets description (thanks to Dudaw)


- Set Lakitu Camera Presets for each custom level 
- Disable some hardcoded camera settings (ROM settings menu)
- Custom music management tools: insertion, extraction, changing instrument sets. Up to 53 sequences can be inserted in the ROM
- New star positions (Bully Bosses, Boo Bosses, Eyerock, Penguin, Klepto, Wiggler, Mr. I, Treasure Chests, Piranha Plants, Peach Slide)
- New trajectories (Moving carpets, Checkboard Platforms, Metal Balls)
 Set peach slide timer limit
- Fixed problem with Fog colors
- Fixed restore option
- .Obj files with up to 6500 faces are now supported (previous limit was 6000)


- Totally redesigned GUI
- fixed mapKd issue when parsing .obj which resulted in texture problems
- set Mario start position (even on levels such as the Castle Grounds)
- fixed false "vertex out of range" warnings
- hack to switch act selectors on/off in each regular level
- trajectories for racing penguin and snowman's bottom
- collision mapping now has an interface, including a preview for resized textures
- fixed "hardcore" fog setting
- background parts (bg00.bmp files) are now correctly deleted after conversion
- multiple water boxes (still buggy)
- support for extra collision parameters (wind direction, moving sand)


- Custom background works better (not perfect yet)
- Limited water/toxic haze/myst features
- Flip textures vertically feature
- Fixed serious bug with the "restore levels" function
- 32x64 and 64x32 now works correctly!


- Custom Background import feature
- Offset model position feature
- New ROM Settings: set trajectories, Item Box contents and restore CRC bootcode check.
- Minor GUI redesign to accomodate new features
- Fixed "start level" function in ROM Settings
- Fixed weather settings when alpha faces weren't present
- Fixed problem with fog command that would crash TT64
- Fixed alpha problems when fog was enabled


- ROM settings feature
- Fixed a problem with fog which could result in TT64 errors


- Alpha support for .PNG textures
- Fog settings (won't work with alpha textures)
- Fixed a bank selector bug that would corrupt the ROM


- Object bank selectors
- Mapping collision type to materials
- Selecting music/level terrain types
- Save/Load settings feature
- Fixed path bugs which prevented textures from being loaded.


- Revert levels feature (restore the original levels)
- Intro screen replacement (not sure if it works well, it needs to be tested further)
- Better error trapping
- Much better .obj and .mtl parsing
- Debugging features (conversion log)


- Graphical interface! (Requires .NET Framework 3.5)
- Replace all levels instead of only Bob-omb Battlefield.
- Select background and environment effect, including beta flower.
- Comprehensive error trapping.
- Fixed problems with texture paths as well as parsing problems when the file had spaces.
- Better texture handling.
- Model files are now centered around (0,0,0).
- Video Tutorial.

Hits -> Web Counters
Fernando Rauber,
18 de set de 2011 18:57
Fernando Rauber,
21 de fev de 2010 12:39
Fernando Rauber,
19 de jul de 2010 15:43
Fernando Rauber,
14 de jun de 2010 20:32
Fernando Rauber,
6 de mar de 2010 15:01
Fernando Rauber,
6 de mar de 2010 15:01
Fernando Rauber,
16 de dez de 2010 18:38
Fernando Rauber,
31 de jul de 2010 08:07
Fernando Rauber,
23 de fev de 2010 09:18
Fernando Rauber,
21 de fev de 2010 12:46
Fernando Rauber,
21 de fev de 2010 12:37
Fernando Rauber,
11 de fev de 2010 19:55