Saltar al contenido principal

Conversión de Java a Bedrock

ResourcePackManager puede convertir el paquete de recursos Java fusionado en un paquete de recursos de Bedrock para que los clientes de GeyserMC vean el mismo contenido personalizado que los clientes de Java. Está activado por defecto.

Cuándo se ejecuta la conversión​

La conversión está condicionada a la presencia de un destino de Bedrock. RSPM considera que hay un destino presente si se cumple cualquiera de estas condiciones:

  1. Geyser-Spigot está instalado en este backend (los jugadores de Bedrock llegan a Geyser localmente).
  2. Floodgate está instalado en este backend (configuración típica de proxy-backend: Floodgate se ejecuta localmente, Geyser está en otro lugar).
  3. El modo de red está activo — RSPM detectó que está detrás de un proxy de Velocity / BungeeCord / Waterfall. El backend produce su paquete de Bedrock y lo expone en un pequeño servidor HTTP para que el plugin del proxy pueda obtenerlo.

Si no se cumple ninguna de estas condiciones, el convertidor es pura sobrecarga y se omite silenciosamente. /rspm status explica exactamente por qué cuando el paquete no se ha generado.

Qué se convierte​

El convertidor es agnóstico respecto al namespace. Recorre cada archivo assets/<namespace>/items/**/*.json en el formato de definición de ítems 1.21.4+, de forma recursiva e incluyendo el namespace minecraft.

Enrutado plano vs 3D​

Para cada modelo hoja el convertidor decide cuál de los dos flujos usar. Los modelos cuya raíz es minecraft:item/generated o minecraft:builtin/generated se quedan en la ruta plana. Para cualquier otra cadena de padres, un modelo baja por el flujo 3D solo cuando el modelo fusionado lleva un array elements no vacío; un modelo sin geometría es un sprite 2D.

  • Plano — la textura layer0 del modelo se copia directamente a textures/items/<hash>.png y se registra como icono de Geyser. En Bedrock el ítem muestra el sprite 2D correcto en el inventario y en la mano, exactamente como lo renderiza Java.
  • 3D — el convertidor cose un atlas de texturas, convierte los cuboides de Java en geometría de Bedrock, genera animaciones de sujeción/cabeza, renderiza por software un icono de inventario de 64×64 y escribe un attachable por cada mapeo (modelo × ítem base × forma del predicado).

Por qué importa la comprobación de geometría: una herramienta de mano plana (padre minecraft:item/handheld con solo una textura layer0 y sin elements) sigue siendo un sprite 2D. Las versiones anteriores empujaban los ítems de mano planos al flujo 3D, donde fallaban en el paso de geometría y desaparecían en Bedrock o recaían en el icono del ítem base vanilla. Esto afectaba especialmente a los paquetes de ItemsAdder, que incluyen muchos ítems de mano planos. Como elements se lee de la cadena de padres fusionada, un modelo no generado que hereda su geometría de un padre se sigue enrutando al flujo 3D.

Se genera un identificador único de Bedrock por cada mapeo (modelo × ítem base × forma del predicado), de modo que un único modelo de espada registrado contra varios ítems base o ramas de predicado no colisione del lado de Geyser. Los nombres de archivo generados son hashes de contenido cortos en lugar de nombres legibles, porque los nombres completos de namespace+ruta superaban habitualmente el límite de 80 caracteres de ruta de paquete de Geyser.

Paquetes heredados anteriores a 1.21.4​

