Solución de problemas de Resource Pack Manager

Esta página solo cubre el comportamiento que está confirmado actualmente en el código de ResourcePackManager.

El primer paso más útil para cualquier problema de RSPM es:

/rspm status

Imprime la versión, el modo de despliegue (independiente vs network-backend), una huella corta y no secreta de la clave de red más de dónde vino esa clave, el estado de los paquetes Java + Bedrock, la ruta de entrega activa con la URL, el host externo resuelto + la IP pública autodetectada, todos los flags de configuración relevantes, un recordatorio de despliegue del proxy (el jar del proxy de red es el mismo ResourcePackManager.jar) y la detección de Floodgate / Geyser-Spigot. El mismo comando existe cuando el jar se ejecuta en un proxy e imprime los equivalentes del lado del proxy (lista de backends, resultados de obtención por backend, estado del paquete fusionado).

La consola está callada a propósito

RSPM imprime una línea cada vez que inicializa de cero una ruta de entrega — el resultado:

[ResourcePackManager] Resource pack is live via self-hosting — http://play.example.com:25566/rspm.zip
[ResourcePackManager] Resource pack is live via automatic hosting — https://magmaguy.com/rsp/<uuid>

Todo lo demás — cada paquete preparado, cada clúster fusionado, cada comprobación de estabilidad, cada sondeo de autoalojamiento y su resultado — se suprime por defecto. Una condición de la que RSPM se recupera por sí mismo no se reporta como advertencia. Si un sondeo de autoalojamiento falla y RSPM cambia silenciosamente al alojamiento remoto, eso es un éxito, no un fallo, y la consola no dice nada al respecto.

Así que: la ausencia de advertencias no es prueba de que no haya pasado nada, y la presencia de la línea de resultado significa que los jugadores están recibiendo un paquete. Antes de reportar un fallo de alojamiento o de fusión, activa la narración:

/rspm verbose on

y luego /rspm reload. Ese comando escribe verboseLogging: true en plugins/ResourcePackManager/config.yml por ti y la opción sobrevive a los reinicios, así que ejecuta /rspm verbose off cuando termines. Editar la clave a mano hace lo mismo. El convertidor de Bedrock tiene un interruptor aparte, bedrockConverterDebug, que es solo de configuración.

Las advertencias que sí puedes ver legítimamente son fallos genuinos: fallo repetido en la entrega del paquete a un jugador concreto, un cliente informando de INVALID_URL, un puerto HTTP que no se pudo enlazar, el fallo de ambas rutas de entrega, o un proxy que ha sondeado varios ciclos sin que ningún backend produzca contenido.

Los jugadores no están recibiendo el paquete de recursos

Comprueba primero estos puntos:

• autoHost debe estar activado si quieres la entrega automática normal (selfHostForce es la anulación explícita para pruebas)
• el paquete fusionado debe existir y al menos una ruta de entrega (autoalojamiento o remoto) debe haber tenido éxito
• los jugadores solo reciben el paquete al conectarse, o mediante la difusión de la primera subida que se dispara en el momento en que el alojamiento queda listo
• los jugadores de Floodgate se omiten intencionadamente en la entrega de Java porque Geyser es el dueño de su sesión de paquete de Bedrock

Si es necesario:

1. Ejecuta /rspm status y mira la sección "Hosting". Active delivery muestra si el autoalojamiento, el remoto o ninguno está actualmente en uso.
2. Si "active delivery: not yet ready" — la mezcla o la subida aún están en curso. El plugin muestra un banner llamativo en la consola cuando un jugador se conecta demasiado pronto y enviará automáticamente el paquete en el momento en que la entrega esté lista.
3. Si "active delivery: none — hosting disabled or failed" — autoHost está desactivado, o los sondeos de autoalojamiento y la subida remota fallaron ambos. Consulta "Las comprobaciones de cordura del autoalojamiento fallaron" y "El alojamiento automático no puede contactar con el servidor remoto" más abajo.
4. Pon verboseLogging: true, ejecuta /rspm reload, observa la consola en busca de los resultados de la subida / del sondeo de autoalojamiento, y luego vuelve a conectarte con un jugador de prueba. (Sin esa opción los pasos del sondeo no se imprimen — solo la línea final de resultado "Resource pack is live via ...".)

La oferta al conectarse se retrasa alrededor de un segundo. Si un cliente de Java informa de FAILED_DOWNLOAD o DISCARDED, RSPM lo reintenta automáticamente hasta tres intentos para esa sesión de jugador. No reintenta un rechazo del jugador ni un INVALID_URL; el agotamiento repetido de reintentos y las URLs inválidas sí se registran como fallos reales.

