vrm-runtime 0.1.0

Renderer-agnostic VRM 1.0 loader, validator, animation system, and runtime
Documentation
use vrm_spec::vrmc_vrm_1_0::{
    AvatarPermissionType, CommercialUsageType, CreditNotationType, Meta, ModificationType,
};

/// The metadata of an avatar: name, authors, licenses and usage permissions.
#[derive(Debug, Clone, Default)]
pub struct AvatarMeta {
    pub(crate) name: String,
    pub(crate) version: Option<String>,
    pub(crate) authors: Vec<String>,
    pub(crate) copyright_information: Option<String>,
    pub(crate) contact_information: Option<String>,
    pub(crate) references: Option<Vec<String>>,
    pub(crate) third_party_licenses: Option<String>,
    pub(crate) thumbnail_image: Option<u32>,
    pub(crate) license_url: Option<String>,
    pub(crate) other_license_url: Option<String>,
    pub(crate) permissions: AvatarPermissions,
}

/// The usage permissions of an avatar, as agreed by the author.
#[derive(Debug, Clone, Default)]
pub struct AvatarPermissions {
    /// Who may use the avatar as their character.
    pub avatar_permission: AvatarPermission,
    /// The maximum permitted class of commercial usage.
    pub commercial_usage: CommercialUsage,
    /// Whether users must credit the author.
    pub credit_notation: CreditNotation,
    /// Whether modification and redistribution of modifications are permitted.
    pub modification: ModificationPermission,

    /// Whether redistribution of the original avatar is permitted.
    pub allow_redistribution: bool,
    /// Whether excessively violent usage is permitted.
    pub allow_excessively_violent_usage: bool,
    /// Whether excessively sexual usage is permitted.
    pub allow_excessively_sexual_usage: bool,
    /// Whether political or religious usage is permitted.
    pub allow_political_or_religious_usage: bool,
    /// Whether antisocial or hate-related usage is permitted.
    pub allow_antisocial_or_hate_usage: bool,
}

/// Identifies who may use the avatar as their character.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum AvatarPermission {
    /// Only the author may use the avatar.
    #[default]
    OnlyAuthor,
    /// Only people granted a separate license may use the avatar.
    OnlySeparatelyLicensedPerson,
    /// Anyone may use the avatar, subject to the remaining permissions.
    Everyone,
}

/// Maximum commercial-use category permitted by the author.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum CommercialUsage {
    /// Only personal, non-profit use is permitted.
    #[default]
    PersonalNonProfit,
    /// Personal for-profit use is also permitted.
    PersonalProfit,
    /// Corporate commercial use is also permitted.
    Corporation,
}

/// Whether users must show author credit.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum CreditNotation {
    /// Author credit is required.
    #[default]
    Required,
    /// Author credit is not required.
    Unnecessary,
}

/// Modification and modified-work redistribution permission.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ModificationPermission {
    /// Modification is prohibited.
    #[default]
    Prohibited,
    /// Modification is permitted, but redistribution of modifications is not.
    AllowModification,
    /// Both modification and redistribution of modified works are permitted.
    AllowModificationRedistribution,
}

impl From<AvatarPermissionType> for AvatarPermission {
    fn from(val: AvatarPermissionType) -> Self {
        match val {
            AvatarPermissionType::OnlyAuthor => Self::OnlyAuthor,
            AvatarPermissionType::OnlySeparatelyLicensedPerson => {
                Self::OnlySeparatelyLicensedPerson
            }
            AvatarPermissionType::Everyone => Self::Everyone,
        }
    }
}

impl From<CommercialUsageType> for CommercialUsage {
    fn from(val: CommercialUsageType) -> Self {
        match val {
            CommercialUsageType::PersonalNonProfit => Self::PersonalNonProfit,
            CommercialUsageType::PersonalProfit => Self::PersonalProfit,
            CommercialUsageType::Corporation => Self::Corporation,
        }
    }
}

impl From<CreditNotationType> for CreditNotation {
    fn from(val: CreditNotationType) -> Self {
        match val {
            CreditNotationType::Required => Self::Required,
            CreditNotationType::Unnecessary => Self::Unnecessary,
        }
    }
}

