Biolume

Simulador de evolución bioluminiscente. Criaturas autónomas evolucionan estrategias de comunicación mediante neuroevolución (NEAT) en un ecosistema día/noche con dinámica de poblaciones real.

Características

• ECS — motor de entidades-componentes propio (sin dependencias externas)
• Boids con parentesco — separación kin/alien, alineación, cohesión producen bandadas emergentes
• Comunicación luminosa — órganos emisores de luz en color RGB con ciclos de pulso
• Sincronización de Kuramoto — acoplamiento de fases entre parientes → sincronía espontánea tipo luciérnaga
• Territorialidad — sesgo posicional suave por especie → segregación espacial emergente
• Ciclo día/noche — luz ambiental sinusoidal que regula energía de fotovoros
• Árbol filogenético — linaje rastreado por generación; exportable como JSON
• Métricas científicas — diversidad Shannon H', índice Kuramoto, distancia genética, varianza fenotípica, consanguinidad F, presión competitiva
• Población a escala — hasta 1 500 criaturas simultáneas (tope navegador práctico)

---

Arquitectura

biolumen/
├── crates/
│   ├── core/       # ECS, física boids, loop de simulación, ciclo día/noche
│   ├── neat/       # Neuroevolución NEAT (genoma, especiación, cruce, mutación)
│   ├── physics/    # Grilla de luz, arrays sensoriales, detección de patrones
│   └── wasm/       # Bindings wasm-bindgen → expone BiolumenApp a JavaScript
├── server/         # Servidor de persistencia (CRDT, sincronización de estado)
├── web/
│   ├── index.html  # UI completa: canvas 2D, controles, métricas, gráficas
│   └── pkg/        # Paquete WASM generado (ignorado en git)
└── shaders/        # Shaders WGSL (glow, bloom, grilla de luz)

---

Prerrequisitos

Todas las plataformas

Herramienta	Versión mínima	Instalación
Rust + Cargo	1.75+	https://rustup.rs
Target WASM	—	rustup target add wasm32-unknown-unknown
wasm-bindgen CLI	0.2.125	ver abajo

Instalar wasm-bindgen-cli con la versión exacta del workspace:

cargo install wasm-bindgen-cli --version 0.2.125

Windows (requerido)

El proyecto usa el toolchain GNU (no MSVC). Necesitas MinGW-w64 vía MSYS2:

1. Instala MSYS2 desde https://www.msys2.org/
2. En la terminal MSYS2 MINGW64:

   pacman -S mingw-w64-x86_64-gcc

3. Agrega al PATH del sistema:

   C:\msys64\mingw64\bin
   C:\Users\<tu-usuario>\.cargo\bin
   

4. Configura el toolchain GNU en Rust:

   rustup default stable-x86_64-pc-windows-gnu

Sin MinGW el target wasm32-unknown-unknown no compila en Windows porque el linker MSVC no puede procesar el formato de objeto WASM.

---

Compilar y ejecutar

1. Compilar WASM

cargo build --target wasm32-unknown-unknown -p biolume-wasm --release

2. Generar el paquete web

wasm-bindgen target/wasm32-unknown-unknown/release/biolume_wasm.wasm \
  --target web \
  --out-dir web/pkg

En Windows (PowerShell):

wasm-bindgen.exe "target\wasm32-unknown-unknown\release\biolume_wasm.wasm" `
  --target web `
  --out-dir "web\pkg"

3. Servir localmente

Cualquier servidor estático funciona:

# Python
python -m http.server 8080 --directory web/

# Node.js
npx serve web/ -p 8080

# Rust (servidor incluido)
cargo run -p biolume-server

Abrir: http://localhost:8080

4. Ejecutar tests

cargo test --workspace --exclude biolume-wasm

---

Configuración de población

Objetivo de población (UI)

El slider Population Target en el panel lateral controla cuántas criaturas se generan al reiniciar el ecosistema. Rango: 50–1 500 criaturas.

• El target toma efecto en el siguiente Reset Ecosystem o al elegir un preset.
• La población real oscila alrededor del target por dinámica ecológica (nacimientos, muertes por inanición/vejez).
• El límite duro del motor es MAX_POPULATION = 1500. Intentar superar ese valor no genera error; la reproducción simplemente se detiene.

Cambiar los límites en el código

crates/core/src/simulation.rs, líneas 27–28:

const MAX_POPULATION: usize = 1500;  // tope duro — reproducción se bloquea aquí
const MIN_POPULATION: usize = 15;    // piso de emergencia — replenish() activa

crates/core/src/simulation.rs, impl Default for SimConfig:

population_target: 800,  // valor inicial por defecto

Después de cambiar estos valores, recompila con los pasos de la sección anterior.

Presets de escenario

Preset	Population target	Descripción
Default	800	Ecosistema balanceado (mixto fotovoro/herbívoro)
Firefly	800	Rango de frecuencia estrecho → sincronía Kuramoto
Deep Sea	500	Oscuridad casi total; herbívoros sociales dominan
Coral Reef	1 200	Alta mutación + kin estrecho → máxima diversidad

Para modificar un preset, edita SimConfig::firefly(), SimConfig::deep_sea() o SimConfig::coral_reef() en simulation.rs.

---

Controles de la UI

Control	Efecto
Speed	Multiplicador de velocidad de simulación (0.25×–4×)
Population Target	Número objetivo de criaturas (50–1 500)
⏸ Pause / ▶ Resume	Pausa/reanuda el loop de simulación
↺ Reset Ecosystem	Reinicia con el escenario y configuración actuales
Seed	Semilla determinista para reproducibilidad exacta
Mutation Rate	Tasa de mutación de color en reproducción (0–50%)
Kin Threshold	Umbral de distancia de color para considerarse "pariente"
Freq. pulso min/max	Rango de frecuencia de pulso luminoso (Hz)
Fracción herbívoros	Proporción de criaturas herbívoras al nacer
Vista: Bio / Linaje / Especie	Modo de renderizado del canvas

Modos de vista

• 🔆 Bio — Bioluminiscencia en tiempo real con partículas de muerte
• 🌳 Linaje — Mapa de calor de profundidad genealógica: azul (G0=fundador) → rojo (generación más antigua)
• 🎨 Especie — Identidad por color base: blobs territoriales + vínculos kin

---

Exportar datos

CSV de historia evolutiva

Botón ⬇ Descargar CSV — descarga biolume_history_seedX.csv con columnas:

tick, population, births_total, deaths_total, deaths_5s, generation,
species_count, shannon_H, honest_signal_r, phase_coherence,
genetic_distance, mean_energy, max_lineage_depth,
phenotypic_var, inbreeding_F, competitive_pressure

Árbol filogenético JSON

Botón 🌳 Exportar Árbol JSON — descarga biolume_tree_seedX_genY.json:

{
  "meta": { "tick": 12480, "gen": 3, "seed": 42, "pop": 784 },
  "nodes": [
    { "lid": 142, "parent": 67, "depth": 5, "x": 423.1, "y": 301.8,
      "r": 0.812, "g": 0.234, "b": 0.041 }
  ]
}

Cada nodo es una criatura viva. lid = ID único de linaje, parent = lid del progenitor (o null si es fundador), depth = generaciones desde el fundador.

---

Métricas científicas

Métrica	Descripción	Rango
Shannon H'	Diversidad de especies (clusters de color)	0 = monocultura, 2+ = alta diversidad
Honest Signal r	Correlación energía↔brillo (principio Zahavi)	−1–1
Sync Index	Coherencia de fase Kuramoto (luciérnagas)	0 = aleatorio, 1 = sincrono
Genetic Dist	Distancia de color pairwise media	0–1.73
Mean Energy	Bienestar medio de la población	0–1
Lineage Depth	Máxima profundidad genealógica	generaciones
Varianza F.	Dispersión fenotípica de color	0 = clones, ~0.08 = máxima
Consanguinidad F	Fracción de pares kin con color casi idéntico	0–1
Presión comp.	Vecinos alien promedio por criatura	0–∞

---

Sprints implementados

Sprint	Característica
0	Monorepo, toolchain, wasm-bindgen
1	ECS, boids, grilla espacial, loop de simulación
2	Shaders WGSL (glow, bloom, grilla de luz), ciclo día/noche
3	NEAT (genoma, especiación, cruce, mutación, motor de evolución)
4	Grilla de propagación de luz, 24 sensores, patrones de comunicación
5	UI web (canvas 2D, controles, overlay de stats, gráficas)
6	CRDT de estado (registros LWW, log de generación grow-only)
7	CI/CD (GitHub Actions: test → build WASM → deploy GH Pages)
8	Sincronización Kuramoto, territorialidad, métricas científicas, linajes, export JSON