# Looping Programming Language — Official Syntax & Reference Guide
> **Looping v1.1 — Production Release (Architecture 3.0A Quantum 3D Synthesis & C++17 Native Engine)**  
> *Release Channels: **Looping** (Production) • **Omega Looping** (Release Candidate / RC) • **Alpha! Looping** (Super Experimental)*  
> *Developed by Coki Studios & Holo Entertainment*  
> *Target Hardware & OS: Shine Loop Console • Holo Looping OoS (POSIX / macOS Universal / Linux Gaming Subsystem)*  
> *Historical Architecture Series: 3.0A, 2.8A, 2.7A, 2.6A, 2.5A, 2.0A, 1.0A*

---

## 1. Introducción, Nomenclatura de Canales & Filosofía de Diseño
**Looping** (extensiones de archivo `.loop` y `.ruup`) es un lenguaje de programación moderno, expresivo y de alto rendimiento diseñado para la creación ágil de videojuegos 2D y 3D, aplicaciones gráficas interactivas, ciencia de datos, criptografía segura, síntesis de audio en tiempo real y lógica multimedia.

### Nomenclatura Oficial de Lanzamientos
Looping se distribuye bajo tres canales oficiales seleccionables con `--channel=<prod|omega|alpha>`:
* ⚡ **`Looping`** *(Producción / Stable)*: Versión oficial estable lista para entornos comerciales (**actual: `v1.1` / `Arch 3.0A`**).
* 🧬 **`Omega Looping`** *(Release Candidate / RC)*: Candidatas a lanzamiento con congelación funcional y validación previa a producción (`v1.1-omega`).
* 🧪 **`Alpha! Looping`** *(Super Experimental)*: Builds súper experimentales de laboratorio y funciones bleeding-edge (`v1.1-alpha`).

Con el lanzamiento de **Looping v1.1** (impulsado por la arquitectura **3.0A Quantum 3D Synthesis + Invis. Compile LPBN v3.0A Binary Pipeline**), Looping consolida su sintaxis expresiva (`let`, `mut`, `val`, `:=`, `fn`, `match`, `|>`, `invis. compile`, `invis.*`, `ui.*`, `spawn.*`, `scene3d.*`, `spawn3d.*`, `math3d.*`, `physics3d.*`, `csid.*`, `csms.*`, `audio.*`, `crypto.*`, `py!`), manteniendo un rendimiento nativo en C++17 de **< 0.5 ms**, **70/70 pruebas unitarias** y cero dependencias de Node.js.

Las versiones de arquitectura quedan catalogadas bajo la serie (**3.0A**, **2.8A**, **2.7A**, **2.6A**, **2.5A**, **2.0A**, **1.0A**).

### Transición de Node.js a C++17 Nativo (Hito del 3 de Octubre de 2026)
Looping comenzó como un prototipo experimental interpretado en JavaScript / Node.js (`bin/looping.js` en la serie 1.0A). El **3 de octubre de 2026** (Commit `67a72391`), el motor fue completamente reescrito en **C++17 nativo**, eliminando el entorno V8, reduciendo los tiempos de arranque de ~120 ms a **< 0.5 ms**, la memoria de 45 MB a **< 2.8 MB RSS**, y produciendo binarios universales sin dependencias de Node.js para macOS (`arm64`/`x86_64`) y Linux.

---

## 2. Compilación y Ejecución del Motor C++

### Binario Precompilado Universal
El ejecutable nativo compilado reside directamente en el repositorio (`arm64` + `x86_64`):
```bash
./bin/looping [opciones] [archivo.loop]
```

### Comandos de la CLI
| Comando | Descripción |
| :--- | :--- |
| `looping <archivo.loop\|.bin>` | Ejecuta un archivo de código `.loop`, `.ruup` o binario compilado (`LPBN v3.0A`) |
| `looping invis <archivo.loop> [-o out.bin] [--target <ui>] [--compact]` | Compila un `.loop` a un archivo binario sellado (`LPBN v3.0A` standalone o compacto `.loopb`) |
| `looping guide [--export <ruta.md>]` | Imprime o exporta la Guía Completa de Aprendizaje de Looping Code (`LOOPING_LEARNING_GUIDE.md`) |
| `looping --gui <archivo.loop>` | Ejecuta el script abriendo la ventana gráfica interactiva |
| `looping --native <archivo.loop>` | Ejecuta el script sintetizando una ventana nativa del SO (sin HTML5) |
| `looping compile <archivo.loop> --target <shine_ui\|xui\|flui\|c2\|invis> [-o out]` | Compila el script a binario `LPBN v3.0A` para una arquitectura de interfaz nativa |
| `looping check <archivo.loop\|.bin>` | Analizador estático recursivo de sintaxis y reporte de métricas AST en microsegundos |
| `looping ast <archivo.loop\|.bin>` | Visualiza el árbol sintáctico abstracto (AST) jerárquico completo del script o binario |
| `looping fmt <archivo.loop> [--write]` | Formatea y normaliza la indentación de un archivo `.loop` |
| `looping doc [topic]` | Manual de referencia integrado (`syntax`, `math`, `collections`, `crypto`, `csv`, `datetime`, `regex`, `ui`, `invis`) |
| `looping bench` | Ejecuta el benchmark de rendimiento de la máquina virtual nativa C++17 |
| `looping doctor` | Verifica el estado del motor C++, `Invis. Compile`, perfiles de UI, criptografía e interoperabilidad Python |
| `looping repl` | Inicia la consola interactiva (REPL) con comandos `vars`, `funcs`, `bench`, `reset` |
| `looping preview3d <archivo.loop>` | Renderiza la escena 3D en viewport Z-Buffer TrueColor en la terminal |
| `looping eval "<code>"` | Evalúa una instrucción o bloque de código en línea |
| `looping test` | Ejecuta la suite de verificación unitaria (**70/70 pruebas**) |
| `looping --channel <alpha\|omega\|prod>` | Selecciona canal (`Alpha! Looping`, `Omega Looping` RC o `Looping` Prod) |
| `looping --version` | Muestra la versión y canal del motor nativo (`Looping v1.1 / Arch 3.0A`) |
| `looping --help` | Despliega el menú de ayuda |

