README.md (8973B)
1 # Ajedrez en Bash 2 3 Un juego de ajedrez COMPLETO escrito enteramente en Bash (el lenguaje de la 4 terminal de Linux). Es un proyecto pensado para ENSENIAR: para mostrar hasta donde 5 se puede llegar con bash, y para que alguien que recien arranca en programacion 6 pueda leer el codigo y entender como funciona cada parte. Por eso todos los 7 archivos estan comentados al detalle, en castellano. 8 9 > Nota sobre la interfaz: los textos que ve quien juega (menus, mensajes) estan en 10 > ingles a proposito. Los COMENTARIOS del codigo estan en castellano para que 11 > sean faciles de seguir mientras se estudia. 12 13 ## Que sabe hacer 14 15 - Todas las reglas del ajedrez (reglas FIDE completas): movimiento de todas las 16 piezas, enroque, captura al paso, coronacion, jaque, jaque mate, ahogado, y 17 todas las formas de tablas (por acuerdo, por repeticion, por la regla de los 50 18 y 75 movimientos, y por material insuficiente). 19 - Jugar de a dos en la misma computadora (modo "hotseat"). 20 - Jugar en red local (LAN): conexion directa entre dos maquinas, o a traves de un 21 servidor "relay" (repetidor). 22 - Reloj de ajedrez configurable, que se ve contar en vivo. 23 - Guardar y retomar partidas; deshacer jugadas (si se habilita); importar y 24 exportar partidas en los formatos estandar PGN y FEN. 25 - Reconectarse si se corta la red en el medio de una partida. 26 - Jugar contra la computadora (la IA usa el motor Stockfish, una descarga opcional). 27 28 ## Que necesitas instalado 29 30 - `bash` version 4 o mas nueva (el interprete de comandos). 31 - `fzf` (el menu interactivo; version 0.36 o mayor para el reloj en vivo). 32 - `ncat` (para jugar en red; viene en el paquete `nmap`). 33 - `curl` (para el reloj en vivo y para bajar el motor de la IA). 34 - Una terminal con soporte de 256 colores (casi todas hoy en dia). 35 - Para la IA, ademas: el motor **Stockfish** (NO viene incluido; ver mas abajo). 36 37 ## Como se juega 38 39 ```bash 40 ./ches.sh # abre el menu interactivo (elegis el modo ahi) 41 ./ches.sh hotseat # dos personas en la misma compu 42 ./ches.sh ai # contra la computadora (necesita Stockfish) 43 ./ches.sh host <port> # hacer de servidor (jugas blancas) 44 ./ches.sh join <host> <port> # unirse a una partida (jugas negras) 45 ./ches.sh server <host> <port> # jugar via un relay (ver abajo) 46 ./ches.sh resume <file> # retomar una partida guardada (carpeta saves/) 47 ./ches.sh fen "<FEN>" # empezar desde una posicion pegada (FEN) 48 ./ches.sh pgn <file> # reproducir/seguir una partida desde un archivo PGN 49 ./ches.sh rejoin <host> <port> # reconectarse a una partida en curso 50 ./ches.sh --selftest # correr las pruebas automaticas del motor 51 ./ches.sh --help # mostrar la ayuda 52 53 ./bin/chess-server.sh [port] # arrancar el relay (puerto 9000 por defecto) 54 ./bin/get-stockfish.sh # instalar el motor Stockfish para la IA 55 ``` 56 57 Para jugar con relay: una maquina de la red corre `bin/chess-server.sh`, y las dos 58 personas se conectan con `./ches.sh server <ip-del-servidor> <puerto>`. 59 60 Durante tu turno podes apretar Escape para abrir el menu de pausa: ofrecer tablas, 61 pedir un retroceso (si se habilito), guardar, exportar a PGN/FEN, salir o rendirte. 62 63 ## La computadora (IA) y Stockfish 64 65 Bash es demasiado lento para "pensar" jugadas de ajedrez, asi que para jugar 66 contra la maquina usamos un motor externo muy fuerte y de codigo abierto llamado 67 **Stockfish**. No lo incluimos en el proyecto (es un binario pesado y distinto 68 para cada procesador); se baja aparte: 69 70 ```bash 71 ./bin/get-stockfish.sh 72 ``` 73 74 En computadoras x86-64 (las de escritorio/notebooks comunes con Linux) lo baja 75 solo y lo deja en `engine/stockfish`. En otros procesadores (por ejemplo una 76 Raspberry Pi o la consola uConsole, que son aarch64) el script te dice como 77 instalarlo con el gestor de paquetes (`pacman -S stockfish`, `apt install 78 stockfish`, etc.). El juego detecta el motor solo. La carpeta `engine/` NO es 79 parte del proyecto: se crea al bajar el motor, y no hace falta compartirla. 80 81 ## Como esta organizado el codigo (para estudiarlo) 82 83 El punto de entrada es **`ches.sh`**: carga las librerias, prepara el modo de juego y 84 corre el bucle principal de la partida (`play()`). Toda la logica esta repartida 85 en la carpeta `lib/`. El orden de abajo es un buen orden para leerlos, de lo mas 86 basico a lo mas complejo: 87 88 - **`lib/board.sh`** — El tablero. Como se guarda la posicion (un arreglo de 64 89 casilleros), como se lee y se escribe un FEN, y las cuentas de coordenadas. 90 EMPEZA POR ACA: es la base de todo. 91 - **`lib/movegen.sh`** — Generar las jugadas posibles de cada pieza (como se mueve 92 la torre, el alfil, el peon, etc.). 93 - **`lib/rules.sh`** — El cerebro de las reglas: detectar ataques y jaques, 94 filtrar las jugadas legales, aplicar una jugada al tablero, y detectar el fin de 95 la partida (mate, ahogado, tablas). 96 - **`lib/notation.sh`** — Traducir jugadas a la notacion estandar SAN (`e4`, 97 `Nf3`, `O-O`...). Sirve para exportar e importar PGN. 98 - **`lib/ui.sh`** — La interfaz: dibujar el tablero a color en la terminal y los 99 menus para elegir jugadas (con fzf). 100 - **`lib/protocol.sh`** — El "idioma" que hablan dos computadoras por la red, y las 101 funciones de bajo nivel para mandar y recibir mensajes. 102 - **`lib/transport.sh`** — De DONDE viene cada jugada (vos, la red, o la IA), el 103 reloj, y toda la logica de red (conectar, reconectar, ofrecer tablas, etc.). 104 - **`lib/ai.sh`** — La computadora: como le hablamos a Stockfish para que juegue. 105 - **`lib/saves.sh`** — Guardar/cargar partidas, y exportar/importar PGN y FEN. 106 - **`lib/selftest.sh`** — Las pruebas automaticas del motor. 107 108 Y en `bin/`: 109 110 - **`bin/chess-server.sh`** — El servidor relay (un repetidor de mensajes "tonto": 111 no sabe ajedrez, solo copia mensajes de una jugadora a la otra). 112 - **`bin/get-stockfish.sh`** — El descargador del motor Stockfish. 113 114 ## La idea mas importante: como se representa el tablero 115 116 El tablero de 64 casilleros se guarda como una LISTA (un arreglo) de 64 elementos, 117 numerados del 0 al 63. El indice 0 es la esquina de arriba a la izquierda (la 118 casilla `a8`) y el 63 es la de abajo a la derecha (`h1`): 119 120 ``` 121 a b c d e f g h 122 8: 0 1 2 3 4 5 6 7 123 7: 8 9 10 11 12 13 14 15 124 6: 16 17 18 19 20 21 22 23 125 5: 24 25 26 27 28 29 30 31 126 4: 32 33 34 35 36 37 38 39 127 3: 40 41 42 43 44 45 46 47 128 2: 48 49 50 51 52 53 54 55 129 1: 56 57 58 59 60 61 62 63 130 ``` 131 132 Cada casillero guarda una letra: `.` si esta vacio; mayusculas `PNBRQK` para las 133 piezas blancas y minusculas `pnbrqk` para las negras (P/p=peon, N/n=caballo, 134 B/b=alfil, R/r=torre, Q/q=dama, K/k=rey, en ingles porque es el estandar). Para 135 pasar de un indice a fila/columna se usa division y resto: fila = indice / 8, 136 columna = indice % 8. Esto esta todo explicado en `lib/board.sh`. 137 138 ## Mini glosario de bash (cosas que vas a ver en el codigo) 139 140 - `variable="valor"` guarda un valor; `$variable` o `${variable}` lo usa. 141 - `$( comando )` ejecuta un comando y se reemplaza por lo que ese comando imprime. 142 - `$(( 2 + 3 ))` hace cuentas con numeros enteros. 143 - `[[ ... ]]` es una pregunta de verdadero/falso (un "if"). 144 - `funcion() { ... }` define una funcion; adentro, `$1`, `$2`... son sus argumentos. 145 - En bash, "exito" = 0 y "error" = distinto de 0. `comandoA && comandoB` corre B 146 si A salio bien; `comandoA || comandoB` corre B si A fallo. 147 - `arreglo=(a b c)` crea una lista; `${arreglo[0]}` es su primer elemento. 148 - `|` (tuberia) conecta la salida de un comando con la entrada del siguiente. 149 - `>` manda la salida a un archivo; `>&2` la manda a la "salida de errores". 150 151 Cada uno de estos aparece explicado en su contexto la primera vez que se usa. 152 153 ## Como correr las pruebas 154 155 ```bash 156 ./ches.sh --selftest 157 ``` 158 159 Corre `lib/selftest.sh`: prueba el motor contra posiciones conocidas (mate del 160 pastor, captura al paso, enroque, coronacion, ahogado, repeticiones, reloj, 161 guardar/cargar, notacion SAN, ida y vuelta de PGN, y la IA si Stockfish esta 162 instalado). Es la forma rapida de verificar que todo anda: si tocas el motor y 163 rompes algo, las pruebas lo detectan. No hay nada que "compilar": bash se 164 interpreta directamente. 165 166 ## Notas para tener en cuenta 167 168 - El mapeo entre el indice (0..63) y el nombre de casilla es facil de invertir 169 (la fila 8 son los indices chicos). Si agregas logica de movimiento, conviene 170 pasar por las funciones de coordenadas de `board.sh`. 171 - `apply_move` NO valida que la jugada sea legal: confia en lo que le pasan. Hay 172 que darle solo jugadas que vengan de `legal_moves`. 173 - Cuidado con declarar varias variables en una sola linea cuando una usa a la 174 otra: `local a=$1 b=${a}` no funciona como uno espera (la parte derecha se 175 calcula ANTES de asignar, asi que `b` ve una `a` vacia). Hay que separarlas en 176 lineas distintas. Esta explicado en `lib/notation.sh`. 177 - El binario de Stockfish (carpeta `engine/`) es una descarga opcional, no parte 178 del proyecto. La integracion de la IA si viene incluida (en `lib/ai.sh`).