Redes proxy (BungeeCord / Waterfall / Velocity)

ResourcePackManager funciona en redes proxy. Hay un único jar — ResourcePackManager.jar — y debes instalar el mismo jar en cada backend y en el proxy. En un backend se ejecuta en rol de backend (fusionar, alojar, enviar, convertir); en un proxy de Velocity o BungeeCord/Waterfall el mismo jar autodetecta el cargador de la plataforma y se ejecuta en rol de proxy (entrega de Bedrock a nivel de red). Los dos roles se encuentran automáticamente mediante el archivo compartido plugins/floodgate/key.pem — sin jar de proxy separado, sin extensión de proxy que extraer, sin clave que pegar.

A lo largo de esta página, "el plugin del proxy" es la forma abreviada de referirse a ese mismo ResourcePackManager.jar ejecutándose en rol de proxy.

Qué hace el plugin del proxy

El trabajo del plugin del proxy es la fusión y entrega del paquete de Bedrock. En una red con varios backends, cada backend produce su propio paquete de Bedrock (la versión convertida de su paquete Java fusionado). El plugin del proxy:

1. Sondea el pequeño servidor HTTP de cada backend cada 5 segundos en busca de /bedrock.zip y /mappings.json, usando If-Modified-Since para que los archivos sin cambios cuesten aproximadamente cero ancho de banda. Cada backend anuncia el puerto HTTP exacto al que se enlazó, por lo que el proxy normalmente da con el puerto correcto automáticamente (consulta Resolución del puerto HTTP del backend).
2. Espera a que el estado de la bandeja de entrada se estabilice — fusiona en cuanto dos sondeos adyacentes observan el mismo conjunto de hashes de archivos.
3. Fusiona el paquete de Bedrock de cada backend en un único paquete a nivel de red.
4. Copia el archivo fusionado de mappings personalizados de Geyser en plugins/Geyser-*/custom_mappings/ del proxy.
5. Sirve el paquete fusionado a los clientes de Bedrock al conectarse mediante el SessionLoadResourcePacksEvent de Geyser.

El plugin del proxy solo es útil para jugadores de Bedrock. La entrega del paquete Java en redes sigue ocurriendo por backend a través de la API habitual de setResourcePack / addResourcePack — los clientes de Java ven el paquete del backend en el que estén, según lo que ese backend haya decidido enviar. Si tu red es solo de Java, no necesitas el plugin del proxy.

Configuración — dos pasos

Paso 1: Instala Floodgate en el proxy y en cada backend

Floodgate es necesario para que los jugadores de Bedrock se autentiquen en el proxy. RSPM se apoya en plugins/floodgate/key.pem de Floodgate para derivar la identidad de red — ese archivo debe ser idéntico byte a byte en el proxy Y en cada backend. Floodgate ya lo requiere para la autenticación de Bedrock, así que si los jugadores de Bedrock funcionan actualmente en tu red, esto ya está hecho.

Si aún no tienes Floodgate, instálalo en cada componente y luego copia un key.pem canónico a todos los demás componentes antes de continuar.

Paso 2: Copia ResourcePackManager.jar al proxy

Solo hay un jar. El mismo ResourcePackManager.jar que instalas en los backends de Bukkit/Paper es también el plugin del proxy — incluye las implementaciones de Velocity y BungeeCord/Waterfall juntas en un único jar sombreado y autodetecta en qué plataforma se está ejecutando. No hay un jar de proxy específico por plataforma que extraer.

Copia el mismo ResourcePackManager.jar en la carpeta plugins/ de tu proxy:

Software de proxy	Usa este jar
Velocity	ResourcePackManager.jar
BungeeCord	ResourcePackManager.jar
Waterfall (fork de Bungee)	ResourcePackManager.jar

Puedes confirmarlo desde un backend en cualquier momento ejecutando /rspm status; la sección Proxy deployment imprime Network proxy jar: ResourcePackManager.jar y Use the same jar on Bukkit/Paper, Velocity, and BungeeCord/Waterfall.

Reinicia el proxy. Eso es todo.

Intencionadamente no hay configuración que editar ni clave que pegar. El plugin del proxy lee plugins/floodgate/key.pem en el proxy al arrancar y deriva la identidad de red a partir de él. Dado que Floodgate ya requiere que ese archivo sea el mismo en cada backend y en el proxy, la clave derivada coincide automáticamente con la de cada backend.

