Cursus — Pac-Man pendiente

«Ghosts! More ghosts!»: un Pac-Man completo y jugable en Python, con laberintos generados por el paquete A-Maze-ing de otro grupo, récords persistentes, modo trampa para el evaluador y publicado en una plataforma de juegos. Proyecto del rank 04.

De dónde sale — Pac-Man lo publicó Namco en 1980, diseñado por Toru Iwatani con la idea de atraer a un público que no jugaba a los matamarcianos de la época. Popularizó el power-up (la píldora que te deja comerte a los fantasmas) y es famoso por su inteligencia artificial: cada fantasma persigue a su manera (Blinky va directo a por ti, Pinky intenta cortarte el paso, Inky es imprevisible y Clyde… raro). La máquina original tenía 256 niveles, pero un desbordamiento de entero hacía imposible terminar el 256: la famosa kill screen, un recordatorio de lo que pasa cuando un contador de 8 bits llega a 255.

En 42next este proyecto cierra un círculo: en el rank 02 hiciste A-Maze-ing, un generador de laberintos empaquetado como librería de Python; aquí tienes que consumir la librería de otro grupo tal cual, sin tocarla. El proyecto mide tanto el juego como la ingeniería que lo rodea: configuración robusta, empaquetado, documentación y gestión del proyecto.

00Qué pide

Rank: 04Lenguaje: Python ≥ 3.10Equipo: en grupo (los repos públicos son de 2 personas; tamaño no confirmado)

Un Pac-Man completo y jugable, en Python, con programación orientada a objetos, una librería gráfica sencilla (MLX o similar) y una arquitectura modular y reutilizable. El juego debe tener:

El ciclo de juego que marca el enunciado: menú principal → empezar partida → ganar o perder → escribir el nombre para el récord → vuelta al menú.

Encima van las reglas comunes de los proyectos Python de 42next, las mismas de los Python Module: flake8, anotaciones de tipo que pasen mypy, docstrings PEP 257, excepciones controladas (un traceback en la evaluación es un proyecto no funcional), recursos con context managers, .gitignore y un Makefile con las reglas install, run, debug (con pdb), clean y lint (y lint-strict opcional).

Sobre «MLX o similar» — El enunciado define «similar» de forma estricta: cada función de la librería que uses debe tener un equivalente en la MLX (la MiniLibX de 42: abrir ventana, dibujar imágenes, recibir teclas y un bucle de eventos). Si te apoyas en algo que la MLX no tiene, no está permitido. Los repos públicos usan la MLX, Pygame o Arcade; si cada uno de ellos cumple esa regla en la práctica depende de qué funciones se usen.

01Uso y fichero de configuración

$> python3 pac-man.py config.json

Exactamente un argumento: un fichero JSON (el nombre da igual). Cualquier error — fichero que no existe, valor no válido, clave que falta — debe acabar en un mensaje claro, nunca en un traceback.

El JSON tiene una extensión: las líneas que empiezan por # son comentarios y se ignoran (se pueden admitir otros estilos, como los de C). La estructura la decides tú, pero hay que documentarla en el README y dar valores por defecto. Las claves sugeridas son orientativas: highscore_filename, un array level con width y height por nivel, lives, pacgum, points_per_pacgum, points_per_super_pacgum, points_per_ghost, seed y level_max_time.

Ante valores ausentes o inválidos: recortar a un valor seguro por defecto, avisar con un mensaje claro y seguir. Las claves desconocidas se ignoran. Y un aviso del enunciado: la configuración se cambiará durante la defensa.

Qué te obliga a aprender — Validación de entrada como parte del diseño, no como parche. JSON (Douglas Crockford, años 2000) no admite comentarios a propósito, así que aquí hay que preprocesar el texto antes de dárselo al parser, y luego decidir para cada clave qué es un valor razonable. Es la diferencia entre un programa que funciona con tu config y uno que aguanta la del evaluador.

02El laberinto ajeno

Está prohibido escribir tu propio generador. Al empezar el proyecto se te asigna el paquete A-Maze-ing de otro grupo, y:

El primer nivel usa una semilla fija (por ejemplo 42) y los siguientes, laberintos aleatorios.