---

## 3. Declaración de Variables y Tipos (`let`, `mut`, `val`, `:=`)

Looping ofrece una sintaxis moderna y tipificada para declaración de estados y mutabilidad:

```loop
// Constantes e inmutables
let hero = "Angel Helium";
val max_hp = 250;

// Variables mutables
mut hp = 100;
mut energy = 45.5;

// Declaración rápida estilo Walrus (:=)
xp := 1500;
level := 12;

// Operadores de incremento y shorthand
level++;
hp += 25;
energy *= 1.2;
```

*(Por compatibilidad retroactiva, la sintaxis heredada `set x to 10` y `set x = 10` sigue funcionando).*

---

## 4. Funciones de Expresión y Bloque (`fn`)

### Funciones Flecha (One-line Arrow Functions)
```loop
fn add(a, b) => a + b;
fn compute_shield(base, lvl) => base * 1.5 + (lvl * 10);

val shield = compute_shield(40, level);
```

### Funciones en Bloque con Retorno (`return` / `->`)
```loop
fn evaluate_rank(points) {
    if (points >= 5000) {
        return "S-Rank Master";
    }
    return "Veteran Guard";
}

let current_rank = evaluate_rank(xp);
```

---

## 5. Bucles Únicos (`loop`, `for..in`, `while`)

### Bucle Contador (`loop (N)`)
Inyecta automáticamente la variable de índice `i`:
```loop
loop (5) {
    out($"  -> Pulso de sincronización: {i}");
}
```

### Bucle de Rango (`for (var in start..end)`)
```loop
for (step in 0..10) {
    out($"Procesando paso #{step}");
}
```

### Bucle de Condición (`while`) y Bucle Infinito (`loop`)
```loop
while (hp < max_hp) {
    hp += 10;
    if (hp >= max_hp) break;
}

loop {
    out("Bucle continuo...");
    break;
}
```

---

## 6. Control de Flujo: Condicionales

### Condicionales en Bloque (`if / else`)
```loop
if (hp >= 100) {
    out("[STATUS] Armadura sobrecargada.");
} else if (hp >= 50) {
    out("[STATUS] Armadura estable.");
} else {
    out("[ALERT] Daño crítico!");
}
```

### Condicional en Línea con Flecha (`->` / `=>`)
```loop
if (shield > 100) -> out("[SHIELD] Campo de deflexión activo");
```

---

## 7. Operador Pipeline (`|>`)

Permite encadenar transformaciones de datos de izquierda a derecha de forma fluida:
```loop
val sqrt_val = 81 |> math.sqrt;
$"[PIPELINE] Raíz calculada: {sqrt_val}" |> out;
```

---

## 8. Puente con Python (`pyloop`, `pysnippet`, `runpy`, `py!`)

### PyLoop Snippets & Ejecución (`from pyloop import snippets runpy`)
Permite importar el subsistema `pyloop` y capturar fragmentos de código Python puros como snippets nombrados para ejecutarlos dinámicamente con `runpy`:

```loop
from pyloop import snippets runpy
define app "Test" version 1.0
      insert pysnippet as sn1:
         print("Hello World!")
      runpy(sn1)
```

**Salida en consola:**
```text
[FUNC RUNPY] Executing sn1...
Hello World!
```

Los snippets pueden contener múltiples líneas, funciones, bibliotecas de Python, y acceden bidireccionalmente a las variables de Looping mediante `looping_vars` y `looping_set(clave, valor)`:
```loop
from pyloop import snippets, runpy

set factor = 10
insert pysnippet as calc_score:
    base = looping_vars.get("factor", 1)
    result = base * 25 + 100
    looping_set("calculated_score", result)

runpy(calc_score)
print "Score recibido:", calculated_score
```

### Macro en línea (`py!`)
```loop
val crit = py!(math.sqrt(64) * 1.5);
val orbit = py!(round(math.pi * 10, 3));
```

### Bloque multilínea con sincronización bidireccional
```loop
py! {
    import math
    current_lvl = looping_vars.get('level', 1)
    calculated_xp = int(current_lvl * 250 + math.pow(current_lvl, 2))
    
    // Guardamos de regreso en Looping
    looping_set('target_xp', calculated_xp)
}

out($"[SYNC] Target XP sincronizado desde Python: {target_xp}");
```

---

## 9. Directivas de UI Glassmorphism (`ui.*`)

Reemplazan la prosa en inglés por llamadas estructuradas con parámetros nombrados o posicionales:

```loop
// Tarjetas de estado con desenfoque holográfico
ui.card(at: (20, 20), size: (760, 60), title: "STATUS // SYSTEM", text: "Pipeline: 60 FPS Low-Latency");

// Botones interactivos con degradado neón
ui.btn(at: (40, 255), text: "EJECUTAR HYPERDRIVE", action: "hyper_boost");

// Entradas de texto interactivas
ui.input(at: (40, 200), size: (320, 40), placeholder: "Ingresa comando...", bind: "terminal_cmd");
```

*(También se acepta la sintaxis con anotación `@ui::card(...)` o `@ui::btn(...)`).*

---

## 10. Entidades de Videojuego y Físicas 2D (`spawn.*`)

```loop
// Plataformas físicas estáticas
spawn.platform(at: (420, 310), size: (350, 16), color: "#38bdf8");

// Monedas / Estrellas coleccionables
spawn.coin(at: (520, 250), points: 500);

// Sprites de jugador y enemigos con físicas a 60 FPS
spawn.sprite("Hero", at: (460, 240), size: (34, 46), color: "#6366f1");

// Indicador dinámico Bubbly Dot
spawn.bubbly("System Active // Diamond", state: "music");
```

---

## 11. Audio y Partículas (`audio.*`, `fx.*`)

