Add Actor Animation

SDF <actor>
  │
  ├─ Import.Actor.cs: ImportActor()
  │  ├─ Create GameObject (tag="Actor")
  │  ├─ Apply SDF pose
  │  ├─ Add Helper.Actor component
  │  ├─ Create skin mesh → Implement.Actor.CreateSkin()
  │  ├─ Load animations → Implement.Actor.SetAnimation()
  │  └─ Pass script data → actorHelper.SetScript()
  │
  ├─ Implement.Actor.cs
  │  ├─ CreateSkin() → MeshLoader.CreateSkinObject()
  │  ├─ SetAnimation() → build bone hierarchy, load AnimationClip
  │  └─ GetBoneHierachy() → relative path dictionary
  │
  ├─ Assimp.Animation.cs: LoadAnimation()
  │  ├─ KeyFramesPosition → localPosition curves
  │  ├─ KeyFramesRotation → localRotation curves (quaternion XYZW)
  │  └─ KeyFramesScale → localScale curves
  │
  └─ Helper.Actor.cs (runtime)
     ├─ Waypoint following (LateUpdate)
     ├─ NavMeshAgent configuration
     └─ Reset handling

<actor name="walking_person">
  <pose>0 0 0 0 0 0</pose>

  <skin>
    <filename>meshes/person.dae</filename>
    <scale>1.0</scale>
  </skin>

  <animation name="walk">
    <filename>meshes/walk.dae</filename>
    <scale>1.0</scale>
    <interpolate_x>true</interpolate_x>
  </animation>

  <script>
    <loop>true</loop>
    <delay_start>0.0</delay_start>
    <auto_start>true</auto_start>

    <trajectory id="0" type="walk">
      <waypoint>
        <time>0</time>
        <pose>0 0 0 0 0 0</pose>
      </waypoint>
      <waypoint>
        <time>5</time>
        <pose>5 0 0 0 0 0</pose>
      </waypoint>
    </trajectory>
  </script>
</actor>

// In Implement.Actor.cs
static GameObject CreateSkin(in string skinFilename)
{
	return MeshLoader.CreateSkinObject(skinFilename);
	// Returns GameObject with:
	//   - SkinnedMeshRenderer (bone-weighted mesh)
	//   - Bone hierarchy as child transforms
	//   - Materials applied from mesh file
}

// In Import.Actor.cs
var newSkinObject = Implement.Actor.CreateSkin(actor.SkinFilename);
newSkinObject.transform.SetParent(actorObject.transform, false);
newSkinObject.transform.localScale = Vector3.one * (float)actor.SkinScale;

// GetBoneHierachy() walks all descendants of rootBone
// Builds dictionary: { "boneName": "Parent/Child/boneName" }
//
// Example:
// {
//   "Hips":        "Hips",
//   "Spine":       "Hips/Spine",
//   "LeftArm":     "Hips/Spine/LeftArm",
//   "LeftForeArm": "Hips/Spine/LeftArm/LeftForeArm"
// }

var rootBone = skinnedMeshRenderer.rootBone;
var relativePaths = GetBoneHierachy(rootBone);

// LoadAnimation() workflow:
// 1. Load scene via Assimp
// 2. Create AnimationClip (legacy=true, wrapMode=Loop, frameRate=30)
// 3. For each NodeAnimationChannel (bone animation):
//    a. Look up bone path from relativePaths dictionary
//    b. Extract position keyframes → KeyFramesPosition
//    c. Extract rotation keyframes → KeyFramesRotation
//    d. Extract scale keyframes → KeyFramesScale
//    e. Bind curves via clip.SetCurve()

var clip = MeshLoader.LoadAnimation(
	animation.Name,
	animation.Filename,
	relativePaths,
	(float)animation.Scale);

// KeyFramesPosition.Add():
// SDF (X-forward, Y-left, Z-up) → Unity (X-right, Y-up, Z-forward)
// Same mapping as SDF2Unity.Position()

// Root bone special handling:
// Root X position is SKIPPED (set by trajectory system instead)
// Only Y and Z position curves are bound for root bone
if (!isRoot)
	clip.SetCurve(relativeName, typeof(Transform), "localPosition.x", curveX);
clip.SetCurve(relativeName, typeof(Transform), "localPosition.y", curveY);
clip.SetCurve(relativeName, typeof(Transform), "localPosition.z", curveZ);

// Rotation keyframes — all 4 quaternion components bound:
clip.SetCurve(relativeName, typeof(Transform), "localRotation.x", curveRotX);
clip.SetCurve(relativeName, typeof(Transform), "localRotation.y", curveRotY);
clip.SetCurve(relativeName, typeof(Transform), "localRotation.z", curveRotZ);
clip.SetCurve(relativeName, typeof(Transform), "localRotation.w", curveRotW);

// In Implement.Actor.SetAnimation():
var animComponent = targetObject.GetComponent<Animation>();
if (animComponent == null)
	animComponent = targetObject.AddComponent<Animation>();

animComponent.AddClip(clip, animation.Name);
animComponent.clip = clip;
animComponent.wrapMode = loop ? WrapMode.Loop : WrapMode.Once;
animComponent.animatePhysics = false;
animComponent.playAutomatically = autoStart;

if (autoStart)
	animComponent.Play();
else
	animComponent.Stop();

// SetScript() preprocesses trajectory data:
// For each trajectory waypoint (skip first if Time==0):
//   - Compute linear speed = distance / deltaTime
//   - Compute angular speed = angle / deltaTime
//   - Store as WaypointToward { linearSpeed, angularSpeed, translateTo, rotateTo }

// Runtime following in LateUpdate():
// 1. Check delay timer (_scriptDelayStart)
// 2. Get current waypoint[_waypointTowardsIndex]
// 3. Vector3.MoveTowards(current, target, speed * deltaTime)
// 4. Quaternion.RotateTowards(current, target, speed * deltaTime)
// 5. SetActorPose(nextPos, nextRot)
// 6. Check convergence:
//    - distance < DistanceEpsilon (Vector3.kEpsilon * 10)
//    - angle < AngleEpsilon (Quaternion.kEpsilon * 50000)
// 7. If converged → advance to next waypoint
// 8. If loop && reached end → RestartWayPointFollowing()

// In Helper.Actor.SetAgentColliderSize() coroutine:
// 1. Wait one FixedUpdate for skinMesh bounds to settle
// 2. Compute radius from skinMesh bounds (min of X, Z extents)
// 3. Configure CapsuleCollider (direction=Y, auto-sized)
// 4. Add/configure NavMeshAgent:

_navMeshAgent.radius = capsuleRadius * AgentMarginRatio; // 1.5x margin
_navMeshAgent.height = capsuleCollider.height;
_navMeshAgent.obstacleAvoidanceType =
	ObstacleAvoidanceType.MedQualityObstacleAvoidance;
_navMeshAgent.avoidancePriority = globalCounter++; // Unique per actor
_navMeshAgent.autoBraking = true;
_navMeshAgent.autoRepath = true;
_navMeshAgent.autoTraverseOffMeshLink = false;

// Helper.Actor.Reset():
public new void Reset()
{
	base.Reset();  // Restores initial pose via PoseControl
	GetComponent<Animation>().Rewind();
	RestartWayPointFollowing();
	// → StopWaypointFollowing()
	// → Restore initial pose from GetPose(0)
	// → ClearPose() + SetPose(initPose)
	// → StartWaypointFollowing()
}