Qué te obliga a aprender — Integrar código que no controlas, que es lo normal en el trabajo real. También por qué un laberinto perfecto no sirve: en teoría de grafos es un árbol (hay un único camino entre cada par de casillas, sin ciclos), lleno de callejones sin salida donde un fantasma te atrapa sin remedio. Con PERFECT=False el generador abre bucles y Pac-Man siempre tiene por dónde escapar. La semilla fija es la misma idea de reproducibilidad que en cualquier generador pseudoaleatorio: misma semilla, mismo laberinto.

03Reglas del juego

Qué te obliga a aprender — Modelar un mundo discreto: una rejilla, entidades que ocupan casillas, colisiones y reglas que se aplican en cada paso. Separar bien el modelo (estado del juego) de la vista (cómo se dibuja) es lo que permite probarlo y lo que piden de forma implícita «arquitectura modular y reutilizable» y la sección de arquitectura del README.

04Fantasmas

Se mueven solos por los pasillos, persiguen al jugador cuando no son comestibles (el comportamiento lo eliges tú: por distancia, aleatorio…), huyen cuando lo son y, si te los comes, vuelven a su esquina al cabo de un rato (por ejemplo 5 o 10 segundos).

Qué te obliga a aprender — Búsqueda en grafos aplicada. Un laberinto es un grafo cuyos nodos son casillas; «ir hacia el jugador» puede ser tan simple como elegir en cada cruce la casilla que reduce la distancia en línea recta (lo que hacía el arcade original, calculando un objetivo distinto para cada fantasma) o tan correcto como un recorrido en anchura (BFS) que da el camino más corto real. En el Pac-Man de 1980 los fantasmas además alternaban entre modo persecución y modo dispersión (cada uno a su esquina) para dar respiros al jugador. El enunciado no exige nada de eso: solo que persigan y huyan.

05Interfaz, bucle y estados

Detrás de cualquier juego hay el mismo esqueleto, que aquí solo se esboza como idea:

mientras el juego esté abierto:
    leer entrada      (teclas)
    actualizar estado (mover, colisiones, temporizadores)
    dibujar           (según la pantalla actual)
Qué te obliga a aprender — El bucle de juego y la máquina de estados. Menú, partida, pausa, fin de partida y victoria son estados con sus transiciones; cada uno decide qué teclas escucha y qué se dibuja. Con la MLX el bucle no es tuyo: registras funciones (hooks) para teclas y para cada fotograma y la librería las llama — programación dirigida por eventos. Y aparece el tiempo: si el movimiento depende de cuántas veces por segundo se ejecuta el bucle, el juego irá a distinta velocidad en cada máquina.

06Récords y modo trampa

Récords: persistentes y donde quieras (un JSON en el proyecto, en disco…), documentados en el README. Robustos ante errores de fichero (no existe, formato inválido…); nombres de como mucho 10 caracteres, alfanuméricos y espacios; puntuaciones enteras no negativas; se guardan los 10 mejores; se cargan al empezar y se guardan al terminar.

Modo trampa: activable para facilitar la evaluación. Sugerencias del enunciado: invencibilidad, saltar de nivel, congelar fantasmas, vidas extra, más velocidad… El criterio es que de verdad ayude al evaluador a probar todas las funciones del juego.

Qué te obliga a aprender — Persistencia sin confiar en el disco: el fichero de récords puede no existir o estar corrupto, y eso no puede tumbar el juego. Y pensar en quién va a probar tu programa: nadie va a jugarse diez niveles en una defensa, así que el modo trampa es una herramienta de testabilidad, no un extra.

07Empaquetado y gestión del proyecto

Qué te obliga a aprender — Que un programa no está terminado cuando funciona en tu máquina: hay que congelar dependencias, generar un ejecutable que funcione en otra y publicarlo. Y gestión de proyecto en equipo, con papeles que lo demuestren: es de los primeros proyectos del cursus donde la documentación del proceso cuenta tanto como el código.

!Puntos delicados

srcFuente

El enunciado no está descargado en el pack. Se han contrastado dos copias públicas del en.subject subidas por estudiantes, en versiones 1.4 y 1.5, que coinciden en todo lo que aparece en esta página. El tamaño del grupo no aparece en ninguna (sí se habla de «otro grupo» y de organización del equipo); los READMEs de los repos consultados están firmados por dos logins.

El enunciado oficial está en la página del proyecto en la intra (slug pac-man).