```loop
// Generador de tono de hardware (frecuencia Hz, duración ms)
audio.tone(587, 80);
audio.tone(880, 100);

// Explosión de partículas FX con física de gravedad
fx.particles(at: (460, 240), color: "#38bdf8");
```

---

## 12. Configuración de Ventana y Aplicación

```loop
@app("CyberShineCore", "2.5") {
    window("CyberShine OS // Looping Native", 800, 520);
    theme("cyber_dark");
    profile("xui");
}
```

---

## 13. Ejemplo Completo (`signature_demo.loop`)

```loop
// ═══════════════════════════════════════════════════════════════
// ♾️ [LOOPING v2.5] Signature Syntax Showcase
// Holo Entertainment (Coki Studios)
// ═══════════════════════════════════════════════════════════════

import loop.engine as engine;
use python "math";

@app("CyberShineCore", "2.5") {
    window("CyberShine OS // Looping Native", 800, 520);
    theme("cyber_dark");
    profile("xui");

    let hero = "Angel Helium";
    mut hp = 100;
    val max_hp = 250;
    level := 12;

    level++;
    hp += 25;

    out($"[INIT] Pilot: {hero} | Level: {level} | HP: {hp}/{max_hp}");

    fn compute_shield(base, lvl) => base * 1.5 + (lvl * 10);
    val shield_rating = compute_shield(40, level);

    val sqrt_val = 81 |> math.sqrt;
    $"[PIPELINE] 81 piped into math.sqrt => {sqrt_val}" |> out;

    val py_calc = py!(round(math.pi * 10, 3));
    out($"[PYTHON MACRO] Pi scaled: {py_calc}");

    if (hp >= 120) -> out("[STATUS] Armor supercharged & ready for battle.");

    for (step in 0..3) {
        out($"  -> [TELEMETRY] Sensor array ping #{step} OK");
    }

    loop (2) {
        out("  -> [HEARTBEAT] Sub-millisecond tick verified");
    }

    ui.card(at: (20, 20), size: (760, 60), title: "CYBERSHINE CORE", text: "Kernel: Holo Looping OoS");
    ui.btn(at: (40, 255), text: "EJECUTAR HYPERDRIVE", action: "hyper_boost");

    spawn.platform(at: (420, 310), size: (350, 16), color: "#38bdf8");
    spawn.sprite("AngelPilot", at: (460, 240), size: (34, 46), color: "#6366f1");

    audio.tone(587, 80);
    fx.particles(at: (460, 240), color: "#38bdf8");

    out("[READY] CyberShine Core compilado y ejecutado en Looping v2.5!");
}
```


---

## 14. Compilación de Interfaces Nativas: Shine UI, XUI y flUI

Looping v2.5 incluye un compilador de perfiles de interfaz de usuario de hardware diseñado específicamente para el ecosistema **Shine Loop Console**, permitiendo adaptar el pipeline gráfico, la tasa de refresco (FPS) y los shaders de visualización a diferentes factores de forma y propósitos de uso:

### 🌟 Los 3 Perfiles de Interfaz de Usuario

| Perfil UI | Alias | Tasa de Refresco | Pipeline Gráfico | Shader Palette & Theme | Propósito / Dispositivo |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Shine UI** | `shine_ui`, `shine` | **60 FPS** | Shine APU Direct V-Sync | `frosted_aqua_a17` (`#00f5d4` / `#0284c7`) | Consola portátil insignia, carrusel 3D y cuadrícula de juegos |
| **XUI** | `xui`, `gama_x` | **240 FPS** | Direct-to-Vulkan (<0.2ms) | `cyber_neon_xui` (`#38bdf8` / `#082f49`) | HUD competitivo para esports, alta tasa de refresco ultra-rápida |
| **flUI** | `flui`, `foldable` | **120 FPS** | Fold-Aware Dynamic Engine | `aurora_indigo_fold` (`#c084fc` / `#ec4899`) | Dispositivos plegables, doble pantalla y tarjetas flotantes |

---

### Compilación desde la CLI de Looping

Puedes compilar cualquier script `.loop` especificando el flag `--target` o `-t`:

```bash
# Compilar el launcher del sistema para Shine UI (Handheld 60Hz)
./bin/looping compile sample_loop_projects/shine_launcher.loop --target shine_ui --output build/ShineLauncher_ShineUI

# Compilar para XUI (Esports 240Hz Direct-to-Vulkan)
./bin/looping compile sample_loop_projects/shine_launcher.loop --target xui --output build/ShineLauncher_XUI

# Compilar para flUI (Plegable / Dual-Screen 120Hz)
./bin/looping compile sample_loop_projects/shine_launcher.loop --target flui --output build/ShineLauncher_flUI
```

El compilador genera un binario ejecutable (`chmod +x`) con shebang `#!/usr/bin/env looping` y metadatos de arquitectura embebidos que puede ejecutarse directamente:

```bash
./build/ShineLauncher_ShineUI
# o mediante:
./bin/looping build/ShineLauncher_ShineUI
```

---

### Sintaxis en Código Fuente (.loop)

Dentro del código de Looping, puedes declarar o bloquear el target de UI con cualquiera de las siguientes formas declarativas:

```loop
// Directiva de compilación explícita
compile target "shine_ui"

// Forma de función funcional
target("xui")

// Macro decorador de arquitectura
@target("flui")
profile("shine_ui")
```

Al ejecutarse, el motor exporta automáticamente las variables de entorno de sistema correspondientes:
- `UI_PROFILE`: Código del perfil (`"shine_ui"`, `"xui"`, `"flui"`)
- `UI_NAME`: Nombre oficial de la arquitectura (`"Shine UI"`, `"XUI"`, `"flUI"`)
- `UI_THEME`: Tema de sombreador de cristal activo
- `UI_FPS`: Tasa de refresco objetivo (`60`, `240`, `120`)

---

## 15. Comparativa de Sintaxis (Antes vs. Ahora)

