project-afterlife/docs/game-servers.md

Servidores de Juegos

Guia de setup, operacion y troubleshooting de cada servidor de juegos.

OpenFusion (FusionFall)

Resumen

Dato	Valor
Emulador	OpenFusion
Lenguaje	C++
Puerto	23000 (login), 23001 (shard)
Base de datos	SQLite (embebida)
RAM	~254 MB

Archivos

servers/openfusion/
├── Dockerfile              # Ubuntu 24.04, copia binario + config
├── docker-entrypoint.sh    # Genera config.ini desde env vars
├── config.ini              # Configuracion del servidor
├── fusion                  # Binario compilado (no en git)
├── sql/                    # Migraciones SQLite
└── tdata/                  # Datos del juego (NPCs, mobs, drops)

Configuracion

Variables de entorno en docker-compose.dev.yml:

• OPENFUSION_SHARD_IP: IP publica del servidor (default: 192.168.10.234)
• OPENFUSION_MOTD: Mensaje del dia

Conexion de cliente

1. Descargar el cliente FusionFall
2. Usar el launcher de OpenFusion apuntando a 192.168.10.234:23000

Troubleshooting

• "Connection refused": Verificar que el contenedor esta corriendo y los puertos estan mapeados
• Datos de juego: Los archivos tdata/ contienen los NPCs, mobs y drops. Si faltan, el mundo estara vacio

---

MapleStory 2

Resumen

Dato	Valor
Emulador	Maple2
Lenguaje	C# / .NET 8
Puertos	20001 (login), 21001 (world), 20003/21003 (game ch0), 4000 (web)
Base de datos	MySQL 8.0 (puerto 3307)
RAM total	~1.4 GB (5 contenedores)

Arquitectura Multi-Servicio

maple2-mysql (3307)
    │
    ├── maple2-world (21001)     ← Coordinador central, gRPC
    │       │
    │       ├── maple2-login (20001) ← Autenticacion, seleccion de personaje
    │       │
    │       └── maple2-game-ch0 (20003/21003) ← Canal de juego (channelId=1)
    │
    └── maple2-web (4000)        ← API web auxiliar

Los servidores se comunican entre si via gRPC (HTTP/2). El World server actua como coordinador central. Los Game servers se conectan al World al iniciar.

Setup Inicial (Primera Vez)

1. Clonar el repositorio

cd servers/
git clone --recurse-submodules https://github.com/MS2Community/Maple2.git maple2

2. Descargar datos del cliente

Se necesita el cliente de MapleStory 2 (~14 GB). Los archivos se colocan en servers/maple2/client-data/Data/.

Fuentes del cliente:

• adventure-island-online-2 releases (6 partes ZIP)
• Extraer todo a servers/maple2/client-data/

3. Aplicar XML Patches

Descargar MapleStory2-XML v1.2.1 y copiar los archivos Server.m2d, Server.m2h, Xml.m2d, Xml.m2h a servers/maple2/client-data/Data/ (reemplazar los originales).

4. Configurar .env

cp servers/maple2/.env.example servers/maple2/.env
# Editar con las IPs correctas:
# GAME_IP=192.168.10.234
# LOGIN_IP=192.168.10.234

5. Verificar .dockerignore

El archivo servers/maple2/.dockerignore DEBE incluir:

client-data
client-download
xml-patches

Sin esto, el build de Docker intentara copiar 14 GB de datos al contexto.

6. Ingestar datos del juego

cd docker/
docker compose -f docker-compose.maple2.yml up -d maple2-mysql
# Esperar a que MySQL este healthy
docker compose -f docker-compose.maple2.yml run --rm maple2-file-ingest \
  bash -c "cd /app && dotnet restore && cd Maple2.File.Ingest && dotnet run"

Este proceso importa todos los datos del cliente a MySQL. Toma ~10 minutos.

7. Construir y levantar servidores

docker compose -f docker-compose.maple2.yml build
docker compose -f docker-compose.maple2.yml up -d

Conexion de cliente