Los paquetes que todavía usan el formato antiguo assets/minecraft/models/item/*.json + overrides[].predicate.custom_model_data también se recogen y se sintetizan a la forma moderna de despacho por rangos. Esto es de mejor esfuerzo: la consola indica cuántos ítems usaron el formato heredado, ya que a menudo no se renderizan correctamente en Bedrock. La solución real es migrar el paquete de origen al formato de definición de ítems 1.21.4+.

Paquetes de entidades de Bedrock escritos a mano​

Un plugin puede incluir recursos nativos de entidades de Bedrock directamente colocándolos bajo assets/<namespace>/rspm_bedrock_pack/ en su paquete de Java. RSPM copia esos archivos tal cual al paquete de Bedrock generado. Solo se aceptan directorios relacionados con entidades (entity, models/entity, animations, animation_controllers, render_controllers, materials, textures/entity), de modo que un plugin contribuyente no pueda tapar el manifest del paquete ni el atlas de iconos. Las rutas demasiado largas se acortan automáticamente, reescribiendo las referencias cruzadas de JSON para que coincidan, de modo que las referencias de geometría y textura sigan resolviéndose. Que dos namespaces escriban bytes distintos en el mismo destino es un error grave, no una sobrescritura silenciosa.

Este es el mecanismo detrás de las verdaderas entidades personalizadas de Bedrock — consulta Extensión de Geyser y entidades personalizadas. Un paquete que contenga solo paquetes de entidades y cero mappings de ítems se sigue distribuyendo.

Los sets de armadura personalizados se detectan cuando existe un archivo hermano assets/<namespace>/equipment/<material>.json. El convertidor cablea un attachable de armadura que combina la geometría de armadura vanilla con la textura Java como capa visible, para que los jugadores de Bedrock vean la textura de armadura correcta al llevar el ítem.

Los UUIDs del header/módulo del manifest del paquete de Bedrock se derivan de forma determinista de la cadena de versión del plugin (semillas rspm_bedrock_header:<pluginVersion> y rspm_bedrock_module:<pluginVersion>), por lo que se mantienen estables entre reconstrucciones de la misma versión del plugin y solo cambian cuando cambia la versión del plugin. El nombre visible del header es el fijo ResourcePackManager Bedrock Pack; no forma parte del UUID. El triplete de versión se incrementa por compilación a partir de un token de invalidación de caché derivado de un resumen de contenido SHA-256 del paquete de Bedrock preparado: contenidos idénticos producen la misma versión (para que las reconstrucciones sin cambios no agiten la caché de Geyser), mientras que los cambios reales de contenido invalidan la caché de paquetes de Bedrock indexada por (uuid, version). El tiempo de compilación (System.currentTimeMillis()) solo se usa como respaldo cuando no se puede calcular el resumen de contenido.

Servicio en vivo por sesión (independiente)​

Cuando se detecta Geyser-Spigot en el mismo backend, RSPM registra un suscriptor a SessionLoadResourcePacksEvent. Cada jugador de Bedrock que se conecte después de una nueva mezcla recibe el paquete de Bedrock más reciente servido directamente desde disco, sin necesidad de reiniciar el servidor para ediciones de textura o modelo de ítems existentes.

Las asignaciones de ítems personalizados de Geyser (el JSON en custom_mappings/) siguen congeladas al arrancar, por lo que añadir nuevos ítems personalizados o eliminar los existentes requiere reiniciar el servidor antes de que los clientes de Bedrock vean esos cambios. RSPM predespliega el archivo de mappings de la ejecución anterior al principio del arranque para que el registro de ítems personalizados de Geyser, durante el arranque, lo recoja automáticamente.

Los jugadores de Bedrock actualmente conectados conservan el paquete que recibieron al conectarse — esa es una restricción del protocolo de Bedrock, no algo que el plugin pueda anular a mitad de sesión.

Cómo funciona en modo proxy​

En una red proxy, el propio backend no registra un suscriptor a SessionLoadResourcePacks (no hay un Geyser local al que suscribirse). En su lugar:

  1. El backend produce output/ResourcePackManager_Bedrock.zip y, cuando existen mappings de ítems, output/rspm_geyser_mappings.json.
  2. El backend inicia un pequeño servidor HTTP (puerto autoderivado, mcPort + 1 por defecto) que expone las rutas /bedrock.zip y /mappings.json, las cuales leen el archivo de forma fresca en cada solicitud, y anuncia al proxy el puerto exacto al que se enlazó.
  3. El plugin del proxy sondea cada 5 segundos, prefiriendo ETags fuertes mediante If-None-Match y manteniendo la compatibilidad con If-Modified-Since para backends más antiguos. Descarga las salidas de cada backend cuando cambian y espera a que la bandeja de entrada se estabilice.
  4. El plugin del proxy fusiona el paquete de Bedrock de cada backend en un único paquete a nivel de red y lo sirve a los clientes de Bedrock a través del Geyser del proxy.
  5. Si el proxy no puede alcanzar directamente el puerto HTTP de un backend (común en alojamientos compartidos/gestionados donde los puertos adyacentes están bloqueados por el firewall), el backend envía sus archivos a un endpoint de relevo en magmaguy.com y el proxy los obtiene a través de allí.

Consulta Redes proxy para la configuración. La fusión del lado del proxy es automática y no tiene interruptor de activación. La configuración del proxy tiene solo dos opciones: network-http-offset-v2, el desplazamiento de puerto de respaldo usado antes de que haya disponible un anuncio de endpoint del backend, y geyser-extension-auto-install, el equivalente del lado del proxy de geyserExtensionAutoInstall.

Archivos de salida​

Tras una mezcla exitosa, los archivos de Bedrock viven en:

plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip
plugins/ResourcePackManager/output/rspm_geyser_mappings.json  # only when item mappings exist

Si el despliegue automático está activado y se detectó una carpeta de datos de Geyser local, el archivo de mappings también se copia a:

<geyser-folder>/custom_mappings/rspm_geyser_mappings.json

El zip del paquete de Bedrock no se copia a <geyser-folder>/packs/ — se sirve en vivo por sesión en su lugar. Si una versión antigua de RSPM dejó ResourcePackManager_Bedrock.zip en el directorio de paquetes de Geyser, el plugin actual no lo borra mientras Geyser está en marcha: Geyser ya ha escaneado esa ruta y puede seguir teniéndolo en memoria. RSPM omite el registro del proveedor en vivo para ese arranque e imprime la ruta heredada exacta. Detén el servidor por completo, borra solo ese archivo heredado y vuelve a arrancar el servidor. Un /reload no es suficiente.

Cuando el convertidor no encuentra nada que publicar (ningún mapping de ítem convertible y ningún archivo permitido de paquete de entidades), RSPM elimina cualquier salida de Bedrock obsoleta de una ejecución anterior en lugar de entregar un paquete vacío. La ruta /bedrock.zip del backend devuelve entonces un 404 limpio, que es la señal correcta para el proxy de que este backend no tiene contenido de Bedrock que aportar. Los paquetes de solo entidades sí se publican.

Opciones en config.yml​

# Toggles Java-to-Bedrock conversion altogether.
bedrockConversionEnabled: true

# Copies the Geyser custom mappings file into the detected Geyser folder's
# custom_mappings/ directory on each mix.
bedrockAutoDeployToGeyser: true

# Manual override for the Geyser data folder. Empty = auto-detect.
# Relative values are tried from the server working directory first, then
# relative to plugins/. Absolute paths work directly.
bedrockGeyserFolder: ""

# Installs and updates the universal ResourcePackManager.jar in Geyser's
# extensions/ folder, which is what makes custom Bedrock ENTITIES render
# instead of armor stands. Separate from pack conversion above — items,
# textures and models convert and serve normally either way.
# Setting this false stops future installation and update staging; it does NOT
# remove an extension jar that is already installed. Delete that by hand while
# Geyser is stopped. See the Geyser extension page.
geyserExtensionAutoInstall: true

# Verbose per-item / per-bone progress logging from the Bedrock pipeline.
# Default false — a clean run emits a single "Bedrock conversion complete: N
# mappings" summary instead of dozens to hundreds of per-item lines. Flip on
# when debugging a specific conversion issue.
bedrockConverterDebug: false

La autodetección de la carpeta de Geyser busca, en orden:

  1. bedrockGeyserFolder si está establecido (se usa tal cual primero, de modo que las rutas relativas se resuelven desde el directorio de trabajo del servidor; si eso no existe, se prueba como relativa a plugins/). Las rutas absolutas también funcionan.
  2. plugins/Geyser-Spigot/
  3. plugins/Geyser-*/ (cualquier variante)
  4. config/Geyser-*/ (para configuraciones Fabric/NeoForge)