| Característica | Prosa en Inglés (Legacy v2.0) | Sintaxis de Firma Looping (v2.5) |
| :--- | :--- | :--- |
| **Variables** | `set player to "Angel"` | `let player = "Angel"` / `player := "Angel"` |
| **Mutables** | `set hp = 100` | `mut hp = 100`, `hp += 25`, `hp++` |
| **Funciones** | `function foo(x) { ... }` | `fn foo(x) => x * 2` / `fn foo(x) { ... }` |
| **Bucles** | `repeat 5 times { ... }` | `loop (5) { ... }` / `for (i in 0..5) { ... }` |
| **Condicional** | `if hp >= 20 do print "ok"` | `if (hp >= 20) -> out("ok")` |
| **Pipelines** | N/A | `81 \|> math.sqrt \|> out` |
| **Puente Python** | `set x to py: math.sqrt(64)` | `val x = py!(math.sqrt(64))` / `py! { ... }` |
| **UI Card** | `draw card at (20,20) with size...` | `ui.card(at: (20, 20), size: (760, 60), ...)` |
| **UI Button** | `draw button at (30,150) with text...` | `ui.btn(at: (30, 150), text: "Go", action: "act")` |
| **2D Entities** | `spawn sprite "Hero" at (10,10)...` | `spawn.sprite("Hero", at: (10, 10), color: "#fff")` |
| **Audio** | `play tone at 587 Hz for 80 ms` | `audio.tone(587, 80)` |

---

## 16. Novedades de Looping v2.6 (Pattern Matching, Stdlib Funcional, Crypto & UI Extendida)

### 16.1 Expresiones Ternarias (`? :`) y Null-Coalescing (`??`)
```loop
val tier = score >= 90 ? "DIAMOND" : "GOLD";
val active_theme = custom_theme ?? "frosted_aqua_a17";
```

### 16.2 Pattern Matching (`match`)
```loop
match rank_code {
    "S" => out("Grandmaster")
    "A" => out("Commander")
    _   => out("Recruit")
}
```

### 16.3 Rangos Inclusivos (`..=`), Paso (`step`) y `continue`
```loop
for (i in 1..=10 step 2) {
    if (i == 5) -> continue
    out($"Pulso impar: {i}")
}
```

### 16.4 Destructuring y Manejo de Errores (`try / catch / throw`)
```loop
let [first, second, third] = [100, 200, 300]
let (pos_x, pos_y) = (45, 90)

try {
    throw "OverheatFault"
} catch (err) {
    out($"[RECOVERY] Error capturado: {err}")
}
```

### 16.5 Biblioteca Estándar Funcional, Estadística y Criptográfica (`crypto.*`)
```loop
fn square(x) => x * x
fn is_even(x) => x % 2 == 0

val evens = [1, 2, 3, 4, 5, 6] |> filter(is_even) |> map(square)
val dedup = unique([1, 2, 2, 3, 1])
val flat  = flatten([[1, 2], [3, 4]])
val avg   = math.mean([10, 20, 30, 40])

// Criptografía nativa C++17 (cero dependencias externas)
val hash_hex = crypto.sha256("HoloOoS")
val b64      = crypto.base64_encode("ShineLoop")
val session  = crypto.uuid()
val room_key = crypto.csms_key("room_alpha")
```

### 16.6 Componentes UI Extendidos (`slider`, `toggle`, `progress` y Snippets en Botones)
```loop
draw slider at (10, 20) with label "Volumen" and min 0 and max 100 and val 75 and bind "vol"
draw toggle at (10, 70) with label "Modo Oscuro" and bind "dark_mode" checked
draw progress at (10, 110) with label "Batería" and val 90 and bind "batt"

insert button "Incrementar" with snippet:
    counter += 1
end
```

---

## 17. Novedades de Looping v2.8 Quantum Signature

### 17.1 Argumentos de Función por Defecto y Operador `%=`
```loop
fn greet_pilot(name, rank = "Commander", bonus = 50) => $"{rank} {name} (+{bonus})"
val p1 = greet_pilot("Jerix")                     // "Commander Jerix (+50)"
val p2 = greet_pilot("Jerix", "Admiral", 200)     // "Admiral Jerix (+200)"

mut rem = 29
rem %= 6                                          // 5
```

### 17.2 Pattern Matching Multi-Patrón (`|`) y por Rangos (`..=` / `..`)
```loop
match tier_code {
    "S" | "SS" | "SSS" => out("🏆 Rango Maestro Cuántico")
    "A" | "B"          => out("⭐ Rango Comandante")
    _                  => out("🎮 Rango Estándar")
}

match score {
    90..=100 => out("Calificación: A+")
    80..90   => out("Calificación: B")
    _        => out("Calificación: C")
}
```

### 17.3 Llamadas de Método sobre Variables (`var.method()`)
Cualquier función de cadenas o colecciones puede invocarse directamente con notación de punto sobre la variable:
```loop
let raw_title = "   coki studios shine   "
val clean_title = raw_title.trim()
val final_title = clean_title.upper()             // "COKI STUDIOS SHINE"

mut dyn_list = [40, 10, 30]
dyn_list.push(20)
val sorted_list = dyn_list.sort()                 // [10, 20, 30, 40]
val total_items = sorted_list.len()               // 4
```

### 17.4 Subsistema Nativo CSV (`csv.*`) y DateTime (`datetime.*` / `time.*`)
```loop
val csv_raw = "city,altitude,hub\nBogota,2640,true\nChia,2564,true"
val rows    = csv.parse(csv_raw)                  // Lista 2D de filas
val records = csv.parse_maps(csv_raw)             // Lista de Maps indexados por cabecera
val out_csv = csv.stringify(rows)

val now_iso = datetime.iso()                      // "2026-10-23T02:35:00Z"
val dt_info = datetime.now()                      // Map {year, month, day, hour, minute, second, iso}
val fmt_str = datetime.format(1767225600, "%Y-%m-%d")
val ns_tick = time.nanos()
```