1. Tener el cliente de MapleStory 2 instalado
2. El cliente debe apuntar a 192.168.10.234:20001 (Login Server)
3. Las IPs se configuran en servers/maple2/.env (GAME_IP, LOGIN_IP)

Troubleshooting

• "No space left on device" al buildear: Verificar .dockerignore incluye client-data
• "Scripting/Scripts not found": Ya corregido — se removio la linea COPY del Dockerfile del Game server
• "project.assets.json not found" en file-ingest: Ejecutar dotnet restore antes de dotnet run
• Servidores no se conectan entre si: Verificar que GRPC_WORLD_IP=maple2-world y GRPC_GAME_IP=maple2-game-ch0 estan configurados en el compose
• "Server not found" al seleccionar personaje: INSTANCED_CONTENT debe ser "false" para que el canal se registre como non-instanced. Con "false", el channelId es 1 y los puertos son 20003/21003 (base + channelId)

Agregar mas canales de juego

Para agregar un segundo canal, duplicar el servicio maple2-game-ch0 en el compose cambiando:

• Nombre: maple2-game-ch1
• Puertos: 20004:20004 y 21004:21004 (channelId=2)
• GRPC_GAME_IP: maple2-game-ch1

Nota sobre puertos: Con INSTANCED_CONTENT: "false", el primer canal es channelId=1 (puertos 20003/21003), el segundo seria channelId=2 (20004/21004), etc. Los puertos se calculan como BasePort + channelId.

---

Minecraft: FTB Evolution

Resumen

Dato	Valor
Imagen Docker	itzg/minecraft-server:java21
Modpack	FTB Evolution v1.29.1
Minecraft	1.21.1
NeoForge	21.1.218
Puerto	25565
RAM	~3.5 GB (6 GB JVM heap, 8 GB limite contenedor)
Mods	200+

Configuracion

El servidor se configura via variables de entorno en docker-compose.dev.yml:

environment:
  EULA: "TRUE"
  TYPE: FTBA
  FTB_MODPACK_ID: 125
  FTB_MODPACK_VERSION_ID: 100181
  MEMORY: 6G
  MAX_MEMORY: 6G
  MOTD: "Project Afterlife - FTB Evolution"
  DIFFICULTY: normal
  MAX_PLAYERS: 20
  VIEW_DISTANCE: 10
  ENABLE_COMMAND_BLOCK: "true"

Primer inicio

El primer inicio toma 5-10 minutos porque:

1. Descarga el FTB App installer
2. Descarga los 200+ mods del modpack
3. Instala NeoForge 21.1.218
4. Genera el mundo

Conexion de cliente

1. Instalar FTB App, MultiMC, ATLauncher, o Prism Launcher
2. Instalar modpack FTB Evolution version 1.29.1
3. Multiplayer > Add Server: 192.168.10.234:25565

Fix: Watchdog crash en primer inicio

Con 200+ mods, el mod Hexerei tarda mas de 60 segundos generando recetas al iniciar, lo que activa el watchdog de Minecraft. Se resuelve con MAX_TICK_TIME: -1 en las variables de entorno del compose.

Troubleshooting

• Server lag: Reducir VIEW_DISTANCE de 10 a 8, o aumentar MEMORY si hay RAM disponible
• NeoForge install fails: Verificar que la imagen Docker es java21 (no java8 ni java17)
• Watchdog crash (single tick took 60s): Verificar que MAX_TICK_TIME: -1 esta configurado

---

Super Mario 64 Coop (sm64coopdx)

Resumen

Dato	Valor
Proyecto	sm64coopdx
Lenguaje	C
Puerto	7777 (UDP)
Jugadores	Hasta 16
RAM	~45 MB

Archivos

servers/sm64coopdx/
├── Dockerfile           # Multi-stage: compila desde fuente + runtime
├── .dockerignore
├── .gitignore           # Excluye ROMs (*.z64, *.n64, *.v64)
└── baserom.us.z64       # ROM de SM64 US (no en git, requerida para build)

Requisitos