Si estás autoalojando a través de tu propia canalización externa (autoHost: false), RSPM no envía tu URL personalizada por ti. En esa configuración aún necesitas tu propio flujo de entrega de paquete desde el servidor.

ItemsAdder está instalado, pero su contenido falta en el paquete final

Esto suele significar que ItemsAdder sigue configurado de una forma que impide a ResourcePackManager leer o alojar su salida.

Usa:

/rspm itemsadder configure

Ese comando actualmente:

• activa resource-pack.hosting.no-host.enabled
• desactiva protection_1, protection_2 y protection_3
• establece resource-pack.zip.compress-json-files: false
• ejecuta /iareload y luego /iazip
• recarga ResourcePackManager unos 15 segundos después

Si el comando te indica que ItemsAdder ya está alojando su propio paquete, desactiva manualmente el alojamiento de ItemsAdder primero y vuelve a ejecutar el comando.

El paquete fusionado es inválido o no se sube

La integración de alojamiento automático de ResourcePackManager gestiona explícitamente estos tipos de errores del lado del servidor:

• archivos requeridos faltantes
• archivo demasiado grande
• formato de archivo no válido
• sesión faltante
• servidor remoto no disponible

Si te topas con uno de estos:

1. Ejecuta /rspm reload para reconstruir el paquete.
2. Comprueba si uno de los paquetes fuente está mal formado, cifrado o es ilegible por algún otro motivo.
3. Comprueba si el paquete final fusionado todavía contiene un pack.mcmeta y un pack.png válidos en la raíz.

Si un paquete activado no se puede extraer o preparar, la mezcla actual se aborta y la consola indica cuál es el paquete que falla. Repara ese paquete, elimina un ZIP añadido manualmente o pon isEnabled: false en su configuración de integración automática antes de recargar.

Un paquete roto ya no bloquea todo para siempre

Un paquete que no se puede preparar falla igual en cada reintento, así que si se deja tal cual atascaría la entrega de forma permanente — la fusión nunca se completa y el mismo error se repite indefinidamente. Tras tres fallos consecutivos del mismo archivo, RSPM saca ese paquete de la fusión para que los demás puedan distribuirse, y lo dice una vez, bien alto:

[ResourcePackManager] Resource pack X.zip failed to stage 3 times in a row and has been excluded
from the merge so the remaining packs can be delivered. The merged pack is now INCOMPLETE ...

Léelo tal como está pensado: los jugadores ahora reciben un paquete al que le falta el contenido de ese plugin. La causa habitual es un zip corrupto o escrito a medias.

La exclusión se limpia sola. El registro del fallo se indexa por el tamaño y la fecha de modificación del archivo, así que reparar o reemplazar el archivo retira automáticamente la cuarentena y el paquete vuelve a la siguiente fusión — sin comando, sin reinicio. /rspm reload también reinicia desde cero todos los registros de cuarentena. Los recuentos de fallos que nunca llegaron a tres se descartan tras cualquier mezcla exitosa, de modo que contratiempos transitorios sin relación entre sí repartidos a lo largo de un tiempo de actividad largo no pueden acumularse hasta provocar una exclusión.

Ante un error SESSION_NOT_FOUND del auto-host remoto, RSPM borra su UUID de sesión y se reinicializa en el siguiente tick de keep-alive — sin intervención manual.

Los assets de un plugin están sobrescribiendo los de otro plugin

Esto se controla mediante priorityOrder en:

plugins/ResourcePackManager/config.yml

Las entradas superiores ganan sobre las inferiores.

Para archivos no fusionables, ResourcePackManager reemplaza el archivo de menor prioridad. Para archivos JSON fusionables, fusiona el contenido en su lugar. Las categorías JSON actualmente fusionables son:

• sounds.json
• archivos de idioma
• JSON de modelos de ítems vanilla en minecraft/models/item (fusión no recursiva: solo se combina el array overrides entre paquetes, el resto del archivo sigue la regla de que gana la mayor prioridad)
• archivos de atlas
• archivos de fuente
• definiciones de modelos de ítems 1.21.4+ en items/ (fusión consciente del formato que respeta la estructura del árbol de predicados)

pack.mcmeta también se fusiona de forma especial: gana el pack_format más alto, los rangos de supported_formats se amplían (se admiten las formas de entero, array de dos enteros y objeto {min_inclusive, max_inclusive}), las entradas de overlay se combinan y las claves de nivel superior no estándar se conservan. Las entradas de overlay se normalizan para compatibilidad con 1.21.9+ añadiendo los campos min_format/max_format cuando faltan. Las fuentes de atlas base también se fusionan en los archivos de atlas de overlay para evitar que los overlays oculten entradas base.

