diff --git a/README.md b/README.md index 7ffe9b5..c0d6fcc 100644 --- a/README.md +++ b/README.md @@ -1,86 +1,109 @@ -# apicula +

Ore ga Omae o Mamoru model in Blender

+

apicula

+

+Build status +Lines of code +license 0BSD +
+Rip models from DS games. +

-[![Build status](https://ci.appveyor.com/api/projects/status/bavh9qh25mbta41x?svg=true)](https://ci.appveyor.com/project/scurest/apicula) -[![Lines of code](https://tokei.rs/b1/github/scurest/apicula)](https://github.com/Aaronepower/tokei) +----- -Convert Nintendo DS models and animations to COLLADA. - -The [Nitro file -formats](https://wiki.vg-resource.com/wiki/Nintendo_DS#NITRO_File_Formats) were -the formats for Nintendo's SDK for DS game developers and were used by many DS -games. This tool is for dealing with Nitro models (NSBMD files), viewing them, -and converting them to COLLADA .dae files. There is also support for loading -textures (NSBTX) and animations (NSBCA). - -![Ore ga Omae o Mamoru model imported into Blender](frontispiece.gif) +Many Nintendo DS games used [Nitro +files](https://wiki.vg-resource.com/wiki/Nintendo_DS#NITRO_File_Formats) for +assets, like NSBMD files for 3D models. apicula can extract these models and +their associated textures and animations from a ROM or memory dump, display them +in its model viewer, and convert them to the common 3D formats COLLADA and glTF +for importing into content-creation tools like Blender. * [Tutorial](https://github.com/scurest/apicula/wiki/TUTORIAL) * [Hallow's tutorial on VG Resource](https://www.vg-resource.com/thread-32332.html) * [Common Blender issues](https://github.com/scurest/apicula/wiki/BLENDER) -## Downloads +### Downloads Pre-built binaries are provided for Windows: -* [apicula-latest-x86_64-pc-windows-msvc](https://s3.amazonaws.com/apicula/apicula-latest-x86_64-pc-windows-msvc.zip) (Windows, 64-bit) -* [apicula-latest-i686-pc-windows-msvc](https://s3.amazonaws.com/apicula/apicula-latest-i686-pc-windows-msvc.zip) (Windows, 32-bit) +* [apicula for Windows, 64-bit](https://s3.amazonaws.com/apicula/apicula-latest-x86_64-pc-windows-msvc.zip) +* [apicula for Windows, 32-bit](https://s3.amazonaws.com/apicula/apicula-latest-i686-pc-windows-msvc.zip) These are built automatically off the latest `master`. You may need one of the Visual Studio Redistributable packages installed. -## Building +### Building -Building is done in the usual way for Rust projects. See [BUILDING.md](BUILDING.md). +Make sure [Rust is installed](https://rustup.rs/) and [build the usual way](https://doc.rust-lang.org/cargo/guide/working-on-an-existing-project.html) + + $ git clone https://github.com/scurest/apicula.git + $ cd apicula + $ cargo b --release + $ target/release/apciula -V -## Usage +### Usage -To view a set of models +To search a ROM or other packed file for Nitro files and extract them + + apicula extract -o + +To view models apicula view -To convert a set of models to COLLADA, placing the generated files in the given -directory +To convert models to COLLADA `.dae` files apicula convert -o -To extract Nitro files from a ROM or other packed file, placing extracted files -in the given directory +To convert models to glTF `.glb` files - apicula extract -o + apicula convert -f=glb -o To get technical information about the given Nitro files apicula info -To receive help +To receive further help apicula help See also the [tutorial](https://github.com/scurest/apicula/wiki/TUTORIAL) on the -process of extracting Nitro files from a ROM image and using apicula to convert -them to COLLADA. +process of extracting Nitro files from a ROM, converting them to COLLADA, and +importing them into Blender. -## Compatibility +### Compatibility -apicula was primarily tested with Nitro files from the following games +apicula recognized these file formats + +* `.nsbmd`, `.BMD`, or `.BMD0` contain 3D models, and often their associated + textures and palettes +* `.nsbca`, `.BCA`, or `.BCA0` contain skeletal animations +* `.nsbtx`, `.BTX`, or `.BTX0` contain textures and palettes +* `.nsbtp`, `.BTP`, or `.BTP0` contain pattern animations, which change the + textures in a material + +Pattern animations are supported in the viewer and extractor, but not in the +converter (neither COLLADA nor glTF support animations that change a material's +textures). + +Exporting is primarily tested with the following games: * Kingdom Hearts: 358/2 Days * Ore ga Omae o Mamoru * Rune Factory 3: A Fantasy Harvest Moon -Importing the COLLADA files we generate has been tested in the following programs: +Importing the resultant COLLADA files has been tested in the following programs: -* Blender +* Blender 2.79 * Godot If you can test in others (Maya, 3DS Max), that would be appreciated :) -## Special Thanks +### Special Thanks * **kiwi.ds**, for models and documentation for Nitro formats. All NDS model viewers seem to be derived from this one. Now defunct. @@ -97,6 +120,6 @@ If you can test in others (Maya, 3DS Max), that would be appreciated :) invaluable. -## License +### License 0BSD diff --git a/frontispiece.gif b/frontispiece.gif index 3938017..471b669 100644 Binary files a/frontispiece.gif and b/frontispiece.gif differ