### 17.5 Álgebra Vectorial, Estadística Avanzada y Colecciones Funcionales
```loop
// Álgebra lineal y estadística (math.*)
val dot_prod = math.dot([1, 2, 3], [4, 5, 6])     // 32
val l2_norm  = math.norm([3, 4])                  // 5
val dist_2d  = math.distance((0, 0), (6, 8))      // 10
val grid     = math.linspace(0, 10, 5)            // [0, 2.5, 5, 7.5, 10]
val p90      = math.percentile([10, 20, 30, 40, 50], 90)

// Colecciones de orden superior
fn parity(n) => n % 2 == 0 ? "even" : "odd"
val grouped = group_by([1, 2, 3, 4, 5, 6], parity)
val parts   = partition([10, 60, 20, 80], is_big)
val first_3 = take([1, 2, 3, 4, 5], 3)
val rest_2  = drop([1, 2, 3, 4, 5], 3)
val freqs   = frequencies(["a", "b", "a", "c", "a"])
```

### 17.6 Criptografía Extendida v2.8 (`crc32`, `constant_time_eq`, `csms_payload`)
```loop
val crc_hex  = crypto.crc32("LoopingEngine")
val hmac_hex = crypto.hmac_sha256("secret_key", "message_payload")
val safe_cmp = crypto.constant_time_eq(hmac_hex, expected_hmac)
val csms_pkt = crypto.csms_payload("room_sabana", "Hola Cota") // 🔒 enc:v1:<iv>:<ciphertext>
```

---

## 18. Experiencia Declarativa SwiftUI en Looping (v2.9 Apple Ecosystem Bridge)

Looping incorpora una experiencia de desarrollo de interfaces declarativas inspirada directamente en **SwiftUI** de Apple. Permite diseñar componentes reactivos, jerárquicos y encadenados con modificadores fluidos (`.padding()`, `.background()`, `.foregroundColor()`), visualizar vistas en vivo en la terminal mediante un Canvas TUI de alta fidelidad, y transpilar o compilar directamente a código **Swift 6** nativo listo para Xcode (`Forkar.iOS`, macOS, watchOS o visionOS).

### 18.1 Sintaxis de Vistas y Componentes Declarativos
```loop
view DashboardView {
    @state count = 100
    @state is_active = true
    @state username = "Jerix"

    VStack(spacing: 16) {
        HStack(spacing: 10) {
            Image(systemName: "sparkles")
                .foregroundColor(.cyan)
            Text("Coki Studios Quantum")
                .font(.title2)
                .fontWeight(.bold)
                .foregroundColor(.cyan)
            Spacer()
            Badge("Live 120Hz")
        }

        Divider()

        VStack(spacing: 8) {
            Text("Telemetría de Sistema")
                .font(.headline)
            Text("Operaciones procesadas: $count")
                .font(.subheadline)
                .foregroundColor(.gray)
        }
        .padding(12)
        .background(.ultraThinMaterial)
        .cornerRadius(10)

        HStack(spacing: 12) {
            Button("Disminuir") {
                count -= 10
            }
            .buttonStyle(.bordered)

            Button("Incrementar") {
                count += 25
            }
            .buttonStyle(.borderedProminent)
        }

        Toggle("Activar ProMotion E2EE", isOn: $is_active)
            .padding(10)

        ProgressView(value: 0.85)
            .tint(.cyan)
    }
    .padding(20)
    .frame(width: 440)
}
```

### 18.2 Catálogo de Contenedores y Controles
| Categoría | Constructores en Looping |
|---|---|
| **Contenedores de Disposición** | `VStack(spacing: N, alignment: .leading)`, `HStack(spacing: N)`, `ZStack`, `List`, `ScrollView`, `Section`, `Group`, `ForEach` |
| **Controles de Texto e Imagen** | `Text("...")`, `Image(systemName: "...")`, `Image("asset.png")`, `Badge("...")` |
| **Interactividad y Entrada** | `Button("Label") { action }`, `TextField("Placeholder", text: $var)`, `Toggle("Label", isOn: $var)`, `Slider(value: $var)` |
| **Indicadores y Separadores** | `ProgressView(value: N)`, `Spacer()`, `Divider()`, `Circle()`, `Rectangle()`, `RoundedRectangle(cornerRadius: N)` |

### 18.3 Modificadores Fluidos Encadenados (Dot Modifiers)
- `.font(.largeTitle | .title | .headline | .subheadline | .body | .caption)`
- `.fontWeight(.bold | .semibold | .medium | .regular | .light)`
- `.foregroundColor(color)` / `.foregroundStyle(color)` / `.tint(color)`
- `.padding([amount])` / `.padding(.horizontal, N)`
- `.background(.ultraThinMaterial | .blue | Color("..."))`
- `.cornerRadius(radius)`
- `.frame(width: W, height: H)`
- `.shadow(radius: R, y: Y)`
- `.opacity(alpha)`
- `.buttonStyle(.bordered | .borderedProminent | .plain)`

### 18.4 Previsualización en Vivo en la Terminal (Canvas TUI)
Puedes inspeccionar cualquier componente SwiftUI directamente en la terminal con renderizado visual en caja simulada de dispositivo:
```bash
# Vista previa en vivo del Canvas SwiftUI
looping preview app.loop [NombreComponente]
```

### 18.5 Transpilación y Compilación Nativa a Swift / Mach-O
```bash
# Transpilar a código fuente Swift puro (.swift)
looping compile app.loop --target swiftui -o MyApp.swift

# Compilar directamente a binario Mach-O ejecutable para macOS (vía swiftc)
looping compile app.loop --target swiftui -o build/MyApp
```

### 18.6 Funciones del Módulo Stdlib `swiftui.*`
- `swiftui.components()`: Lista de nombres de vistas registradas.
- `swiftui.has_component("Name")`: Verifica existencia de una vista.
- `swiftui.preview("Name")`: Imprime el Canvas TUI en la terminal.
- `swiftui.transpile("Name")`: Genera y retorna el código fuente Swift como string.
- `swiftui.export("Name", "out.swift")`: Exporta el archivo `.swift` al disco.