Si necesitas inspeccionar qué ocurrió durante la última fusión, consulta:

plugins/ResourcePackManager/collision_log.txt

El texto de GUI o elementos basados en fuentes se ven mal

Los archivos de fuente son una de las categorías JSON que ResourcePackManager fusiona, pero eso no garantiza que dos sistemas de fuentes distintos convivan bien en Minecraft.

Si un menú o HUD basado en fuentes se ve mal:

1. Cambia priorityOrder para que el paquete que deseas que gane tenga mayor prioridad.
2. Ejecuta /rspm reload.
3. Revisa collision_log.txt para confirmar que las colisiones ocurrieron donde esperabas.

Los cambios del paquete de recursos no aparecen de inmediato

ResourcePackManager tiene un watchdog para las fuentes de paquetes compatibles.

Espera hasta que un paquete modificado permanezca sin cambios durante 3 segundos, y entonces, una vez que todos los paquetes vigilados son estables, la nueva mezcla ocurre inmediatamente.

Si estás regenerando activamente el paquete de otro plugin, dale unos segundos después de que terminen las escrituras de archivos. En caso de duda, ejecuta /rspm reload después de que el plugin de origen haya terminado.

/rspm status dice alojamiento remoto, pero yo esperaba autoalojamiento

Es el comportamiento normal cuando preferSelfHost: true (el valor por defecto) y una de las tres comprobaciones de cordura del autoalojamiento falló. RSPM no avisa de esto — recurrir al alojamiento remoto es un resultado exitoso, así que la comprobación fallida se registra a nivel de detalle con un explícito "This is OK." y permanece oculta salvo que verboseLogging: true. La única línea que obtienes por defecto es Resource pack is live via automatic hosting — ....

Ejecuta /rspm verbose on (o pon verboseLogging: true) y /rspm reload para ver cuál de las tres capas falló:

1. Capa 1 (heurística) — el host externo resuelto es RFC1918 / loopback / link-local. Bien establece selfHostExternalHost a tu hostname público real, o asegúrate de que el plugin pueda alcanzar api.ipify.org / checkip.amazonaws.com.
2. Capa 2 (sondeo a sí mismo en localhost) — una solicitud HEAD a http://127.0.0.1:<port>/rspm.zip no devolvió 200 con un cuerpo no vacío. Detecta colisiones de enlace de puerto o archivos de paquete faltantes.
3. Capa 3 (sondeo de accesibilidad externa) — magmaguy.com intentó obtener tu URL anunciada y no pudo alcanzarla. Lo más común: el puerto HTTP no está reenviado en el router / firewall. La URL del sondeo y un código de motivo (PRIVATE_HOST_REJECTED, CONNECT_TIMEOUT, ECONNREFUSED, RATE_LIMITED, ...) se imprimen bajo verboseLogging.

Soluciones (en orden de preferencia): abre el puerto HTTP en tu firewall + router, establece selfHostExternalHost a un hostname enrutable, o establece preferSelfHost: false para omitir el autoalojamiento por completo.

Cuando el propio sondeo de magmaguy.com es inaccesible (RSPM no puede hablar con él para preguntarle), se mantiene el autoalojamiento en lugar de marcarlo como fallido — el razonamiento es que la ruta de respaldo también necesita magmaguy.com, por lo que negarse a comprometerse por incapacidad de sondear sería paradójico.

Consulta Autoalojamiento para el árbol de decisión completo.

El alojamiento automático no puede contactar con el servidor remoto

El host remoto integrado de ResourcePackManager se comunica con:

https://magmaguy.com/rsp/

Si esa conexión falla, el plugin registra advertencias de comunicación y no puede usar el respaldo remoto hasta que vuelva a conectar correctamente.

Tus opciones son:

1. arreglar la conectividad HTTPS saliente del servidor
2. esperar a que el servicio remoto vuelva a estar accesible
3. desactivar autoHost y alojar el zip generado tú mismo
4. abrir tu puerto HTTP, establecer selfHostExternalHost a tu hostname público y mantener preferSelfHost: true. El hostname explícito omite la autodetección de la IP pública, pero RSPM sigue intentando el sondeo de la Capa 3. Si el propio servicio de sondeo es inaccesible, RSPM mantiene el autoalojamiento en lugar de tratar ese fallo de comunicación como prueba de que tu URL es inalcanzable.

Quiero autoalojar el paquete fusionado a través de mi propio servidor web

La configuración soportada por el código es:

