tawasuyu/llimphi

1//! World-gen procedural: terreno por ruido fractal (fbm propio, sin deps) →
2//! [`VoxelGrid`] coloreado por bandas de altura/pendiente (agua, arena, pasto,
3//! roca, nieve) con árboles. Contenido reusable por cualquier app/juego voxel.
4//!
5//! El terreno se define como **función pura de coordenadas de mundo** ([`column_height`]):
6//! el mismo punto `(wx, wz)` da siempre el mismo relieve, sin importar en qué
7//! ventana caiga. Eso es lo que hace posible el *streaming* (M6): mover una
8//! ventana acotada por un mundo ilimitado y que las costuras encajen
9//! ([`fill_terrain_window`] + [`WorldStream`](crate::WorldStream)).
10
11use llimphi_3d::VoxelGrid;
12
13/// Hash entero → `f32` en `[0, 1)`. Mezcla estilo PCG/xxhash chico, determinista.
14/// Funciona con coordenadas negativas (`as u32` envuelve de forma estable).
15#[inline]
16pub(crate) fn hash2(x: i32, y: i32, seed: u32) -> f32 {
17    let mut h = seed
18        .wrapping_add((x as u32).wrapping_mul(0x9E37_79B9))
19        .wrapping_add((y as u32).wrapping_mul(0x85EB_CA77));
20    h ^= h >> 15;
21    h = h.wrapping_mul(0x2C1B_3C6D);
22    h ^= h >> 12;
23    h = h.wrapping_mul(0x297A_2D39);
24    h ^= h >> 15;
25    (h & 0x00FF_FFFF) as f32 / 0x0100_0000 as f32
26}
27
28/// Suaviza `t` con la curva quíntica de Perlin (`6t⁵−15t⁴+10t³`).
29#[inline]
30pub(crate) fn smooth(t: f32) -> f32 {
31    t * t * t * (t * (t * 6.0 - 15.0) + 10.0)
32}
33
34/// Ruido de valor bilineal en `(x, y)` continuos sobre la lattice entera.
35/// `floor` maneja negativos (continuidad sobre coordenadas de mundo con signo).
36fn value_noise(x: f32, y: f32, seed: u32) -> f32 {
37    let xi = x.floor() as i32;
38    let yi = y.floor() as i32;
39    let xf = smooth(x - xi as f32);
40    let yf = smooth(y - yi as f32);
41    let a = hash2(xi, yi, seed);
42    let b = hash2(xi + 1, yi, seed);
43    let c = hash2(xi, yi + 1, seed);
44    let d = hash2(xi + 1, yi + 1, seed);
45    let top = a + (b - a) * xf;
46    let bot = c + (d - c) * xf;
47    top + (bot - top) * yf
48}
49
50/// Fractional Brownian motion: suma de octavas de `value_noise` (frecuencia ×2,
51/// amplitud ×`gain` por octava). Devuelve `[0, 1]` aprox (normalizado).
52pub(crate) fn fbm(x: f32, y: f32, octaves: u32, seed: u32) -> f32 {
53    let mut freq = 1.0;
54    let mut amp = 1.0;
55    let mut sum = 0.0;
56    let mut norm = 0.0;
57    for o in 0..octaves {
58        sum += value_noise(x * freq, y * freq, seed.wrapping_add(o.wrapping_mul(7919))) * amp;
59        norm += amp;
60        freq *= 2.0;
61        amp *= 0.5;
62    }
63    sum / norm
64}
65
66/// Mezcla lineal de dos colores RGB.
67#[inline]
68fn mix(a: [u8; 3], b: [u8; 3], t: f32) -> [u8; 3] {
69    let t = t.clamp(0.0, 1.0);
70    [
71        (a[0] as f32 + (b[0] as f32 - a[0] as f32) * t) as u8,
72        (a[1] as f32 + (b[1] as f32 - a[1] as f32) * t) as u8,
73        (a[2] as f32 + (b[2] as f32 - a[2] as f32) * t) as u8,
74    ]
75}
76
77/// Frecuencia espacial del relieve: ~4 colinas grandes a lo ancho de una ventana
78/// de lado `span`. Es función del **tamaño de ventana** (constante mientras la
79/// ventana no cambie de tamaño), así dos ventanas del mismo `dim` comparten la
80/// misma escala → el streaming encaja. `min_h`/`amp` salen del alto del mundo.
81#[inline]
82pub(crate) fn world_scale(dim: [u32; 3]) -> f32 {
83    4.0 / dim[0].max(dim[2]) as f32
84}
85
86/// Nivel del mar (índice `y`) para un mundo de alto `dy`.
87#[inline]
88fn sea_level(dy: u32) -> u32 {
89    (dy as f32 * 0.30) as u32
90}
91
92/// Altura del terreno (índice `y` del voxel sólido superior) en la columna de
93/// **mundo** `(wx, wz)`, para un mundo de dimensiones `dim` y `seed`. Es una
94/// **función pura**: el mismo punto da la misma altura en cualquier ventana —
95/// la clave de la continuidad del streaming. Combina un fbm base estirado
96/// (océanos↔picos) con un término *ridged* sólo en lo alto (crestas afiladas).
97pub fn column_height(wx: i32, wz: i32, dim: [u32; 3], seed: u32) -> u32 {
98    let dy = dim[1];
99    let scale = world_scale(dim);
100    let min_h = (dy as f32 * 0.03) as u32;
101    let amp = dy as f32 * 0.95;
102
103    let c = fbm(wx as f32 * scale, wz as f32 * scale, 6, seed);
104    let e0 = ((c - 0.35) * 2.0).clamp(0.0, 1.0);
105    let e = e0 * e0 * (3.0 - 2.0 * e0); // smoothstep → mesetas + valles
106    let ridge =
107        1.0 - (fbm(wx as f32 * scale * 2.3, wz as f32 * scale * 2.3, 5, seed ^ 99) - 0.5).abs() * 2.0;
108    let e = (e + e * e * ridge * 0.55).min(1.0);
109    (min_h + (e * amp) as u32).min(dy - 1)
110}
111
112/// Padding (en voxels) alrededor de la ventana para precomputar alturas: cubre
113/// el cálculo de pendiente (±1) y la copa de los árboles rooteados afuera (±2).
114const PAD: i32 = 3;
115
116/// Rellena `g` con el paisaje voxel cuya esquina local `(0,0)` cae en la columna
117/// de **mundo** `origin = [wx, wz]`. Vacía el grid primero (`clear_all`) y lo
118/// deja **dirty** para que `VoxelRenderer::sync` re-suba (o reconstruir el
119/// renderer). Es la primitiva del streaming: dos ventanas contiguas encajan
120/// porque todo sale de [`column_height`] (función de mundo).
121///
122/// `terrain(dim, seed)` es el caso `origin = [0, 0]` con el dirty reseteado.
123pub fn fill_terrain_window(g: &mut VoxelGrid, origin: [i32; 2], seed: u32) {
124    let dim = g.dim();
125    let [dx, dy, dz] = dim;
126    let sea = sea_level(dy);
127    let (ox, oz) = (origin[0], origin[1]);
128
129    g.clear_all();
130
131    let rock = [88, 86, 92];
132    let snow = [236, 240, 250];
133    let grass_lo = [54, 110, 52];
134    let grass_hi = [96, 150, 70];
135    let sand = [196, 182, 130];
136    let deep = [22, 52, 96];
137    let shallow = [44, 110, 150];
138
139    // Heightmap precomputado sobre la ventana padeada (PAD a cada lado): da
140    // pendiente y copas correctas en las costuras sin recomputar fbm de más.
141    let pw = dx as i32 + 2 * PAD;
142    let pd = dz as i32 + 2 * PAD;
143    let mut heights = vec![0u32; (pw * pd) as usize];
144    for lz in 0..pd {
145        for lx in 0..pw {
146            let wx = ox + lx - PAD;
147            let wz = oz + lz - PAD;
148            heights[(lx + lz * pw) as usize] = column_height(wx, wz, dim, seed);
149        }
150    }
151    // Altura en coordenada LOCAL de ventana (puede ser negativa hasta -PAD).
152    let h_at = |lx: i32, lz: i32| heights[((lx + PAD) + (lz + PAD) * pw) as usize];
153
154    // Terreno + agua, columna por columna de la ventana.
155    for lz in 0..dz {
156        for lx in 0..dx {
157            let (li, lj) = (lx as i32, lz as i32);
158            let (wx, wz) = (ox + li, oz + lj);
159            let h = h_at(li, lj);
160            // Pendiente: diferencia con vecinos → roca en acantilados.
161            let slope = (h as i32 - h_at(li - 1, lj) as i32)
162                .abs()
163                .max((h as i32 - h_at(li, lj - 1) as i32).abs()) as f32;
164
165            for y in 0..=h.min(dy - 1) {
166                let fh = y as f32 / dy as f32;
167                // Jitter por ruido en coordenadas de MUNDO (seamless entre ventanas).
168                let jitter = hash2(wx, wz.wrapping_mul(31).wrapping_add(y as i32), seed ^ 0xABCD) * 0.06 - 0.03;
169                let band = fh + jitter;
170                let col = if y == h && slope > 2.5 && band > 0.34 {
171                    rock
172                } else if band < 0.33 {
173                    sand
174                } else if band < 0.55 {
175                    mix(grass_lo, grass_hi, (band - 0.33) / 0.22)
176                } else if band < 0.72 {
177                    mix(grass_hi, rock, (band - 0.55) / 0.17)
178                } else if band < 0.82 {
179                    rock
180                } else {
181                    mix(rock, snow, (band - 0.82) / 0.10)
182                };
183                g.set(lx, y, lz, col);
184            }
185
186            // Agua: llena lo vacío bajo el nivel del mar (lagos/océano).
187            if h < sea {
188                for y in (h + 1)..=sea.min(dy - 1) {
189                    let depth = (sea - y) as f32 / sea.max(1) as f32;
190                    g.set(lx, y, lz, mix(shallow, deep, depth));
191                }
192            }
193        }
194    }
195
196    // Árboles: roots barridos sobre la ventana padeada (±2) para que las copas
197    // de árboles rooteados justo afuera asomen dentro, y las de borde se recorten.
198    let leaf_base = [40, 96, 44];
199    let leaf_hi = [62, 124, 58];
200    let trunk = [96, 64, 38];
201    for lz in -2..dz as i32 + 2 {
202        for lx in -2..dx as i32 + 2 {
203            let (wx, wz) = (ox + lx, oz + lz);
204            let h = h_at(lx, lz);
205            let fh = h as f32 / dy as f32;
206            if h <= sea + 1 || fh < 0.33 || fh > 0.56 {
207                continue;
208            }
209            if hash2(wx, wz, seed ^ 0x7717) > 0.016 {
210                continue;
211            }
212            let th = 4 + (hash2(wx, wz, seed ^ 0x33) * 3.0) as u32;
213            let top = (h + th).min(dy - 1);
214            // Tronco (sólo si la columna cae dentro de la ventana).
215            if (0..dx as i32).contains(&lx) && (0..dz as i32).contains(&lz) {
216                for y in (h + 1)..=top {
217                    g.set(lx as u32, y, lz as u32, trunk);
218                }
219            }
220            // Copa: elipsoide de hojas, recortada a la ventana.
221            let r = 2i32;
222            let cy = top as i32;
223            for dz2 in -r..=r {
224                for dy2 in -r..=(r + 1) {
225                    for dx2 in -r..=r {
226                        if dx2 * dx2 + dy2 * dy2 + dz2 * dz2 > r * r + 1 {
227                            continue;
228                        }
229                        let (gx, gy, gz) = (lx + dx2, cy + dy2, lz + dz2);
230                        if (0..dx as i32).contains(&gx)
231                            && (0..dy as i32).contains(&gy)
232                            && (0..dz as i32).contains(&gz)
233                        {
234                            // Jitter de hoja por mundo (estable entre ventanas).
235                            let v = hash2((wx + dx2) * 13 + gy, (wz + dz2) * 7 + gy, seed ^ 0x55) * 0.25;
236                            g.set(gx as u32, gy as u32, gz as u32, mix(leaf_base, leaf_hi, v));
237                        }
238                    }
239                }
240            }
241        }
242    }
243}
244
245/// Genera un paisaje voxel en un grid `dim = [dx, dy, dz]` (con `y` arriba),
246/// determinista por `seed`. El terreno ocupa hasta ~`0.85·dy` de alto; el nivel
247/// del mar queda en `~0.30·dy`. Devuelve un [`VoxelGrid`] de `llimphi-3d` listo
248/// para `VoxelRenderer`/`Scene3d`. Equivale a [`fill_terrain_window`] con
249/// `origin = [0, 0]` (con el dirty reseteado: el grid es nuevo, el primer upload
250/// es completo de todos modos).
251pub fn terrain(dim: [u32; 3], seed: u32) -> VoxelGrid {
252    let mut g = VoxelGrid::new(dim);
253    fill_terrain_window(&mut g, [0, 0], seed);
254    g.reset_dirty();
255    g
256}
257
258#[cfg(test)]
259mod tests {
260    use super::*;
261
262    /// `column_height` es función PURA de mundo: el mismo `(wx, wz)` da la misma
263    /// altura aunque el origen de ventana cambie. Sin esto el streaming tendría
264    /// costuras (escalones en los bordes de ventana).
265    #[test]
266    fn column_height_es_independiente_de_la_ventana() {
267        let dim = [96, 48, 96];
268        for &(wx, wz) in &[(0, 0), (37, -12), (-200, 5), (1000, -1000)] {
269            let a = column_height(wx, wz, dim, 7);
270            let b = column_height(wx, wz, dim, 7);
271            assert_eq!(a, b, "determinista en ({wx},{wz})");
272            assert!(a < dim[1], "altura dentro del mundo");
273        }
274    }
275
276    /// Dos ventanas que solapan en mundo coinciden voxel-a-voxel en la zona
277    /// común: una columna de mundo se ve igual desde cualquier ventana. Es la
278    /// prueba dura de continuidad del streaming (sin GPU).
279    #[test]
280    fn ventanas_solapadas_coinciden_en_la_zona_comun() {
281        let dim = [64, 40, 64];
282        let seed = 4242;
283        // Ventana A en origen (0,0); ventana B desplazada (+16,+16). Solapan en
284        // el rango de mundo x,z ∈ [16, 64).
285        let mut a = VoxelGrid::new(dim);
286        fill_terrain_window(&mut a, [0, 0], seed);
287        let mut b = VoxelGrid::new(dim);
288        fill_terrain_window(&mut b, [16, 16], seed);
289
290        let mut comparados = 0u32;
291        for wz in 16..64u32 {
292            for wx in 16..64u32 {
293                for y in 0..dim[1] {
294                    // mundo → local de cada ventana.
295                    let va = a.get(wx, y, wz).unwrap();
296                    let vb = b.get(wx - 16, y, wz - 16).unwrap();
297                    assert_eq!(va, vb, "discrepan en mundo ({wx},{y},{wz})");
298                    comparados += 1;
299                }
300            }
301        }
302        assert!(comparados > 10_000, "se compararon columnas de verdad");
303    }
304}