Se necesita la ROM de Super Mario 64 US (baserom.us.z64, MD5: 20b854b239203baf6c961b850a4a51a2) en servers/sm64coopdx/ antes de construir la imagen Docker.

Cómo funciona

El Dockerfile compila sm64coopdx desde fuente con HEADLESS=1 DISCORD_SDK=0 COOPNET=0. Incluye dos parches:

1. float.h — GCC 11 requiere include explícito de <float.h> para FLT_EPSILON
2. platform.c — El fallback headless (sin SDL2) tiene funciones renombradas que upstream no actualizo (sys_exe_path_dir, sys_resource_path)

La ROM es necesaria tanto en build (extracción de assets) como en runtime (validación MD5 al iniciar).

Configuracion

Variables de entorno en docker-compose.dev.yml:

• SM64_PORT: Puerto UDP del servidor (default: 7777)
• SM64_PLAYERS: Maximo de jugadores (default: 16)

Conexion de cliente

1. Descargar sm64coopdx (requiere compilar con la misma ROM)
2. Abrir sm64coopdx → Join → Direct Connection
3. Ingresar play.consultoria-as.com:7777 (o 192.168.10.234:7777 en LAN)

Mods incluidos

El build incluye mods bundled del repositorio: character-select, star-road, arena, day-night-cycle, sm74.

Troubleshooting

• "could not find valid vanilla us sm64 rom": La ROM debe estar tanto en el build como en el runtime. Verificar que el Dockerfile copia baserom.us.z64 al stage de runtime
• 100% CPU: Normal — el game loop headless no tiene frame limiter porque no renderiza graficos
• No se conectan jugadores: Verificar que el puerto 7777/UDP esta abierto en el router y que el firewall permite UDP

---

N64 Netplay (gopher64 — Mario Party 1-3)

Resumen

Dato	Valor
Proyecto	gopher64-netplay-server
Imagen Docker	k4rian/gopher64-netplay-server
Lenguaje	Go
Puertos	45000-45004 (TCP + UDP)
Jugadores	4 por sala, 4 salas concurrentes
RAM	<1 MB (heap ~660 KB)

Cómo funciona

Servidor relay headless que retransmite inputs de controles N64 entre jugadores via WebSocket (lobby) + UDP (gameplay). No ejecuta el juego — cada jugador corre su propio emulador con su ROM. El servidor solo coordina la sincronización.

• Puerto 45000: WebSocket lobby (creación de salas, chat, conexión)
• Puertos 45001-45004: Sesiones de juego individuales (TCP + UDP)
• LAN discovery: Activado por defecto, los emuladores en la misma red lo detectan automáticamente

Configuracion

Variables de entorno en docker-compose.dev.yml:

• G64NS_NAME: Nombre del servidor ("Afterlife N64 - Mario Party")
• G64NS_PORT: Puerto base (default: 45000)
• G64NS_MAXGAMES: Partidas concurrentes (default: 4)
• G64NS_MOTD: Mensaje de bienvenida
• G64NS_DISABLEBROADCAST: Desactivar LAN discovery (default: false)
• G64NS_ENABLEAUTH: Activar autenticación (default: false)

Juegos soportados

Cualquier juego de N64, pero diseñado especialmente para:

• Mario Party 1 (N64)
• Mario Party 2 (N64)
• Mario Party 3 (N64)

Todos los jugadores deben usar el mismo emulador y el mismo ROM (se verifica MD5).

Emuladores compatibles (cliente)

