Skip to content

Latest commit

 

History

History
134 lines (92 loc) · 5.23 KB

README.md

File metadata and controls

134 lines (92 loc) · 5.23 KB
Raw

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 or 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 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.3"

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");
}

Core Data Types

orphism primary revolves around two data types.

Runtime

The Runtime struct in orphism represents the runtime/ directory that contains your runtime model assets. This is essentially the state on disk, and mechanisms for loading from that state.

Most runtimes contain a single model, along with other files relating to that model, and orphism will attempt to detect this. If there are multiple models detected in a given runtime directory, it will return an error indicating the issue, along with the path it was attempting to load from.

For these cases, there is a Runtime::new_from_model_path that allows you to disambiguate by targeting a specific model file.

Once you have a Runtime, you can call .load_model() on it to load the Model.

Model

The Model struct in orphism represents the contents of those files, once loaded and parsed. This is essentially the state in memory, and mechanisms for accessing and using the data.

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.

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.

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.