---

## 19. Motor de Videojuegos 2D Quantum en Looping (60 FPS Native Graphics)

Looping v2.8+ incorpora un motor completo de videojuegos 2D diseñado para ejecutarse a **60 FPS** nativos con aceleración por hardware tanto en la web (`LoopingInterpreter`), en la consola POSIX/Win32 (`looping eval`), en el IDE hiOP y en **Holo Looping OoS**.

### 19.1 Ejemplo Completo de Nivel 2D
```loop
import loop.engine as game

define game "QuantumRunner2D" version 2.8:
    create window with title "Holo Quantum Arcade" and size (720, 420)
    set theme to "dark_neon"
    
    # ── Configuración de Mundo y Físicas ──
    game.world(width: 1400, height: 420)
    game.gravity(980)
    game.friction(0.82)
    game.lives(3)

    # ── Héroe Protagonista (Doble Salto, Dash, Disparo e Inercia) ──
    spawn.player(name: "Angel Helium", at: (100, 310), speed: 280, jump: 440, health: 100)

    # ── Maglev Plataforma Móvil & Plataformas Neón ──
    spawn.platform(at: (60, 330), size: (180, 18), color: "#6366f1")
    spawn.moving_platform(at: (280, 250), size: (140, 18), range: (220, 500), speed: 85, color: "#06b6d4")
    spawn.platform(at: (560, 190), size: (160, 18), color: "#8b5cf6")
    spawn.platform(at: (780, 260), size: (150, 18), color: "#6366f1")

    # ── Trampas Neón, Impulsores y Anillos de Salto ──
    spawn.spike(at: (430, 376), size: (44, 20), damage: 35)
    spawn.pad(at: (250, 376), power: 670)
    spawn.orb(at: (720, 170), power: 560, color: "#f59e0b")

    # ── Coleccionables & Kits de Salud ──
    spawn.coin(at: (340, 200), points: 100)
    spawn.coin(at: (620, 140), points: 150)
    spawn.coin(at: (840, 210), points: 200)
    spawn.heart(at: (590, 140), heal: 35)

    # ── Enemigo Autónomo (Derrotable por pisada o disparando) ──
    spawn.enemy(name: "CorruptedDrone", at: (800, 216), range: (780, 930), speed: 70, health: 30)

    # ── Portal de Victoria ──
    spawn.portal(at: (1180, 308), label: "NEON HUB")

    print("✔ Nivel cargado exitosamente a 60 FPS")
```

### 19.2 Catálogo de Entidades 2D y Directivas
| Entidad / Directiva | Sintaxis Declarativa | Descripción |
|---|---|---|
| **Jugador / Héroe** | `spawn.player(name, at, speed, jump, health)` | Protagonista con i-frames, doble salto, coyote time y dash. |
| **Plataforma Estática** | `spawn.platform(at, size, color)` | Superficie sólida con reborde neón y brillo volumétrico. |
| **Plataforma Móvil** | `spawn.moving_platform(at, size, range, speed)` | Maglev oscilante con arrastre inercial automático del jugador. |
| **Picos / Trampas** | `spawn.spike(at, size, damage)` | Dientes triangulares neón que infligen daño y rebote de impacto. |
| **Impulsor (Jump Pad)** | `spawn.pad(at, power, color)` | Base con resorte energético que impulsa al jugador hacia arriba. |
| **Anillo de Salto (Orb)** | `spawn.orb(at, power, color)` | Anillo gravitatorio que permite un impulso aéreo al presionarlo. |
| **Moneda / Estrella** | `spawn.coin(at, points)` | Coleccionable con animación de levitación y sonido de cristal. |
| **Kit de Salud (Heart)** | `spawn.heart(at, heal)` | Restaura vida con aura de chispas verdes y chime ascendente. |
| **Enemigo Autónomo** | `spawn.enemy(name, at, range, speed, health)` | Patrullero con IA de límites; derrotado al pisarlo o dispararle. |
| **Portal de Victoria** | `spawn.portal(at, label)` | Vórtice de meta con rotación neón y jingle de victoria. |
| **Gravedad y Fricción** | `game.gravity(val)` / `game.friction(val)` | Control de aceleración y desaceleración del mundo 2D. |
| **Cámara Suave** | `game.camera(follow: "player", smooth: 0.12)` | Seguimiento cinemático con sacudida (*screen shake*) en golpes. |

### 19.3 Mecánicas de Juego Pulidas
1. **Físicas y Plataformeo**:
   - **Coyote Time**: Ventana de 120 ms para saltar justo después de abandonar una plataforma.
   - **Jump Buffering**: Detección de salto previa al aterrizaje para una respuesta inmediata.
   - **Doble Salto Cuántico**: Salto secundario en el aire con partículas violeta.
   - **Dash**: Impulso horizontal de alta velocidad con rastro de movimiento.
   - **Squash & Stretch**: Deformación procedural del personaje en saltos y caídas.
2. **Combate y Enemigos**:
   - **Mecánica de Pisada**: Si el héroe cae sobre un enemigo desde arriba, lo neutraliza instantáneamente con rebote y +250 pts.
   - **Disparo Láser**: Disparo de proyectiles con trazas neón (`[Z]` o `[J]`).
   - **Invulnerabilidad Temporal**: Parpadeo defensivo de 1 segundo tras recibir impacto.
3. **Audio Sintetizado Retro-Futurista**:
   - Generación en tiempo real con Web Audio API (seno, triángulo, diente de sierra y ruido).
   - Efectos para salto, doble salto, dash, moneda, propulsor, pisada, daño, disparo, curación y victoria.
4. **Controles Universales**:
   - **Teclado**: `[A/D]` o Flechas para mover, `[W / Espacio]` saltar, `[Z / J]` disparar, `[X / K / Shift]` dash, `[R]` reiniciar.
   - **Gamepad**: Compatible directamente con mandos Bluetooth/USB (Xbox, PlayStation, Switch).
   - **Táctil**: Cruceta virtual D-Pad y botones [A] y [B] automáticos en dispositivos móviles y tabletas.

