tawasuyu/llimphi

1//! `Actor` — un **muñeco de cajas articuladas** (humanoide voxel estilo
2//! Minecraft/MagicaVoxel) para *actuar* en una escena filmada, con una pequeña
3//! **librería de clips de animación** ([`Clip`]: quieto/caminar/correr/saludar/
4//! señalar/festejar). Es el tercer ingrediente de la rama de juego (tras
5//! [`Player`](crate::Player) y [`raycast`](crate::raycast)): un personaje
6//! **posable y animable**.
7//!
8//! El cuerpo son 6 cajas (cabeza/torso/2 brazos/2 piernas); cada miembro rota en
9//! su articulación (cadera/hombro). Un [`Clip`] es una función `fase → `[`Pose`]
10//! (los ángulos de todas las articulaciones), así agregar una animación nueva es
11//! escribir una pose, no tocar el render. No toca la GPU: produce una **malla**
12//! (`Vec<Vertex3d>` + índices) en espacio local (pies en el origen, mirando a
13//! `+Z`) que la app sube a un [`Renderer3d`](llimphi_3d::Renderer3d) por frame
14//! (`set_geometry`) y compone con los voxels en [`Scene3d`](llimphi_3d::Scene3d).
15
16use llimphi_3d::glam::{Mat4, Vec3};
17use llimphi_3d::{push_cube, Vertex3d};
18use serde::{Deserialize, Serialize};
19
20/// Amplitud base de balanceo de miembros al caminar (rad).
21const SWING: f32 = 0.7;
22/// Duración del **cross-fade** al cambiar de clip (seg): el cuerpo mezcla la pose
23/// saliente con la entrante en este lapso, en vez de saltar en seco.
24const BLEND_DUR: f32 = 0.22;
25
26/// Suavizado Hermite `3t²−2t³` (deriva nula en los extremos) para el cross-fade.
27fn smoothstep(x: f32) -> f32 {
28    let x = x.clamp(0.0, 1.0);
29    x * x * (3.0 - 2.0 * x)
30}
31
32/// Ángulos de todas las articulaciones del muñeco en un instante. Una animación
33/// ([`Clip`]) produce una `Pose`; [`Actor::mesh`] la hornea a cajas. Ángulos en
34/// radianes; `0` = postura neutra (de pie, brazos colgando).
35#[derive(Debug, Clone, Copy, Default)]
36pub struct Pose {
37    /// Balanceo de la pierna izquierda/derecha en la cadera (eje X, adelante+).
38    pub leg_l: f32,
39    pub leg_r: f32,
40    /// Balanceo del brazo izquierdo/derecho en el hombro (eje X, adelante+).
41    pub arm_l: f32,
42    pub arm_r: f32,
43    /// Apertura del brazo izquierdo/derecho hacia el costado/arriba (eje Z). El
44    /// signo se espeja por lado dentro de [`Actor::mesh`]; positivo = levantar.
45    pub arm_l_out: f32,
46    pub arm_r_out: f32,
47    /// Cabeceo de la cabeza (eje X).
48    pub head_pitch: f32,
49    /// Desplazamiento vertical del cuerpo (rebote/respiración), en unidades.
50    pub bob: f32,
51    /// Inclinación del torso hacia adelante (eje X, alrededor de los pies).
52    pub lean: f32,
53}
54
55impl Pose {
56    /// Interpola campo a campo entre dos poses (`t=0`→`a`, `t=1`→`b`). Lo usa el
57    /// cross-fade entre clips.
58    pub fn lerp(a: &Pose, b: &Pose, t: f32) -> Pose {
59        let l = |x: f32, y: f32| x + (y - x) * t;
60        Pose {
61            leg_l: l(a.leg_l, b.leg_l),
62            leg_r: l(a.leg_r, b.leg_r),
63            arm_l: l(a.arm_l, b.arm_l),
64            arm_r: l(a.arm_r, b.arm_r),
65            arm_l_out: l(a.arm_l_out, b.arm_l_out),
66            arm_r_out: l(a.arm_r_out, b.arm_r_out),
67            head_pitch: l(a.head_pitch, b.head_pitch),
68            bob: l(a.bob, b.bob),
69            lean: l(a.lean, b.lean),
70        }
71    }
72}
73
74/// Animación: una función determinista `fase → `[`Pose`]. La fase la acumula
75/// [`Actor::advance`] a la [`cadence`](Clip::cadence) del clip.
76#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
77pub enum Clip {
78    /// De pie, respirando apenas.
79    Idle,
80    /// Caminata: piernas/brazos en oposición.
81    Walk,
82    /// Trote: balanceo amplio + inclinación hacia adelante.
83    Run,
84    /// Saludo: un brazo levantado al costado, oscilando.
85    Wave,
86    /// Señalar: un brazo extendido hacia adelante, firme.
87    Point,
88    /// Festejo: ambos brazos arriba, rebotando.
89    Cheer,
90}
91
92impl Clip {
93    /// `true` si el clip es un **gesto** (no locomoción) — un momento expresivo que
94    /// merece un acento musical. Lo usa el director para derivar los "beats del guion".
95    pub fn is_emote(self) -> bool {
96        matches!(self, Clip::Wave | Clip::Point | Clip::Cheer)
97    }
98
99    /// Velocidad de avance de la fase (rad/seg): pasos más rápidos = más cadencia.
100    pub fn cadence(self) -> f32 {
101        match self {
102            Clip::Idle => 2.0,
103            Clip::Walk => 8.0,
104            Clip::Run => 13.0,
105            Clip::Wave => 9.0,
106            Clip::Point => 3.0,
107            Clip::Cheer => 7.0,
108        }
109    }
110
111    /// La pose de este clip en la `fase` dada.
112    pub fn pose(self, phase: f32) -> Pose {
113        let s = phase.sin();
114        match self {
115            Clip::Idle => Pose {
116                bob: 0.02 * s,
117                head_pitch: 0.03 * s,
118                arm_l_out: 0.07,
119                arm_r_out: 0.07,
120                ..Pose::default()
121            },
122            Clip::Walk => Pose {
123                leg_l: s * SWING,
124                leg_r: -s * SWING,
125                arm_l: -s * SWING,
126                arm_r: s * SWING,
127                bob: (phase * 2.0).sin().abs() * 0.03,
128                ..Pose::default()
129            },
130            Clip::Run => Pose {
131                leg_l: s,
132                leg_r: -s,
133                arm_l: -s * 1.1,
134                arm_r: s * 1.1,
135                lean: 0.38,
136                bob: (phase * 2.0).sin().abs() * 0.06,
137                ..Pose::default()
138            },
139            Clip::Wave => Pose {
140                arm_r_out: 2.35 + 0.18 * s, // levantado al costado, saludando
141                arm_l_out: 0.08,
142                head_pitch: -0.05,
143                ..Pose::default()
144            },
145            Clip::Point => Pose {
146                arm_r: -1.5, // extendido hacia adelante (+Z)
147                arm_l_out: 0.07,
148                head_pitch: 0.08,
149                ..Pose::default()
150            },
151            Clip::Cheer => Pose {
152                arm_l_out: 2.6,
153                arm_r_out: 2.6,
154                bob: (phase * 2.0).sin().abs() * 0.08,
155                head_pitch: -0.1,
156                ..Pose::default()
157            },
158        }
159    }
160}
161
162/// **Edad cuantizada** del personaje: estadios discretos que cambian las
163/// proporciones del cuerpo (un bebé es cabezón y de miembros cortos; un adulto es
164/// alto y proporcionado). Sirve para *mostrar al niño primero* (el corto: nace en el
165/// desierto) y envejecerlo por etapas. Cada edad deriva un [`Build`].
166#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
167pub enum Age {
168    /// Bebé/recién nacido: chiquito, cabezón, miembros cortos.
169    Baby,
170    /// Niño.
171    Child,
172    /// Joven/adolescente.
173    Teen,
174    /// Adulto (proporciones de referencia).
175    Adult,
176    /// Anciano (apenas más bajo que el adulto).
177    Elder,
178}
179
180impl Age {
181    /// Todas las edades, de menor a mayor (para que un editor cicle entre ellas).
182    pub const ALL: [Age; 5] = [Age::Baby, Age::Child, Age::Teen, Age::Adult, Age::Elder];
183
184    /// Nombre legible (español) para la UI.
185    pub fn label(self) -> &'static str {
186        match self {
187            Age::Baby => "bebé",
188            Age::Child => "niño",
189            Age::Teen => "joven",
190            Age::Adult => "adulto",
191            Age::Elder => "anciano",
192        }
193    }
194
195    /// La edad siguiente (cicla) — para botones de ciclo.
196    pub fn next(self) -> Age {
197        let i = Age::ALL.iter().position(|&a| a == self).unwrap_or(0);
198        Age::ALL[(i + 1) % Age::ALL.len()]
199    }
200
201    /// `(escala_total, refuerzo_cabeza, escala_miembros)` por edad. Más joven =
202    /// más chico, cabeza proporcionalmente más grande y miembros más cortos.
203    fn params(self) -> (f32, f32, f32) {
204        match self {
205            Age::Baby => (0.50, 1.55, 0.70),
206            Age::Child => (0.66, 1.28, 0.82),
207            Age::Teen => (0.84, 1.08, 0.93),
208            Age::Adult => (1.00, 1.00, 1.00),
209            Age::Elder => (0.96, 1.00, 0.97),
210        }
211    }
212}
213
214/// **Constitución** del muñeco: las medidas de cada parte (posiciones de
215/// articulación y tamaños de caja), en el espacio local del actor (pies en el
216/// origen, mirando a `+Z`). Es el "esqueleto + modelado" configurable: cambiarla
217/// hace personajes distintos (alto/bajo, cabezón, etc.). Se construye por
218/// [`Age`](Age) ([`Build::for_age`]) y los pies quedan **siempre en `y=0`** por
219/// construcción (`hip_y == leg_len`).
220#[derive(Debug, Clone, Copy)]
221pub struct Build {
222    /// Altura aproximada total (referencia).
223    pub height: f32,
224    /// Centro y tamaño del torso.
225    pub torso_y: f32,
226    pub torso: Vec3,
227    /// Centro y tamaño de la cabeza.
228    pub head_y: f32,
229    pub head: Vec3,
230    /// Altura del hombro y separación lateral; largo y tamaño del brazo.
231    pub shoulder_y: f32,
232    pub shoulder_x: f32,
233    pub arm_len: f32,
234    pub arm: Vec3,
235    /// Altura de la cadera (= `leg_len`, pies en el piso), separación; largo/tamaño
236    /// de la pierna.
237    pub hip_y: f32,
238    pub hip_x: f32,
239    pub leg_len: f32,
240    pub leg: Vec3,
241    /// Tamaño de la mano.
242    pub hand: Vec3,
243}
244
245impl Build {
246    /// Construye la constitución de una [`Age`]. Bottom-up desde los pies (`y=0`),
247    /// así cualquier edad queda con los pies en el piso. `Adult` reproduce las
248    /// proporciones históricas del muñeco (los 11 cubos de siempre).
249    pub fn for_age(age: Age) -> Build {
250        let (s, head_boost, limb) = age.params();
251        let neck = 0.02 * s;
252        let leg_len = 0.80 * s * limb;
253        let hip_y = leg_len; // pies en el piso
254        let torso = Vec3::new(0.55 * s, 0.60 * s, 0.30 * s);
255        let torso_y = hip_y + torso.y * 0.5;
256        let shoulder_y = hip_y + torso.y;
257        let head = Vec3::new(0.42 * s * head_boost, 0.40 * s * head_boost, 0.42 * s * head_boost);
258        let head_y = shoulder_y + head.y * 0.5 + neck;
259        Build {
260            height: head_y + head.y * 0.5,
261            torso_y,
262            torso,
263            head_y,
264            head,
265            shoulder_y,
266            shoulder_x: 0.36 * s,
267            arm_len: 0.60 * s * limb,
268            arm: Vec3::new(0.18 * s, 0.60 * s * limb, 0.18 * s),
269            hip_y,
270            hip_x: 0.14 * s,
271            leg_len,
272            leg: Vec3::new(0.22 * s, leg_len, 0.22 * s),
273            hand: Vec3::new(0.20 * s, 0.18 * s, 0.20 * s),
274        }
275    }
276
277    /// Constitución adulta de referencia.
278    pub fn adult() -> Build {
279        Build::for_age(Age::Adult)
280    }
281}
282
283/// Personaje articulado. `pos` es el **centro de los pies** en espacio de mundo
284/// (las mismas coordenadas del terreno/grid); `facing` el rumbo (yaw, `0`=`+Z`).
285/// `clip`/`phase` definen la animación actual. Colores por zona (piel/remera/
286/// pantalón). La [`Build`] define las proporciones (edad/personaje).
287#[derive(Debug, Clone, Copy)]
288pub struct Actor {
289    /// Centro de los pies, en mundo.
290    pub pos: Vec3,
291    /// Rumbo (yaw, radianes; `0` mira a `+Z`).
292    pub facing: f32,
293    /// Animación actual.
294    pub clip: Clip,
295    /// Fase del clip (acumulada por [`advance`](Self::advance)).
296    pub phase: f32,
297    /// Clip saliente durante un cross-fade (`None` si no hay transición en curso).
298    prev_clip: Option<Clip>,
299    /// Fase del clip saliente (sigue avanzando durante la mezcla).
300    prev_phase: f32,
301    /// Progreso del cross-fade `0..1` (a `1` se descarta el clip saliente).
302    blend: f32,
303    /// Color de la piel (cabeza).
304    pub skin: [f32; 3],
305    /// Color de la remera (torso + brazos).
306    pub shirt: [f32; 3],
307    /// Color del pantalón (piernas).
308    pub pants: [f32; 3],
309    /// **IK de mirada** (look-at constraint): si está, la cabeza gira (yaw+pitch,
310    /// dentro de un rango creíble) para **mirar ese punto de mundo**, por encima del
311    /// cabeceo del clip — los ojos siguen al objetivo. `None` = cabeza alineada al
312    /// cuerpo. La fija [`look_at`](Self::look_at).
313    look_target: Option<Vec3>,
314    /// Constitución (proporciones por edad/personaje). La fija
315    /// [`with_age`](Self::with_age) / [`with_build`](Self::with_build).
316    pub build: Build,
317    /// Edad actual (estadio cuantizado) — informativo; el cuerpo lo da `build`.
318    pub age: Age,
319}
320
321impl Actor {
322    /// Actor parado en `pos` (centro de pies, mundo) mirando a `facing`, en
323    /// [`Clip::Idle`], con una paleta por defecto (piel clara, remera teal,
324    /// pantalón azul).
325    pub fn new(pos: Vec3, facing: f32) -> Self {
326        Self {
327            pos,
328            facing,
329            clip: Clip::Idle,
330            phase: 0.0,
331            prev_clip: None,
332            prev_phase: 0.0,
333            blend: 1.0,
334            skin: [0.86, 0.68, 0.54],
335            shirt: [0.20, 0.62, 0.55],
336            pants: [0.18, 0.22, 0.34],
337            look_target: None,
338            build: Build::adult(),
339            age: Age::Adult,
340        }
341    }
342
343    /// Fija la **edad** (estadio cuantizado) → recalcula la constitución del cuerpo.
344    /// Encadenable: `Actor::new(pos, yaw).with_age(Age::Baby)`. Para *mostrar al
345    /// niño primero* y envejecerlo por etapas.
346    pub fn with_age(mut self, age: Age) -> Self {
347        self.set_age(age);
348        self
349    }
350
351    /// Cambia la edad en caliente (recalcula `build`).
352    pub fn set_age(&mut self, age: Age) {
353        self.age = age;
354        self.build = Build::for_age(age);
355    }
356
357    /// Fija una constitución arbitraria (personaje a medida, no atado a una edad).
358    pub fn with_build(mut self, build: Build) -> Self {
359        self.build = build;
360        self
361    }
362
363    /// Fija (o limpia con `None`) el **objetivo de mirada** (IK de cabeza): la cabeza
364    /// y los ojos se orientan hacia ese punto de mundo, dentro de un rango creíble,
365    /// sin mover el cuerpo. Útil para que un actor "mire a cámara" o siga algo.
366    pub fn look_at(&mut self, target: Option<Vec3>) {
367        self.look_target = target;
368    }
369
370    /// Tinta el actor (piel/remera/pantalón) — encadenable tras [`new`](Self::new).
371    pub fn with_colors(mut self, skin: [f32; 3], shirt: [f32; 3], pants: [f32; 3]) -> Self {
372        self.skin = skin;
373        self.shirt = shirt;
374        self.pants = pants;
375        self
376    }
377
378    /// Cambia la animación. Si es un clip distinto, arranca un **cross-fade**: la
379    /// pose saliente se mezcla con la nueva durante [`BLEND_DUR`] segundos (sin
380    /// saltos). Repetir el mismo clip no corta nada.
381    pub fn set_clip(&mut self, clip: Clip) {
382        if self.clip != clip {
383            self.prev_clip = Some(self.clip);
384            self.prev_phase = self.phase;
385            self.clip = clip;
386            self.phase = 0.0;
387            self.blend = 0.0;
388        }
389    }
390
391    /// Avanza la animación `dt` segundos: la fase a la cadencia del clip, y —si hay
392    /// transición— la fase saliente y el progreso del cross-fade. El movimiento de
393    /// `pos`/`facing` lo maneja el llamador (la dirección).
394    pub fn advance(&mut self, dt: f32) {
395        self.phase += dt * self.clip.cadence();
396        if let Some(pc) = self.prev_clip {
397            self.prev_phase += dt * pc.cadence();
398            self.blend += dt / BLEND_DUR;
399            if self.blend >= 1.0 {
400                self.prev_clip = None;
401            }
402        }
403    }
404
405    /// La pose actual del cuerpo: la del clip vigente, o —durante un cambio— la
406    /// **mezcla** suave entre el clip saliente y el entrante.
407    pub fn pose(&self) -> Pose {
408        let target = self.clip.pose(self.phase);
409        match self.prev_clip {
410            Some(pc) => Pose::lerp(&pc.pose(self.prev_phase), &target, smoothstep(self.blend)),
411            None => target,
412        }
413    }
414
415    /// Orienta al actor para mirar hacia `target` (sólo el plano horizontal).
416    pub fn face_towards(&mut self, target: Vec3) {
417        let d = target - self.pos;
418        if d.x.abs() + d.z.abs() > 1e-4 {
419            self.facing = d.x.atan2(d.z); // yaw=0 → +Z, consistente con forward_h
420        }
421    }
422
423    /// Matriz de ubicación en mundo: traslada a `pos` y rota por `facing`. La
424    /// malla de [`mesh`](Self::mesh) está en espacio local; este es el `model`
425    /// del [`Renderer3d`](llimphi_3d::Renderer3d).
426    pub fn model(&self) -> Mat4 {
427        Mat4::from_translation(self.pos) * Mat4::from_rotation_y(self.facing)
428    }
429
430    /// Construye la **malla del cuerpo** en espacio local (pies en el origen,
431    /// mirando a `+Z`) para la pose del clip/fase actuales. 6 cajas. El cuerpo
432    /// superior (torso/cabeza/brazos) lleva el `bob`+`lean` de la pose; las
433    /// piernas quedan plantadas (sólo su balanceo de cadera) para no levantar los
434    /// pies del suelo. Subir con `Renderer3d::set_geometry` y ubicar con
435    /// [`model`](Self::model).
436    pub fn mesh(&self) -> (Vec<Vertex3d>, Vec<u16>) {
437        let p = self.pose();
438        let b = &self.build;
439        let mut v = Vec::with_capacity(8 * 11);
440        let mut i = Vec::with_capacity(36 * 11);
441
442        // Transform del cuerpo superior: rebote vertical + inclinación adelante
443        // (rotación en X alrededor de los pies/origen).
444        let body = Mat4::from_translation(Vec3::new(0.0, p.bob, 0.0)) * Mat4::from_rotation_x(p.lean);
445
446        // Torso.
447        push_cube(&mut v, &mut i, body * trs(Vec3::new(0.0, b.torso_y, 0.0), Mat4::IDENTITY, b.torso), self.shirt);
448
449        // Cabeza: cabeceo del clip + IK de mirada (yaw/pitch hacia el objetivo). El
450        // `head_anchor` (sin escala) ancla cabeza, ojos y boca para que giren juntos.
451        let (look_yaw, look_pitch) = self.look_angles();
452        let head_rot = Mat4::from_rotation_y(look_yaw) * Mat4::from_rotation_x(p.head_pitch + look_pitch);
453        let head_anchor = body * Mat4::from_translation(Vec3::new(0.0, b.head_y, 0.0)) * head_rot;
454        push_cube(&mut v, &mut i, head_anchor * Mat4::from_scale(b.head), self.skin);
455
456        // Cara: dos ojos + boca en la cara `+Z` de la cabeza. Las posiciones/tamaños
457        // van como **fracción del tamaño de la cabeza** → escalan con la edad (un bebé
458        // cabezón tiene ojos más grandes). Decales finos (apenas sobresalen, estilo
459        // Minecraft). Parpadeo determinista + boca que se abre con los gestos.
460        let (hw, hh, hd) = (b.head.x, b.head.y, b.head.z);
461        let blink = self.blink(); // 1 = abierto, ~0 = cerrado
462        let eye_sz = Vec3::new(0.095 * hw, (0.15 * hh * blink).max(0.012), 0.05 * hd);
463        let face_z = hd * 0.49; // casi en la cara +Z
464        for sx in [0.26_f32, -0.26] {
465            push_cube(
466                &mut v,
467                &mut i,
468                head_anchor * trs(Vec3::new(sx * hw, 0.12 * hh, face_z), Mat4::IDENTITY, eye_sz),
469                EYE_COLOR,
470            );
471        }
472        let mouth_open = self.mouth_open();
473        push_cube(
474            &mut v,
475            &mut i,
476            head_anchor * trs(Vec3::new(0.0, -0.25 * hh, face_z), Mat4::IDENTITY, Vec3::new(0.38 * hw, 0.05 * hh + mouth_open, 0.05 * hd)),
477            MOUTH_COLOR,
478        );
479
480        // Piernas (sin `body`: pies plantados). Articulación en la cadera.
481        let leg_rot_r = Mat4::from_rotation_x(p.leg_r);
482        let leg_rot_l = Mat4::from_rotation_x(p.leg_l);
483        limb(&mut v, &mut i, Mat4::IDENTITY, Vec3::new(b.hip_x, b.hip_y, 0.0), b.leg_len, b.leg, leg_rot_r, self.pants);
484        limb(&mut v, &mut i, Mat4::IDENTITY, Vec3::new(-b.hip_x, b.hip_y, 0.0), b.leg_len, b.leg, leg_rot_l, self.pants);
485
486        // Brazos (con `body`). Rotación = apertura(Z)·balanceo(X); apertura espejada.
487        let arm_r_rot = Mat4::from_rotation_z(p.arm_r_out) * Mat4::from_rotation_x(p.arm_r);
488        let arm_l_rot = Mat4::from_rotation_z(-p.arm_l_out) * Mat4::from_rotation_x(p.arm_l);
489        let (sh_r, sh_l) = (Vec3::new(b.shoulder_x, b.shoulder_y, 0.0), Vec3::new(-b.shoulder_x, b.shoulder_y, 0.0));
490        limb(&mut v, &mut i, body, sh_r, b.arm_len, b.arm, arm_r_rot, self.shirt);
491        limb(&mut v, &mut i, body, sh_l, b.arm_len, b.arm, arm_l_rot, self.shirt);
492
493        // Manos: una caja de piel en la punta de cada brazo (a `arm_len` del hombro).
494        hand_at(&mut v, &mut i, body, sh_r, b.arm_len, arm_r_rot, b.hand, self.skin);
495        hand_at(&mut v, &mut i, body, sh_l, b.arm_len, arm_l_rot, b.hand, self.skin);
496
497        (v, i)
498    }
499
500    /// Ángulos `(yaw, pitch)` de la cabeza para el IK de mirada: dirección al objetivo
501    /// llevada al espacio local del actor (deshaciendo `facing`) y acotada a un rango
502    /// creíble (±70° yaw, ±50° pitch) para que el cuello no se quiebre. `(0,0)` si no
503    /// hay objetivo.
504    fn look_angles(&self) -> (f32, f32) {
505        use std::f32::consts::FRAC_PI_2;
506        let Some(target) = self.look_target else { return (0.0, 0.0) };
507        // Posición aproximada de la cabeza en mundo (pies + 1.62 de altura).
508        let head_pos = self.pos + Vec3::new(0.0, 1.62, 0.0);
509        let d = target - head_pos;
510        if d.length_squared() < 1e-6 {
511            return (0.0, 0.0);
512        }
513        // A espacio local: deshacer el yaw del cuerpo.
514        let local = Mat4::from_rotation_y(-self.facing).transform_vector3(d).normalize();
515        let yaw = local.x.atan2(local.z).clamp(-1.22, 1.22); // ±70°
516        let pitch = (-local.y).asin().clamp(-0.87, 0.87); // ±50°, mirar arriba/abajo
517        let _ = FRAC_PI_2;
518        (yaw, pitch)
519    }
520
521    /// Apertura de párpados `0..1` (1 = abierto). Parpadeo determinista por la fase:
522    /// un cierre breve cada ~3 unidades de fase. Idle no necesita objetivo.
523    fn blink(&self) -> f32 {
524        let ph = self.phase * 0.33; // ciclos lentos
525        let f = ph - ph.floor();
526        // Cerrado sólo en una ventana corta (~6% del ciclo).
527        if f > 0.94 {
528            // Sube y baja rápido dentro de la ventana (triángulo invertido).
529            let w = (f - 0.94) / 0.06; // 0..1
530            (1.0 - (1.0 - (2.0 * w - 1.0).abs())).clamp(0.0, 1.0)
531        } else {
532            1.0
533        }
534    }
535
536    /// Apertura de la boca (unidades): abierta en los gestos expresivos (festejar más
537    /// que saludar/señalar), cerrada el resto → la cara "reacciona" al clip.
538    fn mouth_open(&self) -> f32 {
539        match self.clip {
540            Clip::Cheer => 0.10 + 0.04 * self.phase.sin().abs(),
541            Clip::Wave | Clip::Point => 0.05,
542            _ => 0.0,
543        }
544    }
545}
546
547/// Color de los ojos (casi negro).
548const EYE_COLOR: [f32; 3] = [0.08, 0.07, 0.09];
549/// Color de la boca (marrón oscuro).
550const MOUTH_COLOR: [f32; 3] = [0.30, 0.12, 0.12];
551
552/// Apila la **mano** en la punta de un miembro: una caja de tamaño `hand` centrada a
553/// `len` del pivote `joint` (donde termina la caja del brazo), con la misma rotación
554/// `rot` del brazo y el mismo prefijo `pre`.
555#[allow(clippy::too_many_arguments)]
556fn hand_at(
557    v: &mut Vec<Vertex3d>,
558    i: &mut Vec<u16>,
559    pre: Mat4,
560    joint: Vec3,
561    len: f32,
562    rot: Mat4,
563    hand: Vec3,
564    color: [f32; 3],
565) {
566    let m = pre
567        * Mat4::from_translation(joint)
568        * rot
569        * Mat4::from_translation(Vec3::new(0.0, -len, 0.0))
570        * Mat4::from_scale(hand);
571    push_cube(v, i, m, color);
572}
573
574/// `T(center) · R · S(size)` — caja centrada en `center`, rotada por `rot`,
575/// escalada a `size` (un cubo unitario → su caja en el cuerpo).
576fn trs(center: Vec3, rot: Mat4, size: Vec3) -> Mat4 {
577    Mat4::from_translation(center) * rot * Mat4::from_scale(size)
578}
579
580/// Apila un **miembro articulado**: caja de tamaño `size` y largo `len` que
581/// cuelga del pivote `joint` (su extremo superior) y rota por `rot` en torno a
582/// ese pivote; todo prefijado por `pre` (el transform del cuerpo, o identidad
583/// para las piernas). El centro de la caja queda a `len/2` por debajo del pivote
584/// antes de rotar.
585#[allow(clippy::too_many_arguments)]
586fn limb(
587    v: &mut Vec<Vertex3d>,
588    i: &mut Vec<u16>,
589    pre: Mat4,
590    joint: Vec3,
591    len: f32,
592    size: Vec3,
593    rot: Mat4,
594    color: [f32; 3],
595) {
596    let m = pre
597        * Mat4::from_translation(joint)
598        * rot
599        * Mat4::from_translation(Vec3::new(0.0, -len / 2.0, 0.0))
600        * Mat4::from_scale(size);
601    push_cube(v, i, m, color);
602}
603
604#[cfg(test)]
605mod tests {
606    use super::*;
607    use std::f32::consts::FRAC_PI_2;
608
609    /// Rango en Z de los vértices de la malla (cuánto adelantan/atrasan miembros).
610    fn z_span(a: &Actor) -> f32 {
611        let z: Vec<f32> = a.mesh().0.iter().map(|v| v.pos[2]).collect();
612        z.iter().cloned().fold(f32::MIN, f32::max) - z.iter().cloned().fold(f32::MAX, f32::min)
613    }
614
615    #[test]
616    fn malla_tiene_once_cajas() {
617        // 6 del cuerpo (torso/cabeza/2 piernas/2 brazos) + 2 manos + 2 ojos + boca.
618        let a = Actor::new(Vec3::ZERO, 0.0);
619        let (v, idx) = a.mesh();
620        assert_eq!(v.len(), 8 * 11, "11 cajas × 8 vértices");
621        assert_eq!(idx.len(), 36 * 11, "11 cajas × 36 índices");
622    }
623
624    #[test]
625    fn edades_cambian_proporciones_y_dejan_los_pies_en_el_piso() {
626        let baby = Build::for_age(Age::Baby);
627        let adult = Build::for_age(Age::Adult);
628        // El bebé es más bajo que el adulto.
629        assert!(baby.height < adult.height, "bebé {} < adulto {}", baby.height, adult.height);
630        // ...y CABEZÓN: la cabeza ocupa una fracción mayor de su altura.
631        let head_frac = |b: &Build| b.head.y / b.height;
632        assert!(head_frac(&baby) > head_frac(&adult) + 0.05, "bebé cabezón: {} vs {}", head_frac(&baby), head_frac(&adult));
633        // Toda edad apoya los pies en y=0 (el voxel más bajo de la malla ≈ 0).
634        for age in [Age::Baby, Age::Child, Age::Teen, Age::Adult, Age::Elder] {
635            let a = Actor::new(Vec3::ZERO, 0.0).with_age(age);
636            let ymin = a.mesh().0.iter().map(|v| v.pos[1]).fold(f32::MAX, f32::min);
637            assert!(ymin.abs() < 1e-3, "pies en el piso para {age:?}: ymin={ymin}");
638        }
639    }
640
641    #[test]
642    fn adulto_conserva_los_once_cubos_y_altura_historica() {
643        // El refactor a Build no cambió al adulto: 11 cajas y altura ~1.82.
644        let a = Actor::new(Vec3::ZERO, 0.0);
645        assert_eq!(a.mesh().0.len(), 8 * 11);
646        assert!((a.build.height - 1.82).abs() < 0.05, "altura adulta {}", a.build.height);
647    }
648
649    #[test]
650    fn ik_de_mirada_gira_la_cabeza_hacia_el_objetivo() {
651        // Mirar a la derecha (mundo +X) vs a la izquierda (−X): los ojos (vértices más
652        // adelantados en la cara) deben desplazarse en X en sentidos opuestos.
653        let eye_centroid_x = |a: &Actor| {
654            // Los ojos están en la cara +Z, son los vértices con mayor z y |x|≈0.11.
655            let verts = a.mesh().0;
656            let zmax = verts.iter().map(|v| v.pos[2]).fold(f32::MIN, f32::max);
657            let front: Vec<f32> =
658                verts.iter().filter(|v| v.pos[2] > zmax - 0.05).map(|v| v.pos[0]).collect();
659            front.iter().sum::<f32>() / front.len().max(1) as f32
660        };
661        let mut right = Actor::new(Vec3::ZERO, 0.0);
662        right.look_at(Some(Vec3::new(10.0, 1.62, 1.0)));
663        let mut left = Actor::new(Vec3::ZERO, 0.0);
664        left.look_at(Some(Vec3::new(-10.0, 1.62, 1.0)));
665        // Mirar a +X adelanta la cara hacia +X; a −X, hacia −X.
666        assert!(eye_centroid_x(&right) > eye_centroid_x(&left) + 0.05, "la cabeza sigue al objetivo");
667    }
668
669    #[test]
670    fn caminar_balancea_las_piernas() {
671        // A fase π/2 el seno es máximo → las piernas separan al máximo.
672        let mut a = Actor::new(Vec3::ZERO, 0.0);
673        a.set_clip(Clip::Walk);
674        a.advance(FRAC_PI_2 / Clip::Walk.cadence());
675        assert!(z_span(&a) > 0.5, "al caminar los miembros adelantan/atrasan: {}", z_span(&a));
676    }
677
678    #[test]
679    fn idle_casi_quieto() {
680        // En Idle los miembros no se balancean: el span en Z es chico.
681        let mut a = Actor::new(Vec3::ZERO, 0.0); // Idle por defecto
682        a.advance(FRAC_PI_2 / Clip::Idle.cadence());
683        assert!(z_span(&a) < 0.45, "Idle no debería balancear: {}", z_span(&a));
684    }
685
686    #[test]
687    fn cambiar_de_clip_reinicia_la_fase() {
688        let mut a = Actor::new(Vec3::ZERO, 0.0);
689        a.set_clip(Clip::Walk);
690        a.advance(1.0);
691        assert!(a.phase > 0.0);
692        a.set_clip(Clip::Run);
693        assert_eq!(a.phase, 0.0, "un clip nuevo arranca la pose desde 0");
694        // Repetir el mismo clip NO corta la fase.
695        a.advance(0.5);
696        let ph = a.phase;
697        a.set_clip(Clip::Run);
698        assert_eq!(a.phase, ph);
699    }
700
701    #[test]
702    fn cambio_de_clip_hace_cross_fade() {
703        // Caminando con las piernas bien abiertas…
704        let mut a = Actor::new(Vec3::ZERO, 0.0);
705        a.set_clip(Clip::Walk);
706        a.advance(FRAC_PI_2 / Clip::Walk.cadence());
707        let span_walk = z_span(&a);
708        assert!(span_walk > 0.5);
709
710        // …al pasar a Idle, JUSTO después la pose sigue siendo ~la de caminar
711        // (blend≈0), no salta de golpe a quieto.
712        a.set_clip(Clip::Idle);
713        let span_inicio = z_span(&a);
714        assert!((span_inicio - span_walk).abs() < 0.05, "el cross-fade arranca desde la pose saliente");
715
716        // Pasado el blend, ya es Idle (piernas juntas).
717        a.advance(BLEND_DUR + 0.1);
718        assert!(z_span(&a) < 0.45, "tras el cross-fade la pose es Idle");
719    }
720
721    #[test]
722    fn face_towards_mira_a_mas_z() {
723        let mut a = Actor::new(Vec3::ZERO, 0.0);
724        a.face_towards(Vec3::new(0.0, 0.0, 5.0));
725        assert!(a.facing.abs() < 1e-4, "mirar a +Z → yaw≈0");
726    }
727}