Emulador	Custom server	Estado
gopher64	Si (v1.1.1+)	Activo, recomendado
RMG (Rosalie's Mupen GUI)	Si (v0.8.0+)	Activo
simple64	Si	Archivado (usar gopher64)

Conexion de cliente

1. Descargar gopher64 o RMG
2. Tener el ROM de Mario Party
3. Netplay → Server: seleccionar "Custom"
4. Ingresar play.consultoria-as.com:45000 (o 192.168.10.234:45000 en LAN)
5. Un jugador crea sala, los demás se unen

Troubleshooting

• "Different ROM" error: Todos los jugadores deben tener exactamente el mismo archivo ROM (se compara MD5)
• No se puede conectar: Verificar puertos TCP+UDP 45000-45004 abiertos en router
• Cross-emulator no funciona: Todos deben usar el mismo emulador (no mezclar gopher64 con RMG)

---

Dolphin Traversal Server (GameCube / Wii)

Resumen

Dato	Valor
Proyecto	Dolphin Emulator (componente traversal_server)
Lenguaje	C++
Puertos	6262, 6226 (UDP)
RAM	<10 MB

Cómo funciona

Servidor de NAT hole-punching para Dolphin netplay. No retransmite datos de juego — solo facilita la conexión inicial entre dos instancias de Dolphin que están detrás de NAT/firewall. Una vez conectados, el tráfico de juego fluye directamente peer-to-peer.

• Puerto 6262 (UDP): Puerto principal de traversal
• Puerto 6226 (UDP): Puerto alternativo para probar tipo de NAT

El servidor es completamente stateless (sin persistencia), single-threaded, y las entradas de clientes expiran después de 30 segundos de inactividad.

Build

Multi-stage Docker build que compila solo el target traversal_server del repositorio completo de Dolphin. La build es pesada (~20 min) pero el binary final es tiny.

servers/dolphin-traversal/
├── Dockerfile           # Multi-stage: debian build + debian-slim runtime
└── .dockerignore

Configuracion

El traversal server no tiene opciones de configuración. Los puertos (6262/6226) están hardcodeados en el código fuente. No acepta argumentos de línea de comandos ni variables de entorno.

Juegos soportados

TODOS los juegos de GameCube y Wii que se pueden jugar en Dolphin, incluyendo:

• Mario Party 4, 5, 6, 7
• Mario Kart: Double Dash
• Super Smash Bros. Melee
• F-Zero GX
• Kirby Air Ride
• The Legend of Zelda: Wind Waker
• Y cualquier otro juego de GC/Wii

Conexion de cliente

1. Descargar Dolphin Emulator
2. Ir a Config → General → Netplay (o Config → Network en versiones nuevas)
3. Cambiar Traversal Server a: play.consultoria-as.com
4. Traversal Port: 6262
5. Un jugador hostea (NetPlay → Host), los demás se unen con el Host Code generado
6. Todos necesitan la misma ISO/ROM del juego

Troubleshooting

• No se genera Host Code: Verificar que los puertos UDP 6262 y 6226 están abiertos
• Conexión lenta o fallida: El traversal solo facilita el handshake; si la conexión P2P falla, los jugadores pueden intentar Direct Connection (requiere que el host abra puertos)
• Sin logs: Normal — el servidor no logea nada por defecto (solo errores a stderr)
• Desyncs en juego: Ambos jugadores deben usar la misma versión de Dolphin y la misma ISO

---

Operaciones Comunes

Ver logs de un servidor

docker logs -f minecraft-ftb          # Minecraft
docker logs -f maple2-world           # MapleStory 2 World
docker logs -f docker-openfusion-1    # OpenFusion
docker logs -f sm64coopdx             # SM64 Coop
docker logs -f n64-netplay            # N64 Netplay (Mario Party)
docker logs -f dolphin-traversal      # Dolphin Traversal (GC/Wii)

Reiniciar un servidor

docker restart minecraft-ftb
docker restart maple2-world maple2-login docker-maple2-game-ch0-1
docker restart docker-openfusion-1
docker restart sm64coopdx
docker restart n64-netplay
docker restart dolphin-traversal

Ver uso de recursos

docker stats --no-stream

Backup de datos

# PostgreSQL (CMS)
docker exec docker-postgres-1 pg_dump -U afterlife afterlife > backup_cms.sql

# MySQL (MapleStory 2)
docker exec maple2-db mysqldump -u root -pmaplestory --databases maple-data game-server > backup_ms2.sql

# Minecraft (mundo completo)
docker cp minecraft-ftb:/data/world ./backup_minecraft_world/