---

## 20. Motor de Videojuegos 3D Quantum (Perspectiva, Z-Buffer & Física 120Hz+)

A partir de **Arch 3.0A (Looping v1.2 Commercial)**, el motor incorpora capacidades completas de **juego 3D en tiempo real** tanto en el núcleo nativo C++17 (`Looping3D.hpp` + TUI Z-Buffer + Viewport OS nativo) como en el runtime interactivo Web (`looping_core.js` a 60/120 FPS con sub-stepping físico a 240Hz).

### 20.1 Ejemplo Declarativo de Juego 3D (`define game3d`)
```looping
use "loop-math-3d"
use "loop-game-plus"

define game3d "Cyber Odyssey 3D" version 3.0:
    game.lives(3)

    # 1. Mundo 3D, Cámara Spring-Arm, Iluminación Blinn-Phong y Física 240Hz
    scene3d.world(name: "Neo Horizon 3D", size: (200, 100, 260), sky: "cyber_night", fog: 0.0075, grid: true)
    camera3d.set(mode: "chase", pos: (0, 8.5, -16), target: (0, 2.2, 12), fov: 64, smooth: 0.14)
    light3d.directional(dir: (-0.42, -0.92, -0.35), color: "#f8fafc", intensity: 1.12)
    light3d.point(at: (0, 12, 24), color: "#38bdf8", intensity: 1.45, range: 60)
    physics3d.config(gravity: -28.0, substeps: 4, friction: 0.86, bounce: 0.08)

    # 2. Protagonista y Escenario 3D
    spawn3d.player("AngelPilot3D", at: (0, 2.2, 2), mesh: "hovercraft", speed: 26, jump: 17.5)
    spawn3d.box(at: (0, -0.6, 12), size: (16, 1.2, 30), color: "#4f46e5")
    spawn3d.moving_platform(at: (0, 0.5, 37), size: (8, 1.0, 9), axis: "x", range: (-7, 7), speed: 8.5)
    spawn3d.ring(at: (0, 4.2, 24), radius: 2.8, power: 36, color: "#00f5d4")
    spawn3d.crystal(at: (0, 2.5, 15), points: 200)
    spawn3d.enemy("ValkyrieDrone", at: (0, 3.2, 53), range: (-5.5, 5.5), speed: 9.5, health: 50)
    spawn3d.boss("OMEGA TITAN 3D", at: (0, 9.4, 132), range: (-9, 9), speed: 11, health: 450)
    spawn3d.portal(at: (0, 10.2, 145), radius: 3.4, label: "OMEGA NEXUS")
```

### 20.2 Directivas de Escena, Cámara, Luces y Entidades 3D
| Directiva / Entidad | Sintaxis | Descripción |
|---|---|---|
| **Mundo 3D** | `scene3d.world(name, size, sky, fog, grid, floor)` | Configura dimensiones `(X,Y,Z)`, skybox (`cyber_night`, `sunset_synth`, `nebula_void`, `arctic_holo`) y niebla exponencial. |
| **Cámara 3D** | `camera3d.set(mode, pos, target, fov, smooth)` | Modos `chase`, `orbit`, `fps` y `topdown` con warp dinámico de FOV al acelerar. |
| **Iluminación 3D** | `light3d.directional(...)` / `light3d.point(...)` | Sombreado Blinn-Phong con especular, luces puntuales atenuadas y luz ambiental. |
| **Física 120/240Hz** | `physics3d.config(gravity, substeps, friction, bounce)` | Sub-stepping rígido (`substeps: 4` = 240Hz efectivos a 60 FPS) sin *tunneling*. |
| **Jugador 3D** | `spawn3d.player(name, at, mesh, speed, jump)` | Malla procedural `hovercraft` con alabeo (*roll/pitch*), KERS Hyper-Dash y cañón de plasma. |
| **Geometría Sólida** | `spawn3d.box(at, size, color)` / `spawn3d.moving_platform(...)` | Plataformas arquitectónicas subdivididas y puentes Maglev en ejes `x`, `y` o `z`. |
| **Mallas Primitivas** | `spawn3d.sphere` / `cylinder` / `pyramid` / `torus` | Primitivas 3D procedurales con normales salientes y *backface culling*. |
| **Interactivos 3D** | `spawn3d.ring` / `crystal` / `heart` / `pad` / `checkpoint` / `hazard` | Anillos turbo toroidales, gemas octaédricas, propulsores, checkpoints y trampas 3D. |
| **IA & Jefes 3D** | `spawn3d.enemy(...)` / `spawn3d.boss(...)` / `spawn3d.portal(...)` | Drones centinela, titanes con proyectiles 3D dirigidos y estado *enraged*, y portal de meta. |

### 20.3 Álgebra Lineal, Cuaterniones y Física 3D Nativa (`math3d.*` & `physics3d.*`)
- **Álgebra y Proyección (`math3d.*`)**: `vec3`, `add`, `sub`, `scale`, `dot`, `cross`, `length`, `distance`, `normalize`, `lerp`, `quat_euler`, `quat_slerp`, `quat_rotate`, `mat4_trs`, `mat4_look_at`, `mat4_perspective`, `transform_point`, `project`.
- **Colisiones y Raycasting (`physics3d.*`)**: `collide_sphere`, `collide_aabb`, `collide_capsule_sphere`, `raycast_sphere`, `raycast_aabb`, `raycast_plane`, `raycast_scene`, `step_body`.
- **Herramientas CLI y REPL 3D**:
  - `./bin/looping preview3d sample_loop_projects/cyber_odyssey_3d.loop` — Rasterizador software TrueColor Z-Buffer directamente en la terminal ANSI.
  - `./bin/looping sample_loop_projects/cyber_odyssey_3d.loop --native` — Sintetiza y abre un viewport interactivo nativo del sistema operativo a 60 FPS.
  - `./bin/looping new MiJuego3D --template game3d` — Genera un proyecto 3D completo con arquitectura Arch 3.0A.