Ajuste de la visualización del ítem en mano: bedrock_display_offsets.yml​

Bedrock renderiza el ítem en mano a través de un hueso padre cuya pose de reposo difiere de las transformaciones de primera/tercera persona de Java, por lo que la conversión algorítmica debe aplicar un desplazamiento base por encima de lo que indique la transformación display del modelo Java. Los desplazamientos por defecto funcionan para modelos Java diestros típicos, pero los casos atípicos pueden necesitar ajustes.

La primera persona y la tercera persona son dos pases de renderizado de Bedrock completamente separados (huesos padre distintos, poses de reposo distintas), por lo que cada uno tiene su propio conjunto independiente de seis parámetros. Ajustar uno no afecta al otro.

# ===== First-person (right hand, seen by the holder) =====
firstPersonBaseRotationX: -60.0   # pitch (tipping toward/away from camera)
firstPersonBaseRotationY: 123.0   # yaw (spinning around vertical line)
firstPersonBaseRotationZ: 170.0   # roll (around camera-forward axis)
firstPersonBasePositionX: -8.0    # vertical on screen (positive = up)
firstPersonBasePositionY: 7.5     # depth (positive = further into the scene)
firstPersonBasePositionZ: -5.0    # horizontal on screen (positive = right)

# ===== Third-person (right hand, seen by other players / F5) =====
thirdPersonBaseRotationX: 90.0    # pitch as observers see it
thirdPersonBaseRotationY: 0.0     # yaw
thirdPersonBaseRotationZ: 0.0     # roll around the item's long axis
thirdPersonBasePositionX: 0.0     # horizontal across the holder's body (positive = outward)
thirdPersonBasePositionY: 6.0     # vertical (positive = raises the model)
thirdPersonBasePositionZ: -10.0   # depth relative to holder (positive = forward)

