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