# Codigo explicado de la A a la Z

Este documento no sustituye al codigo fuente. Lo acompana. Su funcion es que una
persona o IA entienda por que existe cada pieza, que problema resolvio y donde
tocar sin romper el proyecto.

## 1. Launcher Windows

Archivos:

- `client/launcher/src/main.rs`
- `client/launcher/src/core.rs`

### Por que Rust + egui

Rust permite compilar un `.exe` unico, controlar rutas, hashes, ZIPs, procesos y
diagnosticos con seguridad. `egui/eframe` evita depender de frameworks pesados y
da una UI portable suficiente para Windows 10.

### Separacion clave

`main.rs` pinta la interfaz. `core.rs` hace el trabajo delicado.

```rust
fn main() -> eframe::Result<()> {
    let args: Vec<String> = std::env::args().collect();

    // Permite probar sin abrir ventana. Esto hizo posible automatizar QA.
    if args.iter().any(|a| a == "--self-test") {
        match run_self_test() {
            Ok(()) => println!("SELF TEST OK"),
            Err(err) => {
                eprintln!("SELF TEST FAILED: {err:#}");
                std::process::exit(1);
            }
        }
        return Ok(());
    }
}
```

Decision: todo lo que pueda validarse sin usuario debe tener modo CLI. Eso evita
depender de "parece que abre" como unica prueba.

### Carpeta portable

```rust
let root_dir = exe_dir.join("ScoobCodingClient");
let conf_dir = root_dir.join("conf");
let game_dir = conf_dir.join("minecraft");
let cache_dir = conf_dir.join("cache");
let runtime_dir = conf_dir.join("runtime");
```

Decision: el launcher nunca escribe en la `.minecraft` personal. Todo va junto al
`.exe`. Si el usuario borra esa carpeta, borra solo el perfil ScoobCoding.

### RAM segura, no maxima

```rust
pub fn recommended_ram_mb() -> u32 {
    let mut sys = System::new();
    sys.refresh_memory();
    let total_mb = sys.total_memory() / 1024 / 1024;
    match total_mb {
        0..=6144 => 2560,
        6145..=8192 => 3072,
        8193..=12288 => 4096,
        12289..=24576 => 5120,
        _ => 6144,
    }
}
```

Decision: asignar demasiada RAM puede matar el rendimiento en portatiles modestos.
El objetivo es estabilidad para amigos, no ganar una captura de "Xmx enorme".

## 2. Panel macOS

Archivo:

- `mac-panel/ServerPanel.swift`

### Por que AppKit puro

El panel vive en un solo Swift para que pueda compilarse con `swiftc` sin
storyboards ni Xcode. Eso facilita que otra IA lo regenere, lo audite o lo firme.

```swift
let serverDir = URL(fileURLWithPath: NSHomeDirectory())
    .appendingPathComponent("Desktop/server/01_servidor")
```

Decision: despues de ordenar el workspace, el servidor real vive en `01_servidor`.
La app ya apunta ahi.

### Error corregido: comandos con slash

Minecraft diferencia consola y chat:

- chat: `/op NombreJugador`
- consola: `op NombreJugador`

El panel acepta lo que escribe un humano y lo normaliza para consola. Ese detalle
evito fallos como escribir `/op` desde el panel y que el servidor lo interpretara
mal.

## 3. Validador del servidor

Archivo:

- `server/scripts/validate-server.sh`

### Por que existe

Porque "arranca en mi maquina" no basta. El validador revisa:

- Java 17;
- `server.properties`;
- Forge;
- mods;
- zip del cliente;
- app macOS compilable y firmada;
- puerto libre;
- arranque hasta `Done`;
- apagado limpio.

```zsh
require_prop "white-list" "false"
require_prop "enforce-whitelist" "false"
```

Decision: la whitelist quedo desactivada porque el operador lo pidio. El validador
lo protege para que no vuelva por accidente.

## 4. Laboratorio

Archivos:

- `lab/scoob_lab.py`
- `lab/overnight_guardian.py`

### Por que Python

Python es ideal para orquestar pruebas: abrir procesos, leer logs, comparar ZIPs,
calcular hashes y producir reportes JSON.

```python
WORKSPACE = pathlib.Path(__file__).resolve().parents[2]
ROOT = WORKSPACE / "01_servidor"
CLIENT_ROOT = WORKSPACE / "02_cliente"
LAB_ROOT = WORKSPACE / "03_laboratorio"
```

Decision: el laboratorio entiende la estructura ordenada. Ya no depende de que
todo viva mezclado en la raiz.

### Honestidad tecnica

El laboratorio valida muchisimo, pero no puede fingir una RTX de Windows. Por eso
el repo separa:

- pruebas automatizadas que si se ejecutan;
- pruebas fisicas en hardware real.

Esa diferencia es clave para no vender humo. El ultimo check RTX ya se cerro con
Cristo: launcher portable final probado en portatil Windows con RTX dedicada,
sin errores ni bugs reportados.