El primer sondeo del proxy se dispara ~2 segundos después del arranque, y luego cada 5 segundos. Combinado con la verja de estabilidad de un solo ciclo, la primera fusión se publica aproximadamente 7 segundos después de que el proxy pueda ver al menos un backend que ya esté produciendo contenido.

Verificar que funciona

Consola del proxy

En ~10 segundos tras el reinicio (suponiendo que los backends están en marcha) deberías ver:

[ResourcePackManager] Network-key auto-derived from Floodgate key.pem ✓
[ResourcePackManager] NetworkSync starting (poll interval 5000 ms, network-http-offset 1 - endpoint announcements preferred, fallback HTTP port = mcPort + offset)
[ResourcePackManager] NetworkSync: inbox stabilized — merging 2 Bedrock zip(s) and 2 mappings file(s) across 2 backend(s).
[ResourcePackManager] Merged Bedrock pack published at .../merged/Bedrock.zip (sha1=...).
[ResourcePackManager] ✔ Network resource pack is now ready (... KB, sha1 ABCD1234)

/rspm status en el proxy

Imprime una instantánea: lista de backends, resultados de obtención por ruta y por backend (200 / 304 / 404 / CONNECT_FAILED), contador de sondeos vacíos consecutivos, ruta + tamaño del paquete fusionado actual, network-http-offset, y presencia de Floodgate / Geyser en el proxy. Requiere resourcepackmanager.command.status o resourcepackmanager.*. La consola siempre tiene ambos; concede uno a los jugadores a través de tu plugin de permisos si quieres que puedan ejecutarlo. La salida no revela secretos (la clave de red está enmascarada, no hay tokens de autenticación), por lo que conceder estos permisos de forma amplia es seguro.

/rspm status en un backend

La línea Deploy mode debería indicar network-backend. La línea Network key debería mostrar una clave enmascarada (los últimos 4 caracteres visibles) — compárala con la clave enmascarada del proxy para confirmar que ambos lados coinciden.

Cliente de Bedrock

Conéctate vía Bedrock. Deberías ver el aviso de descarga del paquete de recursos antes de llegar al mundo. Los ítems personalizados se renderizan con sus modelos previstos en lugar de simples soportes de armaduras (armor stands).

Referencia de configuración

Backend plugins/ResourcePackManager/config.yml

El modo de red se autodetecta — no hay un flag networkMode: true que establecer. Señales de detección (cualquiera es suficiente):

1. Floodgate presente, Geyser-Spigot ausente — la señal más fuerte para el caso de Bedrock-vía-proxy.
2. spigot.yml: settings.bungeecord: true — interruptor heredado de reenvío de IP de BungeeCord / Waterfall.
3. paper-global.yml: proxies.velocity.enabled: true — reenvío moderno de Velocity.

El único parámetro que importa específicamente para el modo de red es networkHttpOffset-v2, que controla el puerto HTTP de respaldo que el proxy sondeará en cada backend (el puerto que el proxy adivina antes de que un backend haya anunciado el puerto al que realmente se enlazó). El valor por defecto 1 funciona en prácticamente todos los alojamientos. Consulta Autoalojamiento para la historia completa de la resolución de puertos.

En operación normal, cada backend anuncia su puerto HTTP real al proxy automáticamente (a través del registro de endpoints de magmaguy.com), por lo que el desplazamiento solo se consulta como respaldo de arranque/fallo. Consulta Resolución del puerto HTTP del backend más abajo.

Proxy plugins/ResourcePackManager/config.yml

El plugin del proxy escribe una configuración mínima por defecto en el primer arranque:

# Force clients to accept the pack (kick on decline). Default: false.
force-resource-pack: false

# FALLBACK offset added to each backend's Minecraft port to derive the HTTP
# port this proxy will hit for /bedrock.zip and /mappings.json BEFORE that
# backend has announced its real ResourcePackManager HTTP port. Default 1.
# In normal operation the backend announces the exact port it bound, so this
# value is only used at startup or if announcement fails — but if it IS used,
# it should match each backend's networkHttpOffset-v2.
network-http-offset-v2: 1

Intencionadamente no hay una entrada network-key — se retiró antes del lanzamiento porque pegar la clave manualmente era una fuente importante de mala configuración (las erratas rompían silenciosamente el enlace proxy↔backend). La clave se deriva automáticamente de plugins/floodgate/key.pem.

