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:
- configuración por fichero (JSON con comentarios);
- gestión de errores robusta: no crash;
- niveles generados con un paquete A-Maze-ing externo (no el tuyo);
- un sistema de récords persistente;
- interfaz gráfica cuidada: menú principal, vista de juego y fin de partida;
- un modo trampa para la evaluación;
- publicación en una plataforma pública de juegos (Steam, Itch.io o similar).
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:
- hay que usarlo tal cual, sin modificarlo; se reinstalará durante la evaluación;
- tu cargador se adapta a su interfaz, no al revés;
- el parámetro
PERFECT se pone a False para obtener pasillos aptos
para Pac-Man;
- si el generador falla, hay que gestionarlo limpiamente.
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
- Nivel: laberinto con muros y pasillos, pacgums (puntos) en la mayoría de pasillos,
super-pacgums en las 4 esquinas, 4 fantasmas (uno en cada esquina) y el jugador empieza en el
centro.
- Jugador: se mueve solo por pasillos en 4 direcciones (flechas o WASD); empieza con 3
vidas, pierde una al tocarle un fantasma y reaparece en el centro; sin vidas, fin de partida.
- Puntos: pacgum +X, super-pacgum +Y (y fantasmas comestibles un rato), fantasma
comido +Z. La puntuación nunca baja.
- Progresión: se gana el nivel al comerse todos los pacgums; al menos 10
niveles, cada uno con límite de tiempo (por ejemplo 90 s; qué pasa al agotarse lo
decides tú). Puntos y vidas se conservan entre niveles. Se puede pausar y reanudar.
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
- Menú principal: Start Game, View Highscores (top 10), Instructions y Exit.
- HUD siempre visible: puntuación, vidas, nivel y tiempo restante.
- Pausa: reanudar o volver al menú.
- Game Over y Victoria: puntuación final (y felicitación) y petición del nombre
para el récord.
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
- Empaquetado: el juego completo, instalable y ejecutable desde una plataforma pública
(Steam, Itch.io…) como versión gratuita pero oculta o privada, totalmente funcional y con
instrucciones mínimas. El repo debe contener todo el código y el script o spec de
empaquetado en la raíz; pueden pedir regenerar el paquete en la evaluación.
- Gestión: un subdirectorio con documentos que demuestren cómo se llevó el proyecto.
Ejemplos del enunciado: calendario, Gantt o Kanban; seguimiento real frente a lo planificado;
análisis y decisiones; análisis de riesgos; organización del equipo; plan de pruebas de
aceptación; bloqueos y conflictos.
- README en inglés con las secciones comunes y, además: Configuration, Highscore, Maze
Generation, Implementation, General Software Architecture y Project Management.
- Recode: en la evaluación pueden pedir una pequeña modificación en directo.
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
- Acoplarte a tu propio A-Maze-ing: el paquete asignado tendrá otra interfaz y se reinstala
en la evaluación.
- Que una config cambiada en la defensa (claves que faltan, valores absurdos, comentarios)
provoque un traceback.
- Velocidad del juego dependiente del número de fotogramas por segundo.
- Colisiones jugador-fantasma que se «saltan» cuando se cruzan entre dos casillas.
- Laberintos donde alguna esquina o el centro caen en un muro: hay que decidir qué hacer.
- La regla de «MLX o similar» si se usa una librería gráfica distinta.
- Dejar el empaquetado y la documentación de gestión para el final.
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).