use crate::Avatar;
use crate::instance::BoneUpdate;
use crate::node::AvatarNode;
use glam::{Mat3, Mat4, Quat, Vec3};
use serde::Deserialize;
use vrm_spec::vrmc_spring_bone_1_0 as spec;
pub(crate) const VRMC_SPRING_BONE_EXTENDED_COLLIDER: &str = "VRMC_springBone_extended_collider";
const PLANE_NORMAL_TOLERANCE: f32 = 1.0e-4;
#[derive(Debug, Clone)]
pub enum ColliderShape {
Sphere {
offset: Vec3,
radius: f32,
inside: bool,
},
Capsule {
offset: Vec3,
radius: f32,
tail: Vec3,
inside: bool,
},
Plane {
offset: Vec3,
normal: Vec3,
},
}
#[derive(Debug, Clone)]
pub struct SpringCollider {
pub node_index: u32,
pub shape: ColliderShape,
}
#[derive(Debug, Clone)]
pub struct SpringColliderGroup {
pub name: Option<String>,
pub colliders: Vec<SpringCollider>,
}
#[derive(Debug, Clone)]
pub struct SpringJoint {
pub node_index: u32,
pub hit_radius: f32,
pub stiffness: f32,
pub gravity_power: f32,
pub gravity_dir: Vec3,
pub drag_force: f32,
}
#[derive(Debug, Clone)]
pub struct SpringChain {
pub name: Option<String>,
pub center_node: Option<u32>,
pub collider_groups: Vec<usize>,
pub joints: Vec<SpringJoint>,
}
#[derive(Debug, Clone, Default)]
pub struct SpringBone {
pub collider_groups: Vec<SpringColliderGroup>,
pub springs: Vec<SpringChain>,
}
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
struct ExtendedColliderSchema {
spec_version: String,
#[serde(default)]
shape: Option<ExtendedColliderShape>,
}
#[derive(Debug, Deserialize)]
struct ExtendedColliderShape {
#[serde(default)]
sphere: Option<ExtendedColliderSphere>,
#[serde(default)]
capsule: Option<ExtendedColliderCapsule>,
#[serde(default)]
plane: Option<ExtendedColliderPlane>,
}
#[derive(Debug, Deserialize)]
struct ExtendedColliderSphere {
#[serde(default)]
offset: Option<[f64; 3]>,
#[serde(default)]
radius: Option<f64>,
#[serde(default)]
inside: bool,
}
#[derive(Debug, Deserialize)]
struct ExtendedColliderCapsule {
#[serde(default)]
offset: Option<[f64; 3]>,
#[serde(default)]
radius: Option<f64>,
#[serde(default)]
tail: Option<[f64; 3]>,
#[serde(default)]
inside: bool,
}
#[derive(Debug, Deserialize)]
struct ExtendedColliderPlane {
#[serde(default)]
offset: Option<[f64; 3]>,
#[serde(default)]
normal: Option<[f64; 3]>,
}
fn deserialize_extended_collider(
collider: &spec::Collider,
) -> Result<Option<ExtendedColliderSchema>, String> {
let Some(properties) = collider
.extensions
.as_ref()
.and_then(|extensions| extensions.get(VRMC_SPRING_BONE_EXTENDED_COLLIDER))
else {
return Ok(None);
};
let object = properties
.iter()
.map(|(name, value)| {
(
name.clone(),
value.clone().unwrap_or(serde_json::Value::Null),
)
})
.collect::<serde_json::Map<_, _>>();
serde_json::from_value(serde_json::Value::Object(object))
.map(Some)
.map_err(|error| format!("is malformed: {error}"))
}
fn finite_vec3(value: [f64; 3], field: &str) -> Result<Vec3, String> {
let result = Vec3::new(value[0] as f32, value[1] as f32, value[2] as f32);
if finite_vec3_after_narrowing(value) {
Ok(result)
} else {
Err(format!("{field} must contain finite values"))
}
}
fn finite_radius(value: Option<f64>) -> Result<f32, String> {
let value = value.unwrap_or(0.0);
let radius = value as f32;
if value >= 0.0 && finite_f32(value).is_some_and(|value| value >= 0.0) {
Ok(radius)
} else {
Err("radius must be a finite non-negative number".to_string())
}
}
fn finite_f32(value: f64) -> Option<f32> {
let narrowed = value as f32;
(value.is_finite() && narrowed.is_finite()).then_some(narrowed)
}
fn finite_vec3_after_narrowing(value: [f64; 3]) -> bool {
value
.into_iter()
.all(|component| finite_f32(component).is_some())
}
#[derive(Debug)]
struct SpringTopologyChain {
center: Option<usize>,
joints: Vec<usize>,
}
fn validate_spring_topology(
parents: &[Option<usize>],
chains: &[SpringTopologyChain],
) -> Result<(), String> {
fn ancestor_or_same(parents: &[Option<usize>], ancestor: usize, node: usize) -> bool {
if ancestor == node {
return true;
}
let mut cursor = parents.get(node).copied().flatten();
let mut steps = 0;
while let Some(current) = cursor {
if current == ancestor {
return true;
}
steps += 1;
if steps > parents.len() {
return false;
}
cursor = parents.get(current).copied().flatten();
}
false
}
let node_count = parents.len();
let mut memberships = Vec::with_capacity(chains.len());
for (chain_index, chain) in chains.iter().enumerate() {
let Some(&first_joint) = chain.joints.first() else {
return Err(format!("spring {chain_index} has no joints"));
};
if first_joint >= node_count {
return Err(format!(
"spring {chain_index} joint 0 references missing node {first_joint}"
));
}
let mut membership = vec![first_joint];
for (joint_index, pair) in chain.joints.windows(2).enumerate() {
let previous = pair[0];
let child = pair[1];
if child >= node_count {
return Err(format!(
"spring {chain_index} joint {} references missing node {child}",
joint_index + 1
));
}
if previous == child {
return Err(format!(
"spring {chain_index} joint {} must descend from the previous joint",
joint_index + 1
));
}
let mut cursor = child;
let mut steps = 0;
while cursor != previous {
membership.push(cursor);
let Some(parent) = parents.get(cursor).copied().flatten() else {
return Err(format!(
"spring {chain_index} joint {} must descend from the previous joint",
joint_index + 1
));
};
cursor = parent;
steps += 1;
if steps > node_count {
return Err(format!(
"spring {chain_index} joint {} must descend from the previous joint",
joint_index + 1
));
}
}
}
memberships.push(membership);
}
let mut owners = vec![None; node_count];
for (chain_index, membership) in memberships.iter().enumerate() {
for &node in membership {
if let Some(previous_chain) = owners[node] {
return Err(format!(
"spring {chain_index} overlaps spring {previous_chain} at explicit or implicit joint node {node}"
));
}
owners[node] = Some(chain_index);
}
}
for (chain_index, chain) in chains.iter().enumerate() {
let Some(center) = chain.center else {
continue;
};
if center >= node_count {
return Err(format!(
"spring {chain_index} references missing center node {center}"
));
}
let first_joint = chain.joints[0];
if !ancestor_or_same(parents, center, first_joint) {
return Err(format!(
"spring {chain_index} center node {center} must be its first joint {first_joint} or an ancestor"
));
}
for (other_index, membership) in memberships.iter().enumerate() {
if chain_index == other_index {
continue;
}
if let Some(other_joint) = membership
.iter()
.copied()
.find(|&node| ancestor_or_same(parents, node, center))
{
return Err(format!(
"spring {chain_index} center node {center} must not be another spring's joint node {other_joint} or its descendant"
));
}
}
}
Ok(())
}
fn parse_extended_collider_shape(
collider: &spec::Collider,
) -> Result<Option<ColliderShape>, String> {
let Some(extension) = deserialize_extended_collider(collider)? else {
return Ok(None);
};
if extension.spec_version != "1.0" {
return Err("specVersion must be `1.0`".to_string());
}
let Some(shape) = extension.shape else {
return Ok(None);
};
let shape_count = usize::from(shape.sphere.is_some())
+ usize::from(shape.capsule.is_some())
+ usize::from(shape.plane.is_some());
if shape_count != 1 {
return Err("shape must contain exactly one shape".to_string());
}
if let Some(sphere) = shape.sphere {
return Ok(Some(ColliderShape::Sphere {
offset: finite_vec3(sphere.offset.unwrap_or([0.0; 3]), "sphere.offset")?,
radius: finite_radius(sphere.radius)?,
inside: sphere.inside,
}));
}
if let Some(capsule) = shape.capsule {
return Ok(Some(ColliderShape::Capsule {
offset: finite_vec3(capsule.offset.unwrap_or([0.0; 3]), "capsule.offset")?,
radius: finite_radius(capsule.radius)?,
tail: finite_vec3(capsule.tail.unwrap_or([0.0; 3]), "capsule.tail")?,
inside: capsule.inside,
}));
}
let Some(plane) = shape.plane else {
return Err("shape must contain exactly one shape".to_string());
};
let normal = finite_vec3(plane.normal.unwrap_or([0.0, 0.0, 1.0]), "plane.normal")?;
if normal.length_squared() <= f32::EPSILON {
return Err("plane.normal must not be zero".to_string());
}
Ok(Some(ColliderShape::Plane {
offset: finite_vec3(plane.offset.unwrap_or([0.0; 3]), "plane.offset")?,
normal: normal.normalize(),
}))
}
fn extended_plane_normal_is_normalized(collider: &spec::Collider) -> Result<bool, String> {
let Some(extension) = deserialize_extended_collider(collider)? else {
return Ok(true);
};
let Some(plane) = extension.shape.and_then(|shape| shape.plane) else {
return Ok(true);
};
let normal = finite_vec3(plane.normal.unwrap_or([0.0, 0.0, 1.0]), "plane.normal")?;
Ok((normal.length() - 1.0).abs() <= PLANE_NORMAL_TOLERANCE)
}
impl SpringBone {
pub(crate) fn load_spring_bone(schema: &spec::VrmcSpringBoneSchema) -> Self {
let colliders: Vec<SpringCollider> = schema
.colliders
.as_deref()
.unwrap_or_default()
.iter()
.map(|c| {
let node_index = c.node.value() as u32;
let extended_shape = parse_extended_collider_shape(c).ok().flatten();
let shape = extended_shape.unwrap_or_else(|| {
if let Some(sphere) = &c.shape.sphere {
let offset = sphere
.offset
.map(|o| Vec3::new(o[0] as f32, o[1] as f32, o[2] as f32))
.unwrap_or(Vec3::ZERO);
ColliderShape::Sphere {
offset,
radius: sphere.radius.unwrap_or(0.0) as f32,
inside: false,
}
} else if let Some(capsule) = &c.shape.capsule {
let offset = capsule
.offset
.map(|o| Vec3::new(o[0] as f32, o[1] as f32, o[2] as f32))
.unwrap_or(Vec3::ZERO);
let tail = capsule
.tail
.map(|t| Vec3::new(t[0] as f32, t[1] as f32, t[2] as f32))
.unwrap_or(Vec3::ZERO);
ColliderShape::Capsule {
offset,
radius: capsule.radius.unwrap_or(0.0) as f32,
tail,
inside: false,
}
} else {
ColliderShape::Sphere {
offset: Vec3::ZERO,
radius: 0.0,
inside: false,
}
}
});
SpringCollider { node_index, shape }
})
.collect();
let collider_groups = schema
.collider_groups
.as_deref()
.unwrap_or_default()
.iter()
.map(|group| {
let group_colliders = group
.colliders
.iter()
.filter_map(|&idx| colliders.get(idx).cloned())
.collect();
SpringColliderGroup {
name: group.name.clone(),
colliders: group_colliders,
}
})
.collect();
let springs = schema
.springs
.as_deref()
.unwrap_or_default()
.iter()
.map(|spring| {
let joints = spring
.joints
.iter()
.map(|j| {
let g_dir = j
.gravity_dir
.map(|d| Vec3::new(d[0] as f32, d[1] as f32, d[2] as f32))
.unwrap_or(Vec3::new(0.0, -1.0, 0.0));
SpringJoint {
node_index: j.node.value() as u32,
hit_radius: j.hit_radius.unwrap_or(0.0) as f32,
stiffness: j.stiffness.unwrap_or(1.0) as f32,
gravity_power: j.gravity_power.unwrap_or(0.0) as f32,
gravity_dir: g_dir,
drag_force: j.drag_force.unwrap_or(0.5) as f32,
}
})
.collect();
SpringChain {
name: spring.name.clone(),
center_node: spring.center.as_ref().map(|c| c.value() as u32),
collider_groups: spring
.collider_groups
.as_deref()
.unwrap_or_default()
.iter()
.map(|&idx| idx as usize)
.collect(),
joints,
}
})
.collect();
Self {
collider_groups,
springs,
}
}
}
#[cfg(test)]
pub(crate) fn validate_schema(
doc: &gltf::Document,
schema: &spec::VrmcSpringBoneSchema,
) -> Result<(), crate::LoadError> {
validate_schema_with_plane_normalization(doc, schema, false).map(|_| ())
}
pub(crate) fn validate_schema_with_plane_normalization(
doc: &gltf::Document,
schema: &spec::VrmcSpringBoneSchema,
allow_plane_normalization: bool,
) -> Result<bool, crate::LoadError> {
if schema.spec_version != "1.0" {
return Err(crate::LoadError::InvalidVrm(
"/extensions/VRMC_springBone/specVersion must be `1.0`".to_string(),
));
}
if schema
.colliders
.as_ref()
.is_some_and(|items| items.is_empty())
{
return Err(crate::LoadError::InvalidVrm(
"/extensions/VRMC_springBone/colliders must not be empty when present".to_string(),
));
}
if schema
.collider_groups
.as_ref()
.is_some_and(|items| items.is_empty())
{
return Err(crate::LoadError::InvalidVrm(
"/extensions/VRMC_springBone/colliderGroups must not be empty when present".to_string(),
));
}
if schema
.springs
.as_ref()
.is_some_and(|items| items.is_empty())
{
return Err(crate::LoadError::InvalidVrm(
"/extensions/VRMC_springBone/springs must not be empty when present".to_string(),
));
}
let node_count = doc.nodes().count();
let colliders = schema.colliders.as_deref().unwrap_or_default();
let mut normalized_plane_normal = false;
for (index, collider) in colliders.iter().enumerate() {
if collider.node.value() >= node_count {
return Err(crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_springBone/colliders/{index}/node is out of range"
)));
}
let shape_count = usize::from(collider.shape.sphere.is_some())
+ usize::from(collider.shape.capsule.is_some());
if shape_count != 1 {
return Err(crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_springBone/colliders/{index}/shape must contain exactly one shape"
)));
}
let valid_vec = finite_vec3_after_narrowing;
let valid_radius = |radius: f64| {
radius >= 0.0 && finite_f32(radius).is_some_and(|narrowed| narrowed >= 0.0)
};
let valid = if let Some(sphere) = collider.shape.sphere {
sphere.radius.is_none_or(valid_radius) && sphere.offset.is_none_or(valid_vec)
} else if let Some(capsule) = collider.shape.capsule {
capsule.radius.is_none_or(valid_radius)
&& capsule.offset.is_none_or(valid_vec)
&& capsule.tail.is_none_or(valid_vec)
} else {
false
};
if !valid {
return Err(crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_springBone/colliders/{index}/shape contains invalid values"
)));
}
parse_extended_collider_shape(collider).map_err(|message| {
crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_springBone/colliders/{index}/extensions/{VRMC_SPRING_BONE_EXTENDED_COLLIDER} {message}"
))
})?;
let plane_normal_is_normalized =
extended_plane_normal_is_normalized(collider).map_err(|message| {
crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_springBone/colliders/{index}/extensions/{VRMC_SPRING_BONE_EXTENDED_COLLIDER} {message}"
))
})?;
if !plane_normal_is_normalized && !allow_plane_normalization {
return Err(crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_springBone/colliders/{index}/extensions/{VRMC_SPRING_BONE_EXTENDED_COLLIDER}/shape/plane/normal must be normalized"
)));
}
normalized_plane_normal |= !plane_normal_is_normalized;
}
let groups = schema.collider_groups.as_deref().unwrap_or_default();
for (group_index, group) in groups.iter().enumerate() {
if group.colliders.is_empty() {
return Err(crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_springBone/colliderGroups/{group_index}/colliders must not be empty"
)));
}
if group
.colliders
.iter()
.any(|&index| index >= colliders.len())
{
return Err(crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_springBone/colliderGroups/{group_index}/colliders contains an invalid index"
)));
}
}
let mut parents = vec![None; node_count];
for node in doc.nodes() {
for child in node.children() {
parents[child.index()] = Some(node.index());
}
}
let springs = schema.springs.as_deref().unwrap_or_default();
let topology = springs
.iter()
.map(|spring| SpringTopologyChain {
center: spring.center.as_ref().map(|center| center.value()),
joints: spring
.joints
.iter()
.map(|joint| joint.node.value())
.collect(),
})
.collect::<Vec<_>>();
validate_spring_topology(&parents, &topology).map_err(|message| {
crate::LoadError::InvalidVrm(format!("/extensions/VRMC_springBone/springs {message}"))
})?;
for (spring_index, spring) in springs.iter().enumerate() {
if spring
.collider_groups
.as_ref()
.is_some_and(|items| items.is_empty())
{
return Err(crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_springBone/springs/{spring_index}/colliderGroups must not be empty when present"
)));
}
if spring
.collider_groups
.as_deref()
.unwrap_or_default()
.iter()
.any(|&index| index < 0 || index as usize >= groups.len())
{
return Err(crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_springBone/springs/{spring_index}/colliderGroups contains an invalid index"
)));
}
for (joint_index, joint) in spring.joints.iter().enumerate() {
let non_negative = |value: Option<f64>| {
value.is_none_or(|value| {
value >= 0.0 && finite_f32(value).is_some_and(|narrowed| narrowed >= 0.0)
})
};
if !non_negative(joint.hit_radius)
|| !non_negative(joint.stiffness)
|| !non_negative(joint.gravity_power)
|| joint.drag_force.is_some_and(|value| {
!(0.0..=1.0).contains(&value)
|| finite_f32(value).is_none_or(|narrowed| !(0.0..=1.0).contains(&narrowed))
})
|| joint
.gravity_dir
.is_some_and(|value| !finite_vec3_after_narrowing(value))
{
return Err(crate::LoadError::InvalidVrm(format!(
"/extensions/VRMC_springBone/springs/{spring_index}/joints/{joint_index} contains invalid physics values"
)));
}
}
}
Ok(normalized_plane_normal)
}
pub(crate) fn sort_springs_by_ancestry(doc: &gltf::Document, spring_bone: &mut SpringBone) {
let mut parents = vec![None; doc.nodes().count()];
for node in doc.nodes() {
for child in node.children() {
parents[child.index()] = Some(node.index());
}
}
let depth = |node: usize| {
let mut depth = 0usize;
let mut cursor = parents.get(node).copied().flatten();
while let Some(parent) = cursor {
depth += 1;
cursor = parents.get(parent).copied().flatten();
}
depth
};
spring_bone.springs.sort_by_key(|spring| {
spring
.joints
.first()
.map(|joint| depth(joint.node_index as usize))
.unwrap_or(usize::MAX)
});
}
pub(crate) fn validate_programmatic(
nodes: &[AvatarNode],
spring_bone: &SpringBone,
) -> Result<(), String> {
let node_count = nodes.len();
let valid_vec = |value: Vec3| value.is_finite();
for (group_index, group) in spring_bone.collider_groups.iter().enumerate() {
if group.colliders.is_empty() {
return Err(format!(
"spring collider group {group_index} must contain at least one collider"
));
}
for (collider_index, collider) in group.colliders.iter().enumerate() {
if collider.node_index as usize >= node_count {
return Err(format!(
"spring collider {group_index}:{collider_index} references missing node {}",
collider.node_index
));
}
let valid = match collider.shape {
ColliderShape::Sphere { offset, radius, .. } => {
valid_vec(offset) && radius.is_finite() && radius >= 0.0
}
ColliderShape::Capsule {
offset,
radius,
tail,
..
} => valid_vec(offset) && valid_vec(tail) && radius.is_finite() && radius >= 0.0,
ColliderShape::Plane { offset, normal } => {
valid_vec(offset)
&& valid_vec(normal)
&& (normal.length() - 1.0).abs() <= PLANE_NORMAL_TOLERANCE
}
};
if !valid {
return Err(format!(
"spring collider {group_index}:{collider_index} contains invalid values"
));
}
}
}
let parents = nodes
.iter()
.map(|node| node.parent.map(|parent| parent as usize))
.collect::<Vec<_>>();
let topology = spring_bone
.springs
.iter()
.map(|spring| SpringTopologyChain {
center: spring.center_node.map(|center| center as usize),
joints: spring
.joints
.iter()
.map(|joint| joint.node_index as usize)
.collect(),
})
.collect::<Vec<_>>();
validate_spring_topology(&parents, &topology)?;
for (spring_index, spring) in spring_bone.springs.iter().enumerate() {
if spring
.collider_groups
.iter()
.any(|&group| group >= spring_bone.collider_groups.len())
{
return Err(format!(
"spring {spring_index} references a missing collider group"
));
}
for (joint_index, joint) in spring.joints.iter().enumerate() {
if !joint.hit_radius.is_finite()
|| joint.hit_radius < 0.0
|| !joint.stiffness.is_finite()
|| joint.stiffness < 0.0
|| !joint.gravity_power.is_finite()
|| joint.gravity_power < 0.0
|| !valid_vec(joint.gravity_dir)
|| !joint.drag_force.is_finite()
|| !(0.0..=1.0).contains(&joint.drag_force)
{
return Err(format!(
"spring {spring_index} joint {joint_index} contains invalid physics values"
));
}
}
}
Ok(())
}
pub struct SpringBoneSimulator {
chains: Vec<SimulatedSpringChain>,
initialized: bool,
}
#[derive(Debug, Clone)]
struct SimulatedSpringChain {
center_node: Option<u32>,
collider_group_indices: Vec<usize>,
joints: Vec<SimulatedJoint>,
}
#[derive(Debug, Clone)]
struct SimulatedJoint {
node_index: u32,
parent_node_index: Option<u32>,
bone_axis: Vec3,
bone_length: f32,
initial_local_rotation: Quat,
rest_local_matrix: Mat4,
stiffness: f32,
gravity_power: f32,
gravity_dir: Vec3,
drag_force: f32,
hit_radius: f32,
current_tail: Vec3,
prev_tail: Vec3,
}
#[derive(Debug, Clone)]
enum WorldCollider {
Sphere {
center: Vec3,
radius: f32,
inside: bool,
},
Capsule {
head: Vec3,
tail: Vec3,
radius: f32,
inside: bool,
},
Plane {
offset: Vec3,
normal: Vec3,
},
}
impl WorldCollider {
fn from_local(shape: &ColliderShape, transform: Mat4) -> Self {
let radius_scale = transform.x_axis.truncate().length();
match shape {
ColliderShape::Sphere {
offset,
radius,
inside,
} => Self::Sphere {
center: transform.transform_point3(*offset),
radius: radius * radius_scale,
inside: *inside,
},
ColliderShape::Capsule {
offset,
radius,
tail,
inside,
} => Self::Capsule {
head: transform.transform_point3(*offset),
tail: transform.transform_point3(*tail),
radius: radius * radius_scale,
inside: *inside,
},
ColliderShape::Plane { offset, normal } => {
let normal_matrix = Mat3::from_mat4(transform).inverse().transpose();
Self::Plane {
offset: transform.transform_point3(*offset),
normal: (normal_matrix * *normal).normalize_or_zero(),
}
}
}
}
fn collision(&self, next_tail: Vec3, joint_radius: f32) -> (Vec3, f32) {
match self {
Self::Sphere {
center,
radius,
inside,
} => collision_with_axis_point(next_tail - *center, *radius, joint_radius, *inside),
Self::Capsule {
head,
tail,
radius,
inside,
} => {
let segment = *tail - *head;
let segment_length_squared = segment.length_squared();
let offset_from_head = next_tail - *head;
let t = if segment_length_squared > 1.0e-6 {
(offset_from_head.dot(segment) / segment_length_squared).clamp(0.0, 1.0)
} else {
0.0
};
let delta = next_tail - (*head + segment * t);
collision_with_axis_point(delta, *radius, joint_radius, *inside)
}
Self::Plane { offset, normal } => {
let delta = next_tail - *offset;
(*normal, delta.dot(*normal) - joint_radius)
}
}
}
}
fn collision_with_axis_point(
delta: Vec3,
collider_radius: f32,
joint_radius: f32,
inside: bool,
) -> (Vec3, f32) {
let magnitude = delta.length();
let direction = if magnitude > 1.0e-6 {
delta / magnitude
} else {
Vec3::ZERO
};
if inside {
(-direction, collider_radius - joint_radius - magnitude)
} else {
(direction, magnitude - (collider_radius + joint_radius))
}
}
impl Default for SpringBoneSimulator {
fn default() -> Self {
Self::new()
}
}
impl SpringBoneSimulator {
pub fn new() -> Self {
Self {
chains: Vec::new(),
initialized: false,
}
}
pub fn reset(&mut self) {
self.chains.clear();
self.initialized = false;
}
pub fn initialize(&mut self, avatar: &Avatar, _world_matrices: &[Mat4]) {
let nodes = avatar.nodes();
let rest_world = crate::node::compute_world_matrices(nodes, &[]);
let spring_bone = avatar.spring_bone();
self.chains.clear();
let node_depth = |node_index: u32| {
let mut depth = 0usize;
let mut cursor = nodes.get(node_index as usize).and_then(|node| node.parent);
while let Some(parent) = cursor {
depth += 1;
cursor = nodes.get(parent as usize).and_then(|node| node.parent);
}
depth
};
let mut springs: Vec<&SpringChain> = spring_bone.springs.iter().collect();
springs.sort_by_key(|spring| {
spring
.joints
.first()
.map(|joint| node_depth(joint.node_index))
.unwrap_or(usize::MAX)
});
for spring in springs {
let center_mat = spring
.center_node
.and_then(|c| rest_world.get(c as usize))
.copied();
let world_to_center = center_mat.map(|m| m.inverse()).unwrap_or(Mat4::IDENTITY);
let mut joints = Vec::new();
for pair in spring.joints.windows(2) {
let head = &pair[0];
let child_node_index = pair[1].node_index;
let head_idx = head.node_index as usize;
let child_idx = child_node_index as usize;
if head_idx >= nodes.len() || child_idx >= nodes.len() {
continue;
}
let head_world = rest_world[head_idx];
let head_pos = head_world.transform_point3(Vec3::ZERO);
let child_pos = rest_world[child_idx].transform_point3(Vec3::ZERO);
let world_dir = child_pos - head_pos;
let bone_length = world_dir.length();
if bone_length <= 1e-6 {
continue;
}
let local_dir = head_world.inverse().transform_vector3(world_dir);
let bone_axis = local_dir.normalize_or_zero();
if bone_axis == Vec3::ZERO {
continue;
}
let node = &nodes[head_idx];
let current_tail = world_to_center.transform_point3(child_pos);
joints.push(SimulatedJoint {
node_index: head.node_index,
parent_node_index: node.parent,
bone_axis,
bone_length,
initial_local_rotation: node.initial_rotation,
rest_local_matrix: node.initial_local_matrix(),
stiffness: head.stiffness,
gravity_power: head.gravity_power,
gravity_dir: head.gravity_dir,
drag_force: head.drag_force,
hit_radius: head.hit_radius,
current_tail,
prev_tail: current_tail,
});
}
if !joints.is_empty() {
self.chains.push(SimulatedSpringChain {
center_node: spring.center_node,
collider_group_indices: spring.collider_groups.clone(),
joints,
});
}
}
self.initialized = true;
}
pub fn update(&mut self, avatar: &Avatar, world_matrices: &[Mat4], dt: f32) -> Vec<BoneUpdate> {
if !self.initialized {
self.initialize(avatar, world_matrices);
}
if dt <= 0.0 {
return Vec::new();
}
let nodes = avatar.nodes();
let spring_bone = avatar.spring_bone();
let mut updates = Vec::new();
let mut current_world: Vec<Mat4> = world_matrices.to_vec();
for chain in &mut self.chains {
let center_mat = chain
.center_node
.and_then(|c| current_world.get(c as usize))
.copied();
let center_to_world = center_mat.unwrap_or(Mat4::IDENTITY);
let world_to_center = center_mat.map(|m| m.inverse()).unwrap_or(Mat4::IDENTITY);
let mut colliders = Vec::new();
for &g_idx in &chain.collider_group_indices {
let Some(group) = spring_bone.collider_groups.get(g_idx) else {
continue;
};
for col in &group.colliders {
let c_idx = col.node_index as usize;
if c_idx >= current_world.len() {
continue;
}
let mat = current_world[c_idx];
colliders.push(WorldCollider::from_local(&col.shape, mat));
}
}
let next_node_indices: Vec<u32> =
chain.joints.iter().skip(1).map(|j| j.node_index).collect();
for (j, joint) in chain.joints.iter_mut().enumerate() {
let idx = joint.node_index as usize;
if idx >= current_world.len() {
continue;
}
let head_world = current_world[idx];
let head_pos = head_world.transform_point3(Vec3::ZERO);
let parent_world = match joint.parent_node_index {
Some(p) if (p as usize) < current_world.len() => current_world[p as usize],
_ => Mat4::IDENTITY,
};
let parent_rot = parent_world.to_scale_rotation_translation().1;
let world_axis = (parent_rot * joint.initial_local_rotation * joint.bone_axis)
.normalize_or_zero();
let inertia = (joint.current_tail - joint.prev_tail) * (1.0 - joint.drag_force);
let mut next_tail_world =
center_to_world.transform_point3(joint.current_tail + inertia);
next_tail_world += world_axis * (joint.stiffness * dt);
next_tail_world += joint.gravity_dir * (joint.gravity_power * dt);
let dir = (next_tail_world - head_pos).normalize_or_zero();
if dir != Vec3::ZERO {
next_tail_world = head_pos + dir * joint.bone_length;
}
for col in &colliders {
let (direction, distance) = col.collision(next_tail_world, joint.hit_radius);
if distance < 0.0 {
next_tail_world -= direction * distance;
let dir = (next_tail_world - head_pos).normalize_or_zero();
if dir != Vec3::ZERO {
next_tail_world = head_pos + dir * joint.bone_length;
}
}
}
joint.prev_tail = joint.current_tail;
joint.current_tail = world_to_center.transform_point3(next_tail_world);
let rest_world_inv = (parent_world * joint.rest_local_matrix).inverse();
let to = rest_world_inv
.transform_point3(next_tail_world)
.normalize_or_zero();
if to != Vec3::ZERO {
let delta = Quat::from_rotation_arc(joint.bone_axis, to);
updates.push(BoneUpdate::new(joint.node_index, delta));
let node = &nodes[idx];
let local = Mat4::from_scale_rotation_translation(
node.initial_scale,
node.initial_rotation * delta,
node.initial_translation,
);
current_world[idx] = parent_world * local;
if let Some(&next_node) = next_node_indices.get(j) {
update_path(&mut current_world, nodes, joint.node_index, next_node);
}
}
}
}
updates
}
}
fn update_path(current_world: &mut [Mat4], nodes: &[AvatarNode], from: u32, to: u32) {
let mut cur = to;
while cur != from {
let idx = cur as usize;
if idx >= nodes.len() {
break;
}
let Some(parent) = nodes[idx].parent else {
break;
};
let p_idx = parent as usize;
if p_idx >= current_world.len() {
break;
}
current_world[idx] = current_world[p_idx] * nodes[idx].initial_local_matrix();
cur = parent;
}
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn node(index: u32, translation: Vec3, parent: Option<u32>) -> AvatarNode {
AvatarNode {
index,
name: None,
parent,
children: Vec::new(),
initial_translation: translation,
initial_rotation: Quat::IDENTITY,
initial_scale: Vec3::ONE,
}
}
fn avatar_with_one_node() -> Avatar {
Avatar::new().with_nodes(vec![AvatarNode {
index: 0,
name: None,
parent: None,
children: Vec::new(),
initial_translation: Vec3::ZERO,
initial_rotation: Quat::IDENTITY,
initial_scale: Vec3::ONE,
}])
}
fn single_joint_chain(
axis: Vec3,
stiffness: f32,
gravity_power: f32,
gravity_dir: Vec3,
drag: f32,
) -> SimulatedSpringChain {
SimulatedSpringChain {
center_node: None,
collider_group_indices: Vec::new(),
joints: vec![SimulatedJoint {
node_index: 0,
parent_node_index: None,
bone_axis: axis,
bone_length: 0.1,
initial_local_rotation: Quat::IDENTITY,
rest_local_matrix: Mat4::IDENTITY,
stiffness,
gravity_power,
gravity_dir,
drag_force: drag,
hit_radius: 0.02,
current_tail: axis * 0.1,
prev_tail: axis * 0.1,
}],
}
}
fn run(sim: &mut SpringBoneSimulator, avatar: &Avatar, steps: usize) -> Vec<Vec<BoneUpdate>> {
let world = vec![Mat4::IDENTITY; 2];
(0..steps)
.map(|_| sim.update(avatar, &world, 0.016))
.collect()
}
#[test]
fn no_springs_yields_no_updates() {
let avatar = Avatar::new();
let mut sim = SpringBoneSimulator::new();
let world = vec![Mat4::IDENTITY; 2];
let updates = sim.update(&avatar, &world, 0.016);
assert!(updates.is_empty());
}
#[test]
fn perpendicular_gravity_swings_tail() {
let avatar = avatar_with_one_node();
let mut sim = SpringBoneSimulator {
chains: vec![single_joint_chain(Vec3::Y, 0.0, 1.0, Vec3::NEG_X, 1.0)],
initialized: true,
};
run(&mut sim, &avatar, 10);
let tail = sim.chains[0].joints[0].current_tail;
assert!(tail.x < -0.03, "tail should swing toward -X, got {tail:?}");
assert!((tail.length() - 0.1).abs() < 1e-2, "bone length preserved");
}
#[test]
fn stiffness_holds_tail_on_axis() {
let avatar = avatar_with_one_node();
let mut sim = SpringBoneSimulator {
chains: vec![single_joint_chain(Vec3::Y, 10.0, 0.0, Vec3::NEG_Y, 1.0)],
initialized: true,
};
run(&mut sim, &avatar, 30);
let tail = sim.chains[0].joints[0].current_tail;
assert!(
tail.distance(Vec3::Y * 0.1) < 1e-3,
"tail should stay on axis"
);
}
#[test]
fn collider_deflects_tail_away() {
let node = avatar_with_one_node();
let collider = SpringCollider {
node_index: 1,
shape: ColliderShape::Sphere {
offset: Vec3::new(-0.06, 0.08, 0.0),
radius: 0.06,
inside: false,
},
};
let mut chain = single_joint_chain(Vec3::Y, 0.0, 1.0, Vec3::NEG_X, 1.0);
chain.collider_group_indices = vec![0];
let mut with_collider = SpringBoneSimulator {
chains: vec![chain.clone()],
initialized: true,
};
let mut without_collider = SpringBoneSimulator {
chains: vec![single_joint_chain(Vec3::Y, 0.0, 1.0, Vec3::NEG_X, 1.0)],
initialized: true,
};
let avatar_with = node.clone().with_spring_bone(SpringBone {
collider_groups: vec![SpringColliderGroup {
name: None,
colliders: vec![collider],
}],
springs: Vec::new(),
});
run(&mut with_collider, &avatar_with, 60);
run(&mut without_collider, &node, 60);
let blocked = with_collider.chains[0].joints[0].current_tail;
let free = without_collider.chains[0].joints[0].current_tail;
assert!(
blocked.x > free.x,
"collider should block the -X swing: blocked={blocked:?} free={free:?}"
);
}
#[test]
fn update_is_deterministic() {
let avatar = avatar_with_one_node();
let mut a = SpringBoneSimulator {
chains: vec![single_joint_chain(Vec3::Y, 0.0, 1.0, Vec3::NEG_X, 1.0)],
initialized: true,
};
let mut b = SpringBoneSimulator {
chains: vec![single_joint_chain(Vec3::Y, 0.0, 1.0, Vec3::NEG_X, 1.0)],
initialized: true,
};
let updates_a = run(&mut a, &avatar, 30);
let updates_b = run(&mut b, &avatar, 30);
assert_eq!(updates_a.len(), updates_b.len());
for (step_a, step_b) in updates_a.iter().zip(updates_b.iter()) {
assert_eq!(step_a.len(), step_b.len());
for (u1, u2) in step_a.iter().zip(step_b.iter()) {
assert_eq!(u1, u2);
}
}
}
#[test]
fn initialize_orders_springs_by_joint_ancestry() {
let nodes = vec![
node(0, Vec3::ZERO, None),
node(1, Vec3::Y, Some(0)),
node(2, Vec3::Y, Some(1)),
node(3, Vec3::Y, Some(2)),
];
let joint = |node_index| SpringJoint {
node_index,
hit_radius: 0.0,
stiffness: 1.0,
gravity_power: 0.0,
gravity_dir: Vec3::NEG_Y,
drag_force: 0.5,
};
let descendant = SpringChain {
name: Some("descendant".to_string()),
center_node: None,
collider_groups: vec![],
joints: vec![joint(2), joint(3)],
};
let ancestor = SpringChain {
name: Some("ancestor".to_string()),
center_node: None,
collider_groups: vec![],
joints: vec![joint(0), joint(1)],
};
let avatar = Avatar::new()
.with_nodes(nodes)
.with_spring_bone(SpringBone {
collider_groups: vec![],
springs: vec![descendant, ancestor],
});
let mut simulator = SpringBoneSimulator::new();
simulator.initialize(&avatar, &[]);
assert_eq!(simulator.chains[0].joints[0].node_index, 0);
assert_eq!(simulator.chains[1].joints[0].node_index, 2);
}
fn spring_schema(collider: serde_json::Value) -> spec::VrmcSpringBoneSchema {
serde_json::from_value(json!({
"specVersion": "1.0",
"colliders": [collider],
"colliderGroups": [{ "colliders": [0] }]
}))
.expect("the test spring schema must deserialize")
}
fn document_with_one_node() -> gltf::Document {
gltf::Gltf::from_slice(br#"{"asset":{"version":"2.0"},"nodes":[{}]}"#)
.expect("the test glTF must be valid")
.document
}
fn extended_collider(shape: serde_json::Value) -> serde_json::Value {
json!({
"node": 0,
"shape": {
"sphere": {
"offset": [0.0, -10000.0, 0.0],
"radius": 0.0
}
},
"extensions": {
"VRMC_springBone_extended_collider": {
"specVersion": "1.0",
"shape": shape
}
}
})
}
#[test]
fn extended_inside_sphere_overrides_the_core_fallback() {
let schema = spring_schema(extended_collider(json!({
"sphere": {
"offset": [1.0, 2.0, 3.0],
"radius": 0.5,
"inside": true
}
})));
let spring_bone = SpringBone::load_spring_bone(&schema);
let parsed = &spring_bone.collider_groups[0].colliders[0].shape;
match parsed {
ColliderShape::Sphere {
offset,
radius,
inside,
} => {
assert_eq!(*offset, Vec3::new(1.0, 2.0, 3.0));
assert_eq!(*radius, 0.5);
assert!(*inside);
}
other => panic!("expected an inside sphere, got {other:?}"),
}
}
#[test]
fn extended_inside_capsule_preserves_head_tail_and_radius() {
let schema = spring_schema(extended_collider(json!({
"capsule": {
"offset": [1.0, 2.0, 3.0],
"tail": [4.0, 5.0, 6.0],
"radius": 0.75,
"inside": true
}
})));
let spring_bone = SpringBone::load_spring_bone(&schema);
match &spring_bone.collider_groups[0].colliders[0].shape {
ColliderShape::Capsule {
offset,
tail,
radius,
inside,
} => {
assert_eq!(*offset, Vec3::new(1.0, 2.0, 3.0));
assert_eq!(*tail, Vec3::new(4.0, 5.0, 6.0));
assert_eq!(*radius, 0.75);
assert!(*inside);
}
other => panic!("expected an inside capsule, got {other:?}"),
}
}
#[test]
fn core_collider_fallback_loads_as_an_outside_shape() {
let schema = spring_schema(json!({
"node": 0,
"shape": {
"sphere": {
"offset": [1.0, 2.0, 3.0],
"radius": 0.5
}
}
}));
let spring_bone = SpringBone::load_spring_bone(&schema);
match &spring_bone.collider_groups[0].colliders[0].shape {
ColliderShape::Sphere { inside, .. } => assert!(!inside),
other => panic!("expected a sphere, got {other:?}"),
}
}
#[test]
fn extended_plane_overrides_the_core_fallback_during_loading() {
let schema = spring_schema(extended_collider(json!({
"plane": {
"offset": [0.0, 2.0, 0.0],
"normal": [0.0, 1.0, 0.0]
}
})));
let spring_bone = SpringBone::load_spring_bone(&schema);
match &spring_bone.collider_groups[0].colliders[0].shape {
ColliderShape::Plane { offset, normal } => {
assert_eq!(*offset, Vec3::new(0.0, 2.0, 0.0));
assert_eq!(*normal, Vec3::Y);
}
other => panic!("expected a plane, got {other:?}"),
}
}
#[test]
fn validates_extended_collider_version_and_shape_cardinality() {
let doc = document_with_one_node();
let mut wrong_version = extended_collider(json!({
"sphere": { "radius": 1.0 }
}));
wrong_version["extensions"]["VRMC_springBone_extended_collider"]["specVersion"] =
json!("1.0-beta");
assert!(validate_schema(&doc, &spring_schema(wrong_version)).is_err());
let multiple_shapes = extended_collider(json!({
"sphere": { "radius": 1.0 },
"plane": { "normal": [0.0, 1.0, 0.0] }
}));
assert!(validate_schema(&doc, &spring_schema(multiple_shapes)).is_err());
}
#[test]
fn validates_extended_collider_numbers_and_plane_normal() {
let doc = document_with_one_node();
let negative_radius = extended_collider(json!({
"capsule": { "radius": -0.1 }
}));
assert!(validate_schema(&doc, &spring_schema(negative_radius)).is_err());
let zero_normal = extended_collider(json!({
"plane": { "normal": [0.0, 0.0, 0.0] }
}));
assert!(validate_schema(&doc, &spring_schema(zero_normal)).is_err());
let non_normalized = extended_collider(json!({
"plane": { "normal": [0.0, 2.0, 0.0] }
}));
assert!(validate_schema(&doc, &spring_schema(non_normalized)).is_err());
let recoverable_normal = extended_collider(json!({
"plane": { "normal": [0.0, 2.0, 0.0] }
}));
assert!(
validate_schema_with_plane_normalization(
&doc,
&spring_schema(recoverable_normal),
true,
)
.expect("permissive validation must normalize a non-zero plane normal")
);
let default_normal = extended_collider(json!({ "plane": {} }));
assert!(validate_schema(&doc, &spring_schema(default_normal)).is_ok());
}
#[test]
fn programmatic_plane_requires_a_finite_normalized_normal() {
let spring_bone = |normal| SpringBone {
collider_groups: vec![SpringColliderGroup {
name: None,
colliders: vec![SpringCollider {
node_index: 0,
shape: ColliderShape::Plane {
offset: Vec3::ZERO,
normal,
},
}],
}],
springs: Vec::new(),
};
let nodes = [node(0, Vec3::ZERO, None)];
assert!(validate_programmatic(&nodes, &spring_bone(Vec3::Y)).is_ok());
assert!(validate_programmatic(&nodes, &spring_bone(Vec3::ZERO)).is_err());
assert!(validate_programmatic(&nodes, &spring_bone(Vec3::Y * 2.0)).is_err());
}
fn resolve_collision(collider: &WorldCollider, tail: Vec3, hit_radius: f32) -> Vec3 {
let (direction, distance) = collider.collision(tail, hit_radius);
if distance < 0.0 {
tail - direction * distance
} else {
tail
}
}
#[test]
fn outside_and_inside_spheres_restrict_opposite_domains() {
let outside = WorldCollider::Sphere {
center: Vec3::ZERO,
radius: 1.0,
inside: false,
};
let inside = WorldCollider::Sphere {
center: Vec3::ZERO,
radius: 1.0,
inside: true,
};
assert!(resolve_collision(&outside, Vec3::X * 0.5, 0.1).distance(Vec3::X * 1.1) < 1e-5);
assert!(resolve_collision(&inside, Vec3::X * 1.5, 0.1).distance(Vec3::X * 0.9) < 1e-5);
}
#[test]
fn outside_and_inside_capsules_restrict_opposite_domains() {
let outside = WorldCollider::Capsule {
head: Vec3::ZERO,
tail: Vec3::Y,
radius: 1.0,
inside: false,
};
let inside = WorldCollider::Capsule {
head: Vec3::ZERO,
tail: Vec3::Y,
radius: 1.0,
inside: true,
};
let point = Vec3::new(0.5, 0.5, 0.0);
assert!(resolve_collision(&outside, point, 0.1).distance(Vec3::new(1.1, 0.5, 0.0)) < 1e-5);
assert!(
resolve_collision(&inside, Vec3::new(1.5, 0.5, 0.0), 0.1)
.distance(Vec3::new(0.9, 0.5, 0.0))
< 1e-5
);
}
#[test]
fn plane_keeps_the_joint_sphere_in_the_positive_half_space() {
let plane = WorldCollider::Plane {
offset: Vec3::ZERO,
normal: Vec3::Y,
};
assert!(
resolve_collision(&plane, Vec3::new(0.0, -0.5, 0.0), 0.1)
.distance(Vec3::new(0.0, 0.1, 0.0))
< 1e-5
);
}
#[test]
fn world_collider_transforms_radius_and_plane_normal() {
let transform = Mat4::from_scale_rotation_translation(
Vec3::splat(2.0),
Quat::from_rotation_z(std::f32::consts::FRAC_PI_2),
Vec3::new(3.0, 4.0, 5.0),
);
let sphere = WorldCollider::from_local(
&ColliderShape::Sphere {
offset: Vec3::X,
radius: 0.5,
inside: false,
},
transform,
);
let plane = WorldCollider::from_local(
&ColliderShape::Plane {
offset: Vec3::X,
normal: Vec3::X,
},
transform,
);
match sphere {
WorldCollider::Sphere { center, radius, .. } => {
assert!(center.distance(Vec3::new(3.0, 6.0, 5.0)) < 1e-5);
assert!((radius - 1.0).abs() < 1e-5);
}
other => panic!("expected a sphere, got {other:?}"),
}
match plane {
WorldCollider::Plane { offset, normal } => {
assert!(offset.distance(Vec3::new(3.0, 6.0, 5.0)) < 1e-5);
assert!(normal.distance(Vec3::Y) < 1e-5);
}
other => panic!("expected a plane, got {other:?}"),
}
}
}