Los valores de posición están en píxeles, donde 1 píxel = 1/16 de bloque. Las rotaciones están en grados.

Cambia el valor, ejecuta /rspm reload y reconecta el cliente de prueba de Bedrock para que su siguiente conexión reciba el paquete reconstruido. Itera hasta que el ítem en mano se vea bien.

Registro de depuración​

Hay dos superficies de depuración disponibles:

  • Backend: bedrockConverterDebug: true en config.yml activa las líneas de log por ítem, por attachable y por mapping del convertidor. Útil cuando necesitas saber por qué un ítem específico no llegó al paquete de Bedrock. Esto es independiente de verboseLogging, que cubre la fusión y el alojamiento de paquetes en lugar de la canalización de Bedrock — para un problema de conversión quieres bedrockConverterDebug.
  • Proxy (Velocity y BungeeCord): /rspm debug bedrock on alterna el flujo de log [RSPM-BedrockDebug] emitido por el GeyserBinder del proxy. Útil cuando los jugadores de Bedrock se conectan al proxy pero no ven el paquete. La opción se restablece a off al reiniciar el proxy, de modo que no puede quedarse activada accidentalmente.

Limitaciones y comportamiento conocido​

  • Los iconos de inventario 3D se renderizan por software a partir de la transformación display.gui del modelo Java. El renderizado es razonable pero no perfecto a nivel de píxel; si el icono se ve mal, la causa más común es un archivo de textura faltante o con el nombre incorrecto referenciado por el modelo.
  • Las texturas de flipbook usadas como iconos de ítem se recortan al fotograma 0 — el item_texture.json de Bedrock no soporta iconos animados, solo texturas animadas de bloques/terreno mediante flipbook_textures.json.
  • La versión de formato de la geometría de attachable está fijada en 1.21.0; actualiza Geyser si tu instalación no puede analizarla.
  • Los archivos heredados de sobrescritura de modelos de ítems vanilla (cualquier cosa bajo assets/minecraft/models/item/, incluyendo shield.json y crossbow.json) se fusionan entre paquetes en lugar de dejar que un paquete gane por completo: solo se combinan los arrays overrides (deduplicados por clave de override), mientras que los campos que no son de override siguen la regla de que gana la mayor prioridad. Ningún archivo recibe un trato especial.
  • Si el convertidor no puede resolver un archivo de textura o modelo referenciado, esa hoja se omite y el resto de la canalización continúa. Activa bedrockConverterDebug para trazas de resolución detalladas. Se emite una advertencia normal cuando un ítem acaba sin ninguna textura personalizada válida o cuando un JSON de modelo referenciado no se puede analizar.
  • Una definición de ítem mal formada es un caso distinto y ahora es fatal para el ciclo: un JSON no analizable aborta toda la conversión con Bedrock conversion failed: ... en lugar de producir en silencio un paquete parcial. Un paquete que antes se convertía "casi entero" ahora te dice que no se convirtió.
  • Los ítems base de estandarte y redstone se omiten. Los ítems personalizados cuya base es uno de los 16 estandartes teñidos o minecraft:redstone no reciben un mapeo de ítem personalizado de Geyser, porque Geyser deriva de esas bases un colocador de bloques inválido. Bedrock muestra el icono vanilla para ellos. La consola indica los ítems afectados cuando ocurre.
  • La conversión se puede cancelar de forma cooperativa: un /rspm reload o un apagado a mitad de proceso aborta limpiamente en lugar de dejar salida escrita a medias. El archivo de mappings de Geyser solo se publica después de que el zip del paquete tenga éxito, así que nunca acabas con un paquete nuevo emparejado con mappings obsoletos.
  • Cuando el paquete fusionado no contiene ni mappings de ítems convertibles ni archivos permitidos de paquete de entidades, no se emite ningún paquete de Bedrock y se elimina cualquier salida de la ejecución anterior. Un paquete de solo entidades sigue siendo válido y se emite aunque haya cero mappings de ítems.

Optimización del tamaño del paquete​

Antes de publicar un paquete de Bedrock, RSPM deduplica los archivos de textura byte a byte idénticos que usan la misma extensión y reescribe las referencias exactas de textura en JSON hacia el archivo conservado. Deliberadamente conserva los alias cuando una referencia es ambigua, está embebida en una cadena más grande o se encuentra en JSON mal formado u opaco, de modo que la optimización no rompa silenciosamente las referencias de recursos.