juegos

README.md (15649B)

---

 # Catan en C — terminal, gráfico, online y PicoCalc
 
 Catan (juego base completo + variante oficial para 2) escrito en C99 portable.
 El mismo núcleo corre en:
 
 - **la terminal** (TUI con ncurses, tablero dibujado con medios bloques de color),
 - **una ventana gráfica** (SDL3, pixel-art),
 - **un servidor** para tu VPS (partidas online en vivo o asincrónicas, que sobreviven reinicios),
 - **la PicoCalc** (Raspberry Pi Pico 1), con **cable 1v1** entre dos PicoCalc.
 
 Todos hablan el mismo protocolo: alguien en la terminal y alguien en la versión
 gráfica juegan la misma partida sin notar diferencia.
 
 ## Compilar
 
 Dependencias: `gcc`/`clang`, `make`, `ncursesw`, `SDL3` (solo para la GUI y el simulador).
 
 ```sh
 make            # catan, catan-server, catan-picosim
 make test       # pruebas del núcleo + 400 partidas bot contra bot + duelos búsqueda vs heurística
 make pico       # firmware PicoCalc (ver más abajo)
 ```
 
 ## Jugar
 
 ```sh
 ./catan                 # menú (terminal)
 ./catan-gui             # lo mismo, en ventana gráfica   (= ./catan --gui)
 ./picocalc-sim          # simulador de la PicoCalc en la PC
 
 ./catan hotseat -n 4 --bots 3      # vos contra 3 bots, directo
 ./catan hotseat -n 2 --2p          # 1v1 en la misma compu con la variante para 2
 ./catan resume                     # retomar la última partida
 ./catan online mivps.com:7373      # mis partidas en el servidor
 ./catan host 7373                  # crear partida en red local
 ./catan join 192.168.0.10 7373     # unirse a una partida en red local
 ```
 
 Opciones: `--lang es|en`, `--gui`, `--layout wide|compact`, `--scale N`.
 Las partidas locales se guardan solas en `~/.local/share/catan/saves/`.
 
 ### Controles
 
 | Tecla | Acción |
 |---|---|
 | Flechas / hjkl | mover el cursor por los lugares válidos |
 | Enter / Espacio | confirmar |
 | Esc | volver / cancelar |
 | `r` | tirar los dados |
 | `1` `2` `3` `4` | ruta, pueblo, ciudad, comprar carta |
 | `d` | jugar carta de desarrollo |
 | `b` | comerciar con banco / puerto |
 | `t` | ofrecer trueque a los demás |
 | `e` | terminar el turno |
 | `f` `z` | (variante 2p) comercio forzado, ladrón al desierto |
 | `Tab` | siguiente objetivo / panel de detalle |
 | `?` `L` `q` | ayuda, idioma, salir |
 
 Con mouse (terminal o GUI) se puede clickear en el tablero, las acciones y los menús.
 
 En los diálogos de cartas (descartar, trueque, descubrimiento): ←→ elige recurso,
 ↑↓ o `+`/`-` cambian la cantidad, `1`-`5` suman, Tab cambia entre "das" y "pedís".
 
 ## Reglas
 
 Catan base completo: colocación inicial en serpiente, producción (con la regla de
 banco sin cartas), 7 con descarte y ladrón, rutas/pueblos/ciudades, cartas de
 desarrollo (14 caballeros, 5 PV, 2 de cada progreso), camino más largo (cortado
 por edificios ajenos), ejército más grande, comercio 4:1 / 3:1 / 2:1 y trueques
 entre jugadores. Se gana con 10 PV en tu turno.
 
 **Variante para 2** (inspirada en la de *Mercaderes y Bárbaros*):
 
 - Hay 2 jugadores **neutrales** con 2 pueblos y 2 rutas iniciales al azar.
 - Cada vez que construís una ruta tenés que construirle una ruta gratis a un
   neutral; cada pueblo, un pueblo neutral (o una ruta si no hay lugar).
 - **Dos tiradas por turno**; la segunda no puede sumar lo mismo que la primera.
 - **Fichas de comercio**: arrancás con 2, ganás 1 por cada caballero jugado y por
   cada pueblo al lado del desierto. Cuestan 1 (2 si vas ganando) y sirven para:
   - **comercio forzado**: le sacás 2 cartas al azar al rival y le devolvés 2 que elijas;
   - **ladrón al desierto**.
 - **Ladrón amable**: no puede ir a un hexágono de alguien con 2 PV o menos.
 
 Los valores están en `Opts` (`core/catan.h`) por si tu edición cambia algo.
 
 ## Online: servidor en tu VPS
 
 ```sh
 make catan-server-static                 # binario estático, anda en cualquier Linux x86-64
 scp catan-server ../comun/deploy/install-vps.sh root@mivps:/tmp/
 ssh root@mivps sh /tmp/install-vps.sh catan 7373 /tmp/catan-server "Servidor de Catan"
 ```
 
 Eso crea el usuario `catan`, guarda las partidas en `/var/lib/catan` y lo deja
 corriendo con systemd en el puerto **7373** (abrilo en el firewall). Logs:
 `journalctl -u catan-server -f`.
 
 Cómo se usa:
 
 1. En `./catan` → *Jugar online*, poné `mivps.com:7373`, tu **nombre** y una **contraseña**.
    No hay cuentas: nombre + contraseña son tu llave (el cliente manda solo un hash).
 2. *Crear partida*: elegís jugadores, qué asientos son bots, el nivel de los bots (fáciles,
    medios o difíciles: la misma búsqueda con más o menos iteraciones) y **"Bot juega si no
    hay"** (nunca, 1, 4, 12, 24 o 48 horas). Quién empieza se sortea. Te da un **código** de 6 letras; pasáselo a tus amigos.
 3. Tus amigos: *Jugar online* → su nombre y contraseña → el código → *Unirse con el código*.
 4. Se juega igual estén todos o no: los conectados ven todo en vivo y la partida da la
    vuelta hasta llegar a alguien que no está. Ahí espera; si pasa el tiempo elegido, el
    bot juega ese turno por él y sigue. Cerrá cuando quieras: otro día, desde **cualquier
    compu**, nombre + contraseña → *Mis partidas* muestra las tuyas y cuáles dicen **¡TE TOCA!**.
 
 Dos instancias en la misma compu con distintos nombres son dos jugadores distintos.
 Sin contraseña, *Mis partidas* usa las partidas guardadas en esta compu
 (`~/.local/share/catan/online`, como antes). El tráfico va en texto plano; si querés
 cifrarlo, usá un túnel SSH (`ssh -L 7373:localhost:7373 mivps`) o stunnel.
 
 Al terminar una partida, **jugar otra** (`a`, o tocar la línea en el cuadro final) arma
 una nueva con las mismas opciones: local, con otro reparto; online, el servidor la crea
 con la misma gente en los mismos asientos y a los demás les aparece en *Mis partidas*.
 
 **Si alguien se olvida la contraseña**: el servidor no la guarda (solo la llave que
 deriva el cliente), pero el administrador puede ponerle una nueva a ese asiento:
 
 ```sh
 sudo catan-admin partidas                          # códigos y asientos
 sudo catan-admin reset ECM8CA Félix nuevaclave     # Félix entra con "nuevaclave" desde ahora
 ```
 
 (`install-vps.sh` instala `catan-admin`; el secreto está en `/var/lib/catan/admin.key`.)
 
 ## Web: la PWA para el teléfono
 
 El mismo cliente compilado a WebAssembly (`make web`, ver abajo) se sirve desde una
 página HTTPS. En el teléfono se entra a la dirección, aparece el menú de siempre y con
 *Agregar a pantalla de inicio* queda como una app. En vertical el tablero va arriba y
 el panel abajo; en apaisado es el layout ancho de la PC. Lo que en la PC es una tecla
 (Esc, ayuda, idioma, salir) son botones; el chat y los campos de texto abren un cuadro
 del navegador (SDL no muestra el teclado táctil).
 
 - Las partidas locales y la configuración se guardan en el almacenamiento del navegador
   (IndexedDB): sobreviven a cerrar y recargar, se pierden si se borran los datos del
   sitio. En iPhone, instalada en la pantalla de inicio, queda exenta de la limpieza de
   7 días de Safari. Con la app instalada, jugar solo anda sin internet.
 - Online es idéntico a la PC: nombre + contraseña dan la misma llave, así que *Mis
   partidas* muestra las mismas y se puede meter un turno desde el celular en la partida
   que se juega en la compu. El campo "Servidor" no aparece: la web habla siempre con el
   servidor de la página.
 
 **Compilar** (`make web` → `web/dist/`): necesita emscripten (`pacman -S emscripten`,
 `source /etc/profile.d/emscripten.sh`) y la fuente de SDL3 (la misma de `make windows`);
 la primera vez compila SDL3 para wasm en `~/.local/opt/SDL3-em`. El cliente no cambia:
 `-sASYNCIFY` hace que sus esperas (SDL, `poll()`) cedan al navegador, y los sockets van
 por un WebSocket. Para probar en la PC:
 
 ```sh
 ./catan-server --port 7373 --data /tmp/catan-data &      # acepta TCP y WebSocket en el mismo puerto
 (cd web/dist && python3 -m http.server 8080)
 chromium --window-size=390,844 'http://localhost:8080/?ws=ws://localhost:7373'
 ```
 
 **Servir**: el navegador necesita `wss://` (TLS), que pone Caddy (o nginx) delante del
 servidor; el `catan-server` entiende WebSocket solo (`comun/server/ws.c`). Bloque de
 `/etc/caddy/Caddyfile`:
 
 ```
 catan.lu3dhn.xyz {
     encode zstd gzip
     handle /ws { reverse_proxy 127.0.0.1:7373 }
     handle { root * /var/www/catan; file_server }
 }
 ```
 
 `make deploy-web` sube `web/dist/` al VPS (host `vps` de ssh) a `/var/www/catan`.
 
 Pendientes conocidos de la web: en iPhone el cuadro de texto no abre el teclado solo
 (hay que tocar el campo); una partida local vive en el navegador de ese teléfono (si se
 borran los datos del sitio se pierde: no hay exportar/importar todavía); una sola
 instancia a la vez (la segunda pestaña avisa y no arranca).
 
 ## PicoCalc
 
 ### Compilar y cargar desde la tarjeta SD (sin cable USB)
 
 Hace falta el compilador ARM y el pico-sdk:
 
 ```sh
 sudo pacman -S arm-none-eabi-gcc arm-none-eabi-newlib
 git clone --depth 1 --recurse-submodules https://github.com/raspberrypi/pico-sdk ~/pico-sdk
 make pico            # arma la carpeta sd/ lista para copiar
 ```
 
 Copiá a la **tarjeta SD** de la PicoCalc lo que corresponda a tu cargador:
 
 - **Cargador de ClockworkPi "Bootloader v0.5"** (la SD tiene la carpeta `firmware/` con
   archivos `.bin`, y al prender aparece la lista): copiá `sd/firmware/Catan.bin` a
   `firmware/` y elegilo en la lista. Es el que está probado.
 - **uf2loader** (SD v0.6 o más nueva, carpeta `pico1-apps/` con `.uf2`): copiá
   `sd/pico1-apps/Catan.uf2` a `pico1-apps/` y elegilo en el menú (encendé con **Arriba**).
 
 Además van en la raíz de la SD dos archivos que `make pico` deja en `sd/`:
 
 - `CATAN.SAV` (80 KB): **la partida guardada**. Sin este archivo el juego no guarda.
 - `CATAN.LOG` (256 KB de espacios): cada arranque agrega ahí qué pasó (pantalla,
   teclado, cable, SD, errores). Si algo falla, ese archivo dice dónde.
 
 Copialos **solo la primera vez**: si después los volvés a copiar encima, perdés la
 partida guardada y el log. El firmware nunca crea archivos ni toca la FAT: solo
 reescribe el contenido de estos dos, así que no puede romper la tarjeta. Si hace
 falta crearlos a mano:
 
 ```sh
 head -c 81920 /dev/zero > /ruta/a/la/sd/CATAN.SAV
 head -c 262144 /dev/zero | tr '\0' ' ' > /ruta/a/la/sd/CATAN.LOG
 ```
 
 **Detalles del arranque desde la SD** (lo que costó hacerlo andar):
 
 - El cargador salta al programa sin apagar nada: deja interrupciones armadas y **su
   segundo núcleo (core 1) corriendo y dibujando en la pantalla**. Catan limpia las
   interrupciones en su primera instrucción (`catan_early_reset`, que
   `comun/tools/patch_reset.py` instala en el vector de reset del `.bin`) y resetea el core 1
   antes de tocar la pantalla.
 - La pantalla necesita cada comando con sus parámetros bajo un mismo *chip select*.
 - La flash de la Pico no se escribe nunca: la partida va en `CATAN.SAV`, en dos
   mitades que se alternan. Si se corta la energía mientras guarda, queda el guardado
   anterior.
 
 Antes de probar en el aparato, probalo en la PC: `./picocalc-sim` corre **el mismo código**.
 
 En el menú principal está **"Prueba: 10 partidas de bots"**: juega 10 partidas completas
 en la Pico verificando las reglas en cada movida y deja el resultado en la pantalla y en
 `catan.log`.
 
 ### El cable 1v1
 
 La PicoCalc tiene dos headers de 8 pines. Usamos **J703** (el del lado de la Pico),
 con el UART1 del RP2040:
 
 | Pin J703 | Señal | Conectar con la otra PicoCalc |
 |---|---|---|
 | 4 | GP4 = TX | pin **5** |
 | 5 | GP5 = RX | pin **4** |
 | 8 | GND | pin **8** |
 | 1 | 3V3 | **no conectar** |
 
 ```
 PicoCalc A (J703)        PicoCalc B (J703)
    pin 4 (TX) ─────────────── pin 5 (RX)
    pin 5 (RX) ─────────────── pin 4 (TX)
    pin 8 (GND) ────────────── pin 8 (GND)
 ```
 
 - Las dos son de 3,3 V: no hace falta conversor. Cable corto (< 1 m). 115200 baudios.
 - GP2-GP5 y GP21 los comparte la PSRAM de la placa; el firmware deja su CS (GP20)
   en alto, así que no molesta (el juego no usa la PSRAM).
 - **No** usamos J702 (UART0): va al chip USB-serie del USB-C y chocarían las señales.
 
 Uso: en una PicoCalc *Cable 1v1: crear (A)*, en la otra *Cable 1v1: unirse (B)*.
 La A es la autoridad (dados, mazo, bots extra) y guarda la partida en su SD;
 si se desenchufa el cable, la B vuelve a sincronizar sola al reconectar.
 Cada línea lleva un checksum; si llega algo corrupto, la B pide todo de nuevo.
 
 ## Cómo está hecho
 
 ```
 core/     reglas, tablero, movidas, autoridad, bots, i18n, controlador de UI
           (C99 sin malloc ni stdio: compila igual para Linux y el RP2040)
 gfx/      dibujo de Catan en pixeles (tablero, pantallas compacta/ancha)
 linux/    cliente: TUI (ncurses), GUI (SDL3), menús, red, guardado, pruebas
 server/   Catan como módulo del servidor de partidas (también embebido en `catan host`)
 pico/     firmware PicoCalc: app.c (portable, corre igual en el simulador)
 app_config.h  nombre de la app, archivos de la SD
 ```
 
 Lo que no es de Catan vive en `../comun/` (ver `comun/README.md`): renderer de
 pixeles y fuente, formularios, kits de TUI y SDL, red, el esqueleto del servidor,
 la capa de hardware de la PicoCalc (pantalla, teclado, SD, cable) y su simulador,
 y el instalador del VPS. El ajedrez usa lo mismo.
 
 La idea central: un nodo **autoridad** valida cada movida y resuelve el azar
 (dados, robos, mazo); todos los demás aplican las movidas ya resueltas con
 `game_apply()`. Una partida es su **log de movidas**, así que guardar, retomar,
 reconectar y jugar asincrónico salen de lo mismo. Las cartas de desarrollo
 compradas se ocultan a los demás (`move_redact`).
 
 ### Bots
 
 Hay dos niveles (en *Nueva partida*: "Bots: Fáciles / Difíciles", se recuerda en la config):
 
 - **Fáciles** (`core/bot.c`): heurística de una movida. Valora esquinas por pips,
   diversidad y puertos, junta para un objetivo (pueblo, ciudad, ruta o carta),
   cambia con el banco hacia lo que le falta. No propone cambios a otros.
 - **Difíciles** (`core/search.c`): ISMCTS. En cada iteración sortea lo que el bot
   no puede ver (cartas de desarrollo ajenas y orden del mazo), baja por un árbol
   de movidas candidatas (podadas con la heurística) eligiendo con UCB, juega 8
   turnos más con el bot fácil y evalúa (puntos, producción, cartas). Cada nodo
   guarda el puntaje de quien movió (max-n). Corta por tiempo: 300 ms por decisión
   en la PC, 150 ms en el servidor, 1,2 s en la PicoCalc.
 
 Contra tres bots fáciles, uno difícil gana ~70-78 % de las partidas de 4
 (base 25 %) y ~85 % de las de 2 (`./catan --duel`).
 
 ### Protocolo
 
 Líneas de texto terminadas en `\n` (general en `comun/server/srv.h`, lo de Catan en `server/server.h`):
 
 ```
 -> HELLO 1 Ana              <- WELCOME 1
 -> CREATE 2 1 10 0 HH       <- GAME K7QX2M 0 <token>
                             <- HDR G ...        (tablero y opciones)
                             <- SEAT 0 P 1 Ana
                             <- EV 2 NEUTRAL 2 1 34   (historial...)
                             <- SYNC
 -> MOVE 0 SETTLE 12         <- EV 0 SETTLE 12
 -> MOVE 0 ROLL 0 0 0 0      <- EV 0 ROLL 3 4 2 5 (la autoridad pone los dados)
 ```
 
 ### Pruebas
 
 ```sh
 ./catan --selftest          # reglas, serialización, replay, redacción
 ./catan --sim 2000 4        # 2000 partidas de bots: invariantes (recursos, piezas, mazo)
 ./catan --sim 2000 2 2p     # lo mismo con la variante para 2
 ./catan --duel 100 4 2000 8 # 100 partidas: un bot difícil (2000 iteraciones, horizonte 8)
                             # contra fáciles, rotando el asiento; también 2p, semilla y c de UCB
 make debug && make test     # con AddressSanitizer / UBSan
 ```