TUTORIAL

What you'll need for this tutorial

• apicula
• the ROM image for the game your interested in
• Blender (I'm using 2.80), or another program to open COLLADA files

apicula is a command-line program so you'll need to know how to use a CLI. See Wikipedia for a short introduction.

tl;dr

# First extract Nitro files from a ROM...
apicula extract <path to rom.nds> -o <nsbxx out dir>
# ...then view the models.
apicula view <nsbxx out dir>
# ...or convert them to .daes.
apicula convert <nsbxx out dir> -o <dae out dir>

Extract

The kinds of files apicula understands are called Nitro files or .nsbXX files. The first things to do is scan the ROM image for anything that looks like a Nitro file and extract it. You can do it with

apicula extract <your rom file.nds> -o nsbxx_files

Whenever apicula creates output files it always creates a new folder to put them in. In this case, it will create a folder called nsbxx_files. Make sure the folder name you pick doesn't already exist!

If everything goes well you should get a message like

Found 402 BMDs, 0 BTXs, 318 BCAs, 9 BTPs, 8 BTAs.

and you can see that there will a lot of files in the nsbxx_files folder. If you don't get anything, your game probably doesn't use Nitro files (but it might). See EXTRACT for other ways to get files out.

See FILETYPES for a list of a types of files you'll get. Here's the short version:

• .nsbmd has models, textures, and palettes
• .nsbtx has textures and palettes
• .nsbca has joint animations (ex. a walk cycle)
• .nsbtp has pattern animations (flipbook-type animation)
• .nsbta has material animations (UV scrolling effect)

Viewing

Now that you have some Nitro files, you can view them by passing the files you want to view

apicula view <file 1> <file 2> ...

or you can pass a folder, which is the same as passing everything inside of it. For example, we can view all the models we just extracted with

apicula view nsbxx_files

You'll get a message telling you how many models, textures, palettes, and animations were found and a window will open viewing the first model. The controls are printed out too. You can move around with WASD and look by dragging the mouse button.

You can switch between models with , and .. You can cycle through all the joint animations that the current model can play with O and P. If you hold Alt, O and P will single-step through the frames of the current joint animation instead. The other animation types work similarly.

apicula tries to pick which textures and animations that go with each model. If you want you can have it apply all the animations to every model instead by passing --all-animations.

If you pass a lot of stuff at once you'll probably have models that have the wrong joint animations applied to them (currently two models with the same number of bones have the same animations). You can fix this by passing just one model and only the animations you want it to use (press the space bar to print out the files the current model/animation were found in if you need help figuring out what files to use).

Converting

To convert to COLLADA, pass the same files you did for the viewer and a folder to put the output files in

apicula convert <your files here> -o dae_files

There will be one .dae file in the output folder for each model, plus a bunch of .pngs for your textures.

Note: Only joint animations are converted. .dae files will not contain pattern or material animations.

Open Blender and pick File > Import > Collada (Default) (.dae) and navigate to the .dae you want to import, then click Import COLLADA. I also recommend ticking the "Fix Leaf Bones", "Find Bone Chains", and "Auto Connect" options under "Armature Options" when importing to get a nicer skeleton.

If your model had one animation, you can scrub the timeline to watch it play. If it had more than one Blender will have screwed it up >_<; For coping methods and more, see IMPORT: Blender.

---

That's it! Have fun!

FAQ

• Not all the textures got converted to PNGs!

  Only the PNGs needed for the models are created. You can get more by passing files with pattern animations (the PNGs needed for the pattern animation will be created even though the pattern animations aren't converted), or by passing the flag --more-textures (it will try to guess which palette matches up with which texture and create PNGs for those).

• Textures are missing!

  Sometimes they're stored in a separate .nsbtx file.

• The wrong textures are being used!

  If you passed multiple .nsbtx files, try passing only the ones you need for the model.

• A joint animation isn't being played on my model!

  Pass the flag --all-animations. It works when you convert too.

• I had problems importing the .dae into my 3D program!

  See the page for Blender or Maya.