impl From<ModificationType> for ModificationPermission {
    fn from(val: ModificationType) -> Self {
        match val {
            ModificationType::Prohibited => Self::Prohibited,
            ModificationType::AllowModification => Self::AllowModification,
            ModificationType::AllowModificationRedistribution => {
                Self::AllowModificationRedistribution
            }
        }
    }
}

impl AvatarPermissions {
    pub(crate) fn load_meta(meta: &vrm_spec::vrmc_vrm_1_0::Meta) -> Self {
        Self {
            avatar_permission: meta.avatar_permission.map(Into::into).unwrap_or_default(),
            commercial_usage: meta.commercial_usage.map(Into::into).unwrap_or_default(),
            credit_notation: meta.credit_notation.map(Into::into).unwrap_or_default(),
            modification: meta.modification.map(Into::into).unwrap_or_default(),
            allow_redistribution: meta.allow_redistribution.unwrap_or(false),
            allow_excessively_violent_usage: meta.allow_excessively_violent_usage.unwrap_or(false),
            allow_excessively_sexual_usage: meta.allow_excessively_sexual_usage.unwrap_or(false),
            allow_political_or_religious_usage: meta
                .allow_political_or_religious_usage
                .unwrap_or(false),
            allow_antisocial_or_hate_usage: meta.allow_antisocial_or_hate_usage.unwrap_or(false),
        }
    }
}

impl AvatarMeta {
    /// Creates the required metadata fields for a programmatic avatar.
    pub fn new(
        name: impl Into<String>,
        authors: impl IntoIterator<Item = impl Into<String>>,
        license_url: impl Into<String>,
    ) -> Self {
        Self {
            name: name.into(),
            authors: authors.into_iter().map(Into::into).collect(),
            license_url: Some(license_url.into()),
            ..Self::default()
        }
    }

    pub(crate) fn load_meta(meta: &Meta) -> Self {
        Self {
            name: meta.name.clone(),
            version: meta.version.clone(),
            authors: meta.authors.clone(),
            copyright_information: meta.copyright_information.clone(),
            contact_information: meta.contact_information.clone(),
            references: meta.references.clone(),
            third_party_licenses: meta.third_party_licenses.clone(),
            thumbnail_image: meta.thumbnail_image.as_ref().map(|i| i.value() as u32),
            license_url: Some(meta.license_url.clone()),
            other_license_url: meta.other_license_url.clone(),
            permissions: AvatarPermissions::load_meta(meta),
        }
    }

    /// Returns the avatar title.
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Returns the author-provided avatar version.
    pub fn version(&self) -> Option<&str> {
        self.version.as_deref()
    }

    /// Returns author names in declaration order.
    pub fn authors(&self) -> &[String] {
        &self.authors
    }

    /// Returns free-form copyright information.
    pub fn copyright_information(&self) -> Option<&str> {
        self.copyright_information.as_deref()
    }

    /// Returns author contact information.
    pub fn contact_information(&self) -> Option<&str> {
        self.contact_information.as_deref()
    }

    /// Returns source or reference URLs supplied by the author.
    pub fn references(&self) -> Option<&[String]> {
        self.references.as_deref()
    }

    /// Returns third-party license notices bundled with the avatar.
    pub fn third_party_licenses(&self) -> Option<&str> {
        self.third_party_licenses.as_deref()
    }

    /// Returns the glTF image index of the square thumbnail, if present.
    pub fn thumbnail_image(&self) -> Option<u32> {
        self.thumbnail_image
    }

    /// Returns the required license URL.
    pub fn license_url(&self) -> Option<&str> {
        self.license_url.as_deref()
    }

    /// Returns an additional license URL, if supplied.
    pub fn other_license_url(&self) -> Option<&str> {
        self.other_license_url.as_deref()
    }

    /// Returns the structured usage permissions declared by the author.
    pub fn permissions(&self) -> &AvatarPermissions {
        &self.permissions
    }
}