Resolución del puerto HTTP del backend

El proxy necesita saber qué puerto HTTP sondear en cada backend para /bedrock.zip y /mappings.json. Resuelve ese puerto en este orden:

1. Endpoint anunciado por el backend (preferido). Cada backend sube el puerto HTTP exacto al que se enlazó al registro de endpoints de magmaguy.com, indexado por la clave de red. En cada sondeo, el proxy refresca esta lista y empareja el puerto anunciado de un backend con la entrada de la lista de servidores por el puerto de Minecraft (y por el host cuando está disponible). Esto significa que un administrador que establezca un selfHostPort explícito en un backend, o cuyo backend aterrice automáticamente en mcPort + 1, se gestiona de forma idéntica — el proxy usa lo que el backend realmente haya enlazado.
2. mcPort + network-http-offset-v2 (respaldo). Se usa solo cuando no hay un anuncio coincidente disponible (p. ej. el primer sondeo antes de que ningún backend haya anunciado, o el registro de endpoints está brevemente inaccesible). Por eso los dos desplazamientos deberían seguir coincidiendo si dependes del respaldo.

El proxy deliberadamente no hace escaneo de puertos en un backend como respaldo — eso parece comportamiento abusivo para el host. Cuando la obtención directa no puede funcionar en absoluto, la ruta de relevo (más abajo) es la respuesta categórica.

/rspm status en el proxy muestra, por backend, qué puerto se eligió y si provino de un anuncio o del respaldo del desplazamiento.

Estabilidad y cadencia de fusión

El proxy espera a que el estado de la bandeja de entrada se estabilice antes de fusionar: el primer sondeo establece el conjunto base de hashes de archivos, y el siguiente sondeo que observa el mismo conjunto dispara la fusión (una verja de estabilidad de un ciclo). Con el retardo inicial de ~2 s y el intervalo de sondeo de 5 s, eso sitúa la primera fusión ~7 s después de que el proxy pueda ver al menos un backend produciendo contenido. Las fusiones posteriores solo vuelven a comprimir cuando cambia el conjunto SHA-1 de los archivos de la bandeja de entrada, por lo que un periodo largo de inactividad cuesta aproximadamente nada.

Los backends escriben su bedrock.zip en un archivo temporal y lo renombran de forma atómica, de modo que la ruta /bedrock.zip siempre sirve un zip completo — el proxy nunca tiene que defenderse de lecturas a medio escribir, razón por la cual la verja es de un solo ciclo en lugar de dos.

Obtención directa vs respaldo por relevo

La ruta por defecto es la obtención directa: el proxy hace un HTTP GET a http://<backend-host>:<mcPort + offset><path> para cada backend.

Si el proxy no puede alcanzar directamente el puerto HTTP de un backend (típico de los alojamientos de Minecraft compartidos / gestionados donde los puertos MC están expuestos pero los puertos adyacentes están bloqueados por el firewall), el backend envía su bedrock.zip y mappings.json a un endpoint de relevo en magmaguy.com bajo el namespace de la red (derivado de la clave de Floodgate). El proxy lista y descarga desde el relevo cuando la obtención directa falla por completo.

Ambas rutas alimentan el mismo paso de fusión, por lo que el operador nunca tiene que elegir — la obtención directa es la preferida (coste de ancho de banda cero para magmaguy.com), el relevo entra de forma transparente cuando es necesario.

El relevo tiene un TTL de 30 minutos del lado del servidor. Los backends hacen push cada 25 minutos para mantener viva la entrada; un apagado limpio elimina la entrada de inmediato en lugar de esperar al TTL.

Solución de problemas comunes

"Floodgate key.pem missing" al arrancar el proxy

El plugin del proxy no pudo encontrar plugins/floodgate/key.pem y quedó inactivo. RSPM no puede enlazar con ningún backend sin él.

Solución: instala Floodgate en el proxy y luego asegúrate de que plugins/floodgate/key.pem en el proxy sea idéntico byte a byte al mismo archivo en cada backend. Floodgate genera automáticamente claves distintas por instalación por defecto — copia un key.pem canónico de cualquier backend a todos los demás componentes y reinicia todo.

Advertencia "No merged pack content" tras ~20 segundos

Tras 4 ciclos de sondeo vacíos consecutivos, el proxy registra una advertencia única de varias líneas que lista cada backend que sondeó, la URL que intentó y el resultado. La advertencia explica las soluciones más comunes:

• CONNECT_FAILED en cada backend — el proxy no puede alcanzar el puerto HTTP del backend en absoluto. Comprueba que la dirección en velocity.toml / config.yml sea una que el proxy pueda alcanzar realmente (no un nombre interno de Docker que no se resuelve desde la red del proxy) y que el puerto HTTP del backend esté abierto entre el proxy y el backend. La advertencia imprime el host:puerto HTTP exacto que intentó para cada backend y si ese puerto provino del anuncio del backend o del respaldo mcPort + networkHttpOffset-v2. Si no tienes forma de abrir ese puerto (alojamiento gestionado), consulta la sección de respaldo por relevo más arriba — el backend debería estar subiendo al relevo automáticamente.
• NOT_FOUND_404 en cada backend — los backends están en marcha pero no producen un paquete de Bedrock. Ejecuta /rspm status en cada backend; el bloque de diagnóstico del paquete Bedrock te dirá por qué (lo más frecuente: no hay definiciones de ítems en el paquete fusionado, o el primer ciclo de mezcla aún no se ha completado).

La advertencia se dispara una vez por periodo de atasco. Se registra una línea NetworkSync: recovered cuando al menos un backend vuelve a devolver contenido.

Los jugadores de Bedrock no ven modelos personalizados en el primer arranque del proxy

Geyser registra su tabla de ítems personalizados solo al arrancar el proxy. Si el proxy arrancó antes de que ningún backend produjera un paquete de Bedrock, Geyser se ejecuta con una tabla de mappings vacía y permanece así durante el resto de la sesión.

Solución: reinicia el proxy una vez después de que el backend haya registrado su primera línea Merged Bedrock pack published. RSPM predespliega los mappings de la ejecución anterior en cada arranque del proxy, por lo que esto solo afecta en una instalación completamente nueva — los arranques posteriores tienen algo listo antes de que Geyser escanee.

Advertencias "Duplicate bedrock_identifier" al arrancar el proxy

Dos backends emitieron el mismo identificador de Bedrock para el mismo ítem base. Gana el último que escribe; inofensivo si solo necesitas que un backend proporcione ese ítem. Si ambos backends deben alojar ítems personalizados distintos bajo el mismo ítem base, renombra uno de los modelos Java de origen para que los hashes autogenerados difieran.

El jugador de Bedrock se conectó pero no ve el paquete

El proxy dispara un banner de chat a todos los jugadores de Java en línea cuando una sesión de Bedrock se carga sin un paquete de RSPM utilizable:

⚠ [RSPM] Bedrock player Alice connected before the resource pack was ready — they're seeing plain armor stands instead of custom models. Tell them to disconnect and reconnect; the pack will load on their next session. (Cause: ...)

El propio jugador de Bedrock también recibe una ventana emergente modal, y la consola del proxy recibe un banner. Si necesitas profundizar más, activa el flujo de depuración (disponible tanto en Velocity como en BungeeCord):

/rspm debug bedrock on

Eso activa las líneas de log verbosas [RSPM-BedrockDebug] de GeyserBinder. Reproduce el problema y luego desactívalo:

/rspm debug bedrock off

La opción se restablece a off al reiniciar el proxy, de modo que no puede quedarse activada accidentalmente.

Actualizar RSPM en una red

Tras subir la versión del jar de RSPM del backend, vuelve a copiar también el mismo ResourcePackManager.jar a la carpeta plugins/ del proxy y reinicia el proxy. Es el mismo jar en cada backend y en el proxy, así que mantén todos los componentes en la misma versión.

Lo que aún no se soporta

• Paquetes Java en redes a través del plugin del proxy. Los clientes de Java reciben paquetes de cada backend directamente a través de la API habitual. No hay un mezclador de paquetes Java del lado del proxy.
• Fusión de paquetes Java entre backends. El paquete Java de cada backend es independiente. Si un jugador cambia de backend, recibe el paquete del nuevo backend.
• Reconfiguración en vivo de la clave de red. La clave está ligada al key.pem de Floodgate. Cambiarla requiere reiniciar el proxy Y cada backend (que es lo que harías de todos modos al rotar la clave de Floodgate).