Struct BoneMappingSystem 

pub struct BoneMappingSystem;

Stateless utility for resolving semantic bone landmarks to ComponentIds in a live skeleton.

All functions are free (associated) functions — no instance state. Called once during AvatarControlSystem::try_init_splices; returns resolved IDs that AVC uses to wire IK chains.

Implementations

impl BoneMappingSystem

pub fn resolve_arm_chain( world: &World, model_root: ComponentId, hand_name: &str, lower_arm_name: Option<&str>, upper_arm_name: Option<&str>, min_bone_length: Option<f32>, ) -> Option<ResolvedArmChain>

Resolve a 2-bone arm chain from (optional) explicit names + topology fallback.

Resolution order for each joint:

1. Explicit name, if provided — look up by #name MMQ selector under model_root.
2. Topology derivation — walk TC parent chain from the joint below, using tc_ancestor_at_distance with the given min_bone_length threshold.

min_bone_length: if Some(d), topology derivation skips TC ancestors closer than d metres to the previous anchor, filtering out short helper bones. Pass None to always use the immediate TC parent.

Returns None if hand_name is not found under model_root.

pub fn resolve_spine_chain( world: &World, model_root: ComponentId, head_id: ComponentId, hips_name: Option<&str>, min_bone_length: Option<f32>, ) -> Option<ResolvedSpineChain>

Resolve a spine chain from head bone up to (optionally named) hips bone.

Walks UP from head_id via tc_ancestor_at_distance (threshold ~0.03m to skip helper bones), collecting TC joints. Stops when it hits hips_name (by component name) if provided, or after at most 8 hops otherwise.

Returns the chain in HIPS → HEAD order (FABRIK convention: root first). Returns None if the walk produces fewer than 2 joints.

pub fn tc_ancestor_at_distance( world: &World, start: ComponentId, min_dist: Option<f32>, ) -> Option<ComponentId>

Walk upward from start, returning the nearest TC ancestor whose world position is at least min_dist metres away from start.

If min_dist is None, returns the immediate TC parent (no distance filtering). Returns None if no TC parent is found, or if the walk exceeds 32 steps.

pub fn find_branching_ancestor( world: &World, start: ComponentId, min_tc_children: usize, ) -> Option<ComponentId>

Find the first TC ancestor of start that has >= min_tc_children TC children.

Used for shoulder girdle detection (first 3-way split above hips) and hip detection. Returns None if no such ancestor exists within 32 steps.