Look-At Controllers

struct LookAtController {
    uint32_t  head_node_idx;           // The primary head/neck joint
    glm::vec3 local_forward_axis;      // The "forward" axis in the joint's local space
    glm::vec3 local_up_axis;           // The "up" axis in the joint's local space
    float     max_angle_degrees;       // Maximum deviation from the rest pose
    float     weight;                  // Blend weight: 0 = no look-at, 1 = full
};

void apply_look_at(
    std::vector<Node>&     nodes,
    const LookAtController& controller,
    const glm::vec3&        target_world)
{
    Node& head = nodes[controller.head_node_idx];

    // World position of the head joint
    glm::vec3 head_world_pos = glm::vec3(head.world_matrix[3]);

    glm::vec3 to_target = target_world - head_world_pos;
    float dist = glm::length(to_target);
    if (dist < 1e-4f) return; // Target is inside the head; ignore
    to_target /= dist;

    // Current world-space forward direction of the head joint
    glm::quat head_world_rot = head.get_world_rotation();
    glm::vec3 current_forward = head_world_rot * controller.local_forward_axis;

    float dot = glm::clamp(glm::dot(current_forward, to_target), -1.0f, 1.0f);
    if (dot > 0.9999f) return; // Already looking at target

    float angle = std::acos(dot);

    // Clamp the rotation to the maximum allowed angle.
    // This prevents the head from twisting 180 degrees around.
    float clamped_angle = std::min(angle, glm::radians(controller.max_angle_degrees));

    // Apply the weight: a weight of 0.5 would only rotate halfway to the target.
    // This is useful for blending the look-at in and out smoothly.
    clamped_angle *= controller.weight;
    if (clamped_angle < 1e-5f) return;

    glm::vec3 rotation_axis = glm::cross(current_forward, to_target);
    if (glm::length(rotation_axis) < 1e-6f) {
        // Vectors are anti-parallel; choose an arbitrary perpendicular axis.
        // Use the joint's up axis as the rotation axis to avoid gimbal issues.
        rotation_axis = head_world_rot * controller.local_up_axis;
    } else {
        rotation_axis = glm::normalize(rotation_axis);
    }

    glm::quat world_correction  = glm::angleAxis(clamped_angle, rotation_axis);
    glm::quat new_world_rot     = world_correction * head_world_rot;

    glm::quat parent_world_rot = (head.parent_index != INVALID_NODE_INDEX)
        ? nodes[head.parent_index].get_world_rotation()
        : glm::quat(1, 0, 0, 0);

    head.local_rotation = glm::inverse(parent_world_rot) * new_world_rot;
    head.mark_dirty();
    update_world_matrices_subtree(nodes, controller.head_node_idx);
}

struct LookAtChain {
    std::vector<uint32_t> joints;      // Ordered from root (spine) to tip (head)
    std::vector<float>    weights;     // Per-joint share of the total rotation (must sum to 1)
    glm::vec3 local_forward_axis;      // Forward axis in the *head joint's* local space
    glm::vec3 local_up_axis;           // Up axis in the *head joint's* local space
    float     max_total_angle_degrees; // Maximum total look-at angle across all joints
    float     blend_weight;            // Global blend weight (0 = none, 1 = full)
};

void apply_look_at_chain(
    std::vector<Node>&    nodes,
    const LookAtChain&    chain,
    const glm::vec3&      target_world)
{
    if (chain.joints.empty()) return;
    uint32_t head_idx = chain.joints.back();

    // Compute the total desired rotation (same as single-joint look-at)
    glm::vec3 head_world_pos  = glm::vec3(nodes[head_idx].world_matrix[3]);
    glm::vec3 to_target       = target_world - head_world_pos;
    float dist = glm::length(to_target);
    if (dist < 1e-4f) return;
    to_target /= dist;

    glm::quat head_world_rot   = nodes[head_idx].get_world_rotation();
    glm::vec3 current_forward  = head_world_rot * chain.local_forward_axis;

    float dot   = glm::clamp(glm::dot(current_forward, to_target), -1.0f, 1.0f);
    float angle = std::acos(dot);
    if (angle < 1e-5f) return;

    float total_angle = std::min(angle, glm::radians(chain.max_total_angle_degrees));
    total_angle *= chain.blend_weight;
    if (total_angle < 1e-5f) return;

    glm::vec3 rotation_axis = glm::cross(current_forward, to_target);
    if (glm::length(rotation_axis) < 1e-6f) {
        rotation_axis = head_world_rot * chain.local_up_axis;
    } else {
        rotation_axis = glm::normalize(rotation_axis);
    }

    // Distribute the rotation across the chain, applying each joint's share
    for (size_t i = 0; i < chain.joints.size(); ++i) {
        uint32_t joint_idx    = chain.joints[i];
        float    joint_angle  = total_angle * chain.weights[i];
        if (joint_angle < 1e-5f) continue;

        Node& joint = nodes[joint_idx];
        glm::quat world_correction = glm::angleAxis(joint_angle, rotation_axis);
        glm::quat new_world_rot    = world_correction * joint.get_world_rotation();

        glm::quat parent_world_rot = (joint.parent_index != INVALID_NODE_INDEX)
            ? nodes[joint.parent_index].get_world_rotation()
            : glm::quat(1, 0, 0, 0);

        joint.local_rotation = glm::inverse(parent_world_rot) * new_world_rot;
        joint.mark_dirty();
        update_world_matrices_subtree(nodes, joint_idx);
    }
}

struct LookAtState {
    glm::vec3 smoothed_target;  // The temporally-smoothed look-at target
    bool initialized = false;
};

void update_look_at_target(
    const glm::vec3& raw_target,
    float            speed,      // Higher = faster tracking; typical range 3–15
    float            delta_time,
    LookAtState&     state)
{
    if (!state.initialized) {
        state.smoothed_target = raw_target;
        state.initialized     = true;
        return;
    }
    float t = glm::clamp(speed * delta_time, 0.0f, 1.0f);
    state.smoothed_target = glm::mix(state.smoothed_target, raw_target, t);
}