- **Controles 3D Universales**:
  - `[W/A/S/D]` o Flechas: Movimiento 3D relativo a la cámara • `[Espacio]`: Salto / Doble Salto (con *Coyote Time* y sombra proyectada en suelo) • `[Shift / X / K]`: Hyper-Dash 3D (barra KERS + warp FOV) • `[Z / J / Clic]`: Cañón de Plasma 3D • `[Q / E / Arrastrar Ratón]`: Órbita de cámara • `[C]`: Alternar cámara (`CHASE`, `ORBIT`, `FPS`, `TOPDOWN`).

---

## 21. Modelos Wavefront `.obj`, Interoperabilidad C# y Librería `loopize++`

A partir de **Looping v1.1 (Arch 3.0A + loopize++ 1.0)**, el motor 3D añade carga nativa de mallas `.obj`, scripting C# embebido sin dependencias (`CSharpBridge`) y el paquete híbrido de adiciones de juego **`loopize++`**.

### 21.1 Pipeline 3D Wavefront `.obj` (`obj3d.*` & `spawn3d.obj`)
- **Carga y Geometría**: `obj3d.load(path, alias)` / `obj3d.parse(raw_obj, alias)` / `obj3d.stats(alias)` / `obj3d.normalize(alias, target_extent)` / `obj3d.subdivide(alias)` / `obj3d.export(alias)`.
- **Spawn de Entidades `.obj`**:
  ```looping
  spawn3d.obj("Starfighter01", obj: "assets/models/starfighter.obj", at: (0, 2.2, 6), scale: 1.5, color: "#38bdf8", cs: "StarfighterPilot")
  ```
- **Modelos Incluidos en `assets/models/`**: `starfighter.obj`, `valkyrie_drone.obj`, `omega_titan.obj`, `cyber_crystal.obj`, `star_gate.obj`.
- **Raycasting y Colisión 3D Exacta**: `physics3d.raycast_scene(origin, dir)` ejecuta intersección triángulo por triángulo (Möller–Trumbore) sobre mallas `.obj`, y `physics3d.collide_entities(a, b)` valida AABB en espacio mundial.

### 21.2 Scripting C# Embebido (`use "csharp"`, `cs!`, `cssnippet`, `runcs`)
- **Bloques y Expresiones C#**:
  ```looping
  use "csharp"
  cs! {
      public class StarfighterPilot : MonoBehaviour {
          public float Shield = 100.0f;
          public void Start() => LoopingBridge.Set("cs_pilot_ready", true);
          public void Update(float dt) {
              Scene3D.Rotate("Starfighter01", 0.0f, dt * 45.0f, 0.0f);
              LoopingBridge.Set("cs_shield", Shield);
          }
      }
  }
  ```
- **API de Bridge y Exportación**:
  - `cs!(expr)` — Evalúa expresiones C# inline (`Mathf.Clamp`, `Vector3.Distance`, etc.).
  - `insert cssnippet as <nombre>: ... end` + `runcs(<nombre>)` — Define y ejecuta fragmentos C#.
  - `csharp.new(clase, id, entity)`, `csharp.call(id, method, ...)`, `csharp.step(dt)`, `csharp.get(id, field)`, `csharp.set(id, field, val)`.
  - `csharp.export("MiArena", "out.cs")` o compilación directa hacia `.cs` (`--target csharp`).
  - Detección automática de compilador externo `dotnet` / `mcs` + `mono` si está presente en el sistema.

### 21.3 Librería Híbrida `loopize++` (`use "loopize++"`)
Paquete híbrido (Loop + C++17 `LoopizeCore.hpp` + C# `LoopizeGame.cs` + Web Kit) con sistemas listos para videojuegos:
- **ECS y Consultas Espaciales**: `loopize.ecs_spawn(id, tag, pos, hp, obj, cs_class)`, `loopize.ecs_query_tag(tag)`, `loopize.spatial_radius(center, r, tag)`, `loopize.ecs_set/get/destroy`.
- **Wave Director & FSM**: `lz_wave_rush(wave, kind, count, hp, obj_model)`, `loopize.wave_add/wave_next`, `lz_fsm(key, state)`, `loopize.fsm_get(key)`.
- **Game Feel & Progresión**: `lz_hit_combo(pts, trauma)`, `lz_ease(curve, t)`, `lz_tween(...)`, `loopize.shake(trauma)`, `loopize.camera_update(target, dt, yaw)`, `loopize.inventory_add/has/use`, `lz_mission(...)`, `loopize.quest_progress(...)`, `lz_step(dt)` y `lz_report()`.
- **Demo Oficial**: `./bin/looping sample_loop_projects/loopize_3d_obj_csharp_demo.loop` (o `preview3d`).

---

## 22. Web Loopize Kit (`@cokistudios/web-loopize-kit`)

SDK Web de cero dependencias (`web-loopize-kit.js`, studio interactivo en `loopize-kit.html`) para ejecutar escenarios Looping 3D, mallas `.obj`, scripts C# y sistemas `loopize++` en cualquier navegador moderno:

```html
<script type="module" src="https://cokistudios.com/web-loopize-kit.js"></script>
<loopize-obj-viewer model="starfighter" color="#38bdf8" autorotate="true"></loopize-obj-viewer>
<loopize-stage preset="orbital_arena" title="Orbital Arena 3D"></loopize-stage>
```

- **API JS**: `import { createStage, parseWavefrontOBJ, normalizeOBJMesh, subdivideOBJMesh, exportWavefrontOBJ, PRESETS } from './web-loopize-kit.js'`.
- **Submódulo del Paquete**: `modules/loopize++/components/web-loopize-kit.js` (`smile.json` -> `components.web`).

---

*© 2026 Holo Entertainment • Coki Studios. Making the world Shine, together.*