nsbmd-rs

A Rust library for parsing, modifying, and rebuilding Nintendo DS .nsbmd (Nitro Models) files.

Status: 🚧 Experimental / Proof of Concept. This project was developed to solve specific rigging challenges in Inazuma Eleven modding and is currently in an unfinished state.

📖 Overview

The nsbmd format is a container used by the Nintendo DS to store 3D models. While tools like apicula, g3dcvtr, or MKDS Course Modifier exist, they often lack the granular control required for preserving complex skeletal animations when modifying geometry.

This project aims to:

1. Parse .nsbmd files into a manipulatable Rust struct.
2. Extract vertex data from the DS GPU command lists.
3. Modify the mesh (specifically vertex positions) while strictly respecting the original skeleton.
4. Rebuild the binary file with the new geometry, ready for hardware.

⚽ The "Why" (Inazuma Eleven & Rigging)

This tool was born out of a specific necessity: Modding Inazuma Eleven.

Inazuma Eleven uses a highly modular character system. To allow any character to use any "Hissatsu" (special move) and wear any uniform (which involves model swaps, not just textures), the game relies on a strictly standardized skeleton.

If you modify a model (e.g., a hairstyle) using standard converters, you often lose the specific rigging properties or break the bind-pose matrices. This results in the mesh detaching or distorting during animations.

nsbmd-rs solves this by:

• Calculating the inverse transformations from the rigging.
• Applying these inverses to the new model data.
• Ensuring that when the game engine applies the animation, the modified vertices end up exactly where they should be, fully animated.

✨ Features

• Robust Parsing: Reads .nsbmd containers and breaks them down into their sub-blocks (MDL0, TEX0, etc.).
• GPU Command Execution: Simulates/Parses the internal DS GPU command lists (src/executors) to extract vertex positions.
• Rigging Support: Handles bone lists and inverse bind matrices (inv_bind_matrices.rs) to preserve animation compatibility.
• Rebuilding: Can generate valid nsbmd binaries from the modified internal structures.
• GLTF Integration: Contains experimental support for reading GLTF files (src/tools/models/formats/gltf.rs) to serve as the source for new vertex data.

🛠️ Project Structure

• src/lib.rs: Library entry point.
• src/subfiles/: Handles the internal chunks of the format (MDL, TEX, PAL).
• src/executors/: Logic for interpreting DS GPU commands (e.g., mesh_render_cmd_vertex_pos_extractor).
• src/data_structures/: Low-level structures for names and lists.
• src/tools/: Utilities for mesh command generation and format conversion (GLTF).
• src/util/math/: Fixed-point arithmetic implementation (DS hardware uses fixed-point math, not floating point).

🚀 Future Roadmap

• Multiple boned vertices support.
• Multiple textured moddels support.
• Full .nsbca (Nitro Animation) support.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This software is experimental. It deals with low-level binary manipulation. Always backup your original game files before attempting to inject models generated by this tool.