orphism 0.2.0

a library for interacting with a certain format sometimes used for VTuber model assets
Documentation

orphism Latest Version

Overview

As a VTuber, your model probably came with a bunch of files in a runtime directory. orphism is a library for the Rust programming language that lets you load and interpret those files your own programs, assuming those programs are written in Rust.

What you do from there is up to you.

What is this NOT?

  • There is no UI, this is a library for building other things with.
  • It does not provide a way to create, edit models, beyond data serialization and deserialization.
    • If you need this, the format vendor's official editor provides this.
  • It does not provide any sort of non-Rust interface to these assets.
    • If you need this, the format vendor's official SDK provides this.

While it may be possible to build some or all of those things using this library, they are all very deliberately out of scope for this project.

What IS it then?

  • It provides a collection of data types to read, validate, and analyze these files.
  • It provides a foundation for other (more interesting) things to build on top of.
  • It is completely unencumbered by the format vendor's EULA and licensing requirements, since it does not share or include any code whatsoever with their SDK or any other licensed work.

Why does this exist?

  1. As a token of my gratitude for the VTubing community and all they do every day.

  2. To open a path for other Rustaceans to build cool things in the VTubing space.

How was this made?

  • Carefully, without using or referencing any code or libraries from the format vendor.
  • The ImHex highlighting patterns from the MOC3ingbird Exploit (CVE-2023-27566) were instrumental in understanding this format.
  • The discovery process for undocumented JSON formats is described here.
  • The discovery process for undocumented binary formats is described here.

How do I obtain this majestic tool?

Run the following Cargo command in your project directory (assuming you have cargo-edit installed):

cargo add orphism

Or add the following line to your Cargo.toml (in the [dependencies] array):

orphism = "^ 0.2"

How do I use it?

A minimal program might look something like this:

use orphism::Runtime;
use orphism::moc3::Model;
use std::path::PathBuf;

fn main() {
  let runtime = Runtime::new_from_runtime_path(PathBuf::from("./path/to/model/runtime")).expect("failed to load runtime directory");
  let moc3 = runtime.load_model().expect("failed to load model").data;
  let model = Model::read(moc3).expect("failed to parse model");
}

Project Crates

orphism is made up of several related crates. The top-level crate is this one, and it re-exports all the other sub-crates (with the exception of orphist), in addition to providing unified error handling.

If you don't need all of it, each of the supported data formats has a separate crate, so you can load only what you need for whatever you want to do.

There's also a command-line interface that's mostly useful for testing and validation.

License

orphism is available under the MIT License. See LICENSE.txt for the full text.

While the license is short, it's still written in fancy lawyer-speak. If you prefer more down-to-earth language, consider the following:

  • tl;drLegal has a simple visual summary available here.
  • FOSSA has a more in-depth overview available here.