1. Establece autoHost: false.
2. Establece resourcePackRerouting si quieres que ResourcePackManager escriba una copia adicional en una carpeta existente.
3. Aloja ResourcePackManager_RSP.zip tú mismo.

resourcePackRerouting se resuelve relativo al directorio plugins, y la carpeta de destino debe existir previamente.

Si en cambio quieres usar el servidor HTTP de autoalojamiento integrado de RSPM (cosa distinta — la misma JVM que el plugin), consulta Autoalojamiento.

Necesito inspeccionar qué datos remotos están almacenados para este servidor

Usa:

/rspm data_compliance_request

Si hay una sesión de alojamiento remoto activa, ResourcePackManager descarga la respuesta en:

plugins/ResourcePackManager/data_compliance/data.zip

RSPM también escribe un ReadMe.md en esa misma carpeta data_compliance.

Si no hay sesión remota (p. ej. estás usando autoalojamiento), el comando informa que no hay datos remotos que solicitar.

El paquete de Bedrock no se está generando

bedrockConversionEnabled por defecto es true, así que debería ejecutarse automáticamente. Ejecuta /rspm status primero — la sección del paquete Bedrock te dirá por qué el paquete no está en disco:

• "No Bedrock target detected" — no hay Geyser-Spigot local, no hay Floodgate local y no está en modo de red. La conversión se omite intencionadamente. Instala Floodgate (para configuraciones de proxy) o Geyser-Spigot (para configuraciones independientes) y ejecuta /rspm reload.
• "Network mode is active so this backend SHOULD produce a Bedrock pack. The file is missing" — normalmente el primer ciclo de mezcla aún no se ha completado (espera ~30 s tras el arranque), o la conversión no encontró ni mappings de ítems convertibles ni paquetes de entidades permitidos, o la conversión lanzó una excepción. Busca en la consola advertencias [BedrockConverter] o la línea Generic scanner: discovered 0 items definition files.

Si falla la autodetección de Geyser:

1. Establece bedrockGeyserFolder en config.yml a la ruta de tu carpeta de datos de Geyser (p. ej. Geyser-Spigot).
2. Las rutas absolutas funcionan. Una ruta relativa se prueba primero desde el directorio de trabajo del servidor y después relativa al directorio plugins.

El convertidor autodetecta Geyser en plugins/Geyser-Spigot/, cualquier variante plugins/Geyser-*/, o config/Geyser-*/ para configuraciones Fabric/NeoForge.

Para salida de log por ítem / por hueso, establece bedrockConverterDebug: true y recarga.

Bedrock: el proveedor en vivo se omitió porque existe un paquete heredado

Si la consola informa de Legacy RSPM Bedrock pack detected, Geyser ya escaneó un ResourcePackManager_Bedrock.zip antiguo de su directorio de paquetes durante el arranque. Borrar ese archivo mientras el proceso está en marcha dejaría a Geyser con un códec en memoria para una ruta que ya no existe, así que RSPM omite deliberadamente su proveedor de paquetes en vivo durante ese arranque.

Detén el servidor por completo, borra únicamente la ruta exacta del archivo heredado que RSPM imprimió y vuelve a arrancar el servidor. No uses /reload para esta migración. El paquete actual permanece en plugins/ResourcePackManager/output/ y se sirve por sesión; no pertenece al directorio packs/ de Geyser.

Los jugadores de Bedrock ven los ítems en mano en una posición incorrecta

Esto es un problema de ajuste, no un fallo de conversión. Abre plugins/ResourcePackManager/bedrock_display_offsets.yml, ajusta el eje pertinente, ejecuta /rspm reload y reconecta el cliente de prueba de Bedrock para que su siguiente conexión reciba el paquete reconstruido. La primera persona y la tercera persona son independientes — ajustar una no afecta a la otra. Consulta Conversión a Bedrock para ver la lista completa de parámetros y lo que controla cada uno.

Las texturas de armadura personalizadas faltan en los jugadores de Bedrock

La armadura personalizada se renderiza en Bedrock combinando la geometría de armadura vanilla con la textura Java como capa visible. Para que esto funcione, el paquete del plugin de origen debe definir un archivo de equipamiento bajo assets/<namespace>/equipment/<material>.json junto a la definición del ítem. Si el log de conversión muestra el ítem pero no aparece textura de armadura en el juego, verifica que ese archivo existe en el paquete fusionado.

Proxy: un backend dice que no tiene clave de red

En el backend, /rspm status muestra Network key source: not set — the proxy sends one when a player next connects here, y la consola repite "This backend is behind a proxy but has no network key yet".

Que falte plugins/floodgate/key.pem no es la causa — ese archivo ahora es opcional. El proxy es el dueño de la clave: carga su propio archivo network-key, o la siembra una vez desde el key.pem de Floodgate si está presente, o genera una clave nueva, y luego se la envía a cada backend cuando un jugador se conecta allí.

Comprueba, en orden:

1. ¿Se ha conectado algún jugador a ese backend desde que arrancó el proxy? La concesión viaja con una conexión de jugador.
2. ¿Está ResourcePackManager.jar realmente en el proxy? El backend prepara una copia de su propio jar por ti en plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar e imprime esa ruta — cópialo al plugins/ del proxy y reinicia el proxy.
3. En Velocity con reenvío moderno, ¿coincide el secreto de reenvío del backend con el del proxy? Un backend con reenvío moderno rechaza deliberadamente una concesión sin firmar o mal firmada; su log indica cuál de los dos casos es. Corrige el secreto en ambos lados y la siguiente conexión de un jugador lo reintenta por sí sola.
4. Compara las líneas Network key fingerprint de /rspm status en ambos lados. Huellas idénticas significan que el enlace está bien; la clave en sí nunca se imprime.

Consulta Redes proxy para la secuencia completa.

Proxy: "Could not save the network key"

El proxy resolvió una clave pero no pudo escribirla en su archivo network-key. Este arranque sigue funcionando. El siguiente reinicio genera una clave distinta, y cada backend ya aprovisionado conserva la antigua y rechaza la nueva — toda la red se desenlaza silenciosamente.

Corrige los permisos del sistema de archivos en la carpeta de datos del plugin del proxy antes de reiniciar.

Proxy: "no merged pack" tras varios ciclos de sondeo

Tras ~20 segundos de ciclos de sondeo vacíos (4 ciclos × intervalo por defecto de 5 s) en el proxy, RSPM registra un banner de diagnóstico único que lista cada backend que sondeó, la URL HTTP que intentó y el resultado (200 / 304 / 404 / CONNECT_FAILED / etc.). El banner explica las soluciones más comunes:

• CONNECT_FAILED en cada backend → el proxy no puede alcanzar el puerto HTTP del backend. Comprueba que la dirección en velocity.toml / config.yml sea una que el proxy pueda alcanzar realmente (no, p. ej., un nombre interno de Docker que no se resuelve desde la red del proxy) y que el puerto HTTP anunciado del backend esté abierto entre el proxy y el backend. El banner imprime la URL exacta que intentó; antes de que un backend haya anunciado su puerto, el proxy recurre a mcPort + network-http-offset-v2, por lo que un CONNECT_FAILED temprano también puede significar que ese puerto de respaldo aún no es accesible.
• 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é.

El banner se dispara una vez por periodo de atasco y se registra una línea "NetworkSync: recovered" cuando al menos un backend vuelve a devolver contenido. Consulta Redes proxy para más información.

Proxy: Los jugadores de Bedrock no ven modelos 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.

La solución es reiniciar el proxy una vez que el proxy haya registrado Merged Bedrock pack published at .... RSPM predespliega los mappings de la ejecución anterior al arrancar el proxy, por lo que esto solo afecta en una instalación completamente nueva — los arranques posteriores tienen algo listo antes de que Geyser escanee.

Backend: "Backend HTTP server failed to bind on port X"

En modo de red, el backend expone sus salidas de Bedrock a través de un pequeño servidor HTTP. Si el puerto está en uso o no disponible, verás un bloque [ERROR] de varias líneas en la consola. Soluciones:

• Establece selfHostPort a un valor positivo diferente en config.yml.
• O cambia networkHttpOffset-v2 para alejar el puerto autoderivado de la colisión (p. ej. ¿RCON en mcPort + 1? ponlo en 2 o 3). No necesitas actualizar el proxy para que coincida: una vez que el backend se enlaza correctamente, anuncia su puerto HTTP real al proxy automáticamente, por lo que el propio network-http-offset-v2 del proxy solo importa como conjetura previa al anuncio.

Mientras el servidor HTTP del backend esté caído, el paquete de Bedrock de este backend no llegará al proxy por obtención directa. El respaldo por relevo de magmaguy.com sigue funcionando (el backend envía sus archivos al relevo y el proxy los obtiene a través de allí).

Limpiar una configuración v1 obsoleta

Los operadores que actualizan desde RSPM v1 pueden tener una clave networkHttpOffset (sin -v2) muerta en su config.yml. RSPM v2 intencionadamente no lee la clave antigua — obtienes el valor por defecto de la v2 (1) escrito en la configuración en el siguiente arranque automáticamente. La clave v1 muerta queda en tu config como un artefacto inofensivo hasta que la limpies a mano.