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 contenido personalizado compatible del paquete 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. El backend produce su paquete de Bedrock y lo expone en un pequeño servidor HTTP para que el plugin del proxy pueda obtenerlo.

La conversión también debe estar activada con bedrockConversionEnabled. Si está desactivada o no hay ningún destino, RSPM retira la salida anterior de Bedrock y omite la conversión. /rspm status indica por qué no se ha generado el paquete.

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.

Selección entre modelos planos y 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. Bedrock usa esa capa como sprite 2D en el inventario y en la mano; esto no conserva cualquier capa adicional ni cualquier rama de modelo de 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 × definición de ítem × 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.

RSPM deriva un identificador de Bedrock para cada mapeo (modelo × ítem base × definición de ítem × forma del predicado). Así separa las distintas variantes de ítem base y predicado de un modelo de espada, y mantiene en identificadores distintos dos definiciones de ítem que reutilizan un mismo modelo. Los nombres de archivo generados usan hashes cortos de los identificadores de origen, no del contenido de los archivos, para evitar la advertencia de Geyser sobre rutas de 80 caracteres o más.

Ramas de modelos de objetos compatibles

La conversión admite los nodos model, condition, range_dispatch y select (con o sin el prefijo minecraft:). Los demás tipos de nodos, incluidos composite y special, se omiten. Que un paquete Java se vea correctamente no demuestra que todas sus ramas puedan representarse en Bedrock.

Nodo	Propiedades compatibles y comportamiento alternativo
condition	broken, damaged, fishing_rod_cast, has_component, custom_model_data. using_item conserva solo on_false como modelo en reposo. Las demás condiciones no compatibles omiten ambas ramas.
range_dispatch	damage, count, bundle_fullness, custom_model_data. use_duration y las demás propiedades no compatibles conservan solo fallback, si existe.
select	charge_type, trim_material, context_dimension, custom_model_data. display_context conserva el caso gui, o su alternativa si no existe un caso GUI. Las demás propiedades no compatibles conservan solo su alternativa.

Esto significa que las fases de tensado del arco de Java y los modelos distintos para cada contexto no se conservan automáticamente en la conversión. Activa bedrockConverterDebug para ver los mensajes sobre nodos y propiedades omitidos y comprueba el objeto resultante en un cliente Bedrock.

Paquetes heredados anteriores a 1.21.4

El lector del formato heredado lee los archivos JSON directamente dentro de assets/minecraft/models/item/ y crea definiciones de despacho por rangos a partir de overrides con un predicate.custom_model_data numérico. No recorre las subcarpetas heredadas ni conserva los demás predicados del override. Por ejemplo, un override que también dependa del tensado de un arco pierde esa condición. El recuento de ítems heredados solo aparece con bedrockConverterDebug activado. Usa el formato de definición de ítems 1.21.4+ para los paquetes que mantengas y contrasta sus ramas con la tabla de compatibilidad anterior.

Ítems base

Geyser asigna cada ítem personalizado a uno o varios ítems base de Java. RSPM los elige así:

• Un archivo de override heredado y una definición assets/minecraft/items/<item>.json en la raíz se asignan a ese ítem vanilla.
• Las demás definiciones se emparejan por nombre de archivo. Las palabras de armas y herramientas se asignan a ítems vanilla relacionados: sword a las seis espadas, pickaxe a los seis picos, wand o staff a minecraft:stick, spear a minecraft:trident, etc. Los nombres de armaduras usan el archivo de equipamiento del namespace o palabras de ranura como helmet y boots. Todo lo demás usa un conjunto de respaldo: papel, palo, etiqueta de nombre, brújula y las seis espadas.
• Las definiciones del namespace freeminecraftmodels también se asignan a minecraft:leather_horse_armor, el ítem que usa FreeMinecraftModels para mostrar los huesos de los modelos.
• Un plugin productor puede declarar los ítems base reales en assets/<namespace>/rspm_item_bases/<path>.json, donde <path> coincide con items/<path>.json. El archivo contiene {"base_items": ["minecraft:blaze_rod"]}. Solo se leen los ID minecraft:, y se añaden a la elección por nombre de archivo. FreeMinecraftModels escribe uno para cada ítem personalizado con el material que indica su configuración, así que una varita sobre BLAZE_ROD muestra su modelo en Bedrock.

Ítems solo para Java

Un plugin productor puede excluir ítems de la conversión colocando un archivo en assets/<namespace>/rspm_item_java_only/<path>.json. Solo importa que el archivo exista. Excluye items/<path>.json y todas las definiciones de ítem bajo items/<path>/, así que esos ítems no reciben mapping de Geyser, icono ni attachable. FreeMinecraftModels lo usa para los ítems de sprite detrás de sus efectos de partículas, que solo usan los item displays de Java; los jugadores de Bedrock ven en su lugar la partícula nativa. Un paquete cuyos ítems son todos solo para Java no activa la advertencia de formato heredado.

Paquetes de entidades de Bedrock escritos a mano

Un plugin puede incluir recursos nativos de entidades de Bedrock bajo assets/<namespace>/rspm_bedrock_pack/ en su paquete Java. RSPM importa esos archivos al paquete de Bedrock generado. Solo acepta directorios relacionados con entidades (entity, models/entity, animations, animation_controllers, render_controllers, materials, particles, textures/entity), por lo que el plugin no puede sustituir el manifiesto ni el atlas de iconos. Las rutas compatibles de 80 caracteres o más se acortan y las referencias exactas a esas rutas en los JSON del mismo conjunto se actualizan. Los demás archivos se copian tal como se suministran. Si dos namespaces producen bytes distintos en el mismo destino, se genera un error.

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.

La conversión de armaduras equipadas se ejecuta en la ruta de ítems planos cuando el ítem base es una armadura o unos élitros. Obtiene <material> del nombre del archivo de definición del ítem, quitando un sufijo de ranura reconocido, y busca assets/<namespace>/equipment/<material>.json en el namespace del modelo hoja. Usa la primera capa de textura de humanoid, humanoid_leggings para pantalones o wings para élitros si existe. El PNG correspondiente debe estar en el paquete fusionado. El attachable generado usa la geometría de armadura vanilla de Bedrock. Un archivo de equipamiento por sí solo, capas de textura adicionales o un ID de recurso de equipamiento sin relación no garantizan la conversión de la armadura.

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)

Con la conversión activada y Geyser-Spigot en el mismo backend independiente, RSPM registra un suscriptor a SessionLoadResourcePacksEvent. Ofrece desde disco el último paquete de Bedrock autorizado a cada jugador que se conecta. Las ediciones de textura o geometría pueden llegar a la siguiente conexión sin reiniciar el servidor si los mappings registrados no cambian. Los backends en modo de red dejan la distribución al proxy, aunque también tengan Geyser-Spigot instalado localmente.

Los mappings de ítems personalizados de Geyser, el JSON de custom_mappings/, se fijan al arrancar. Añadir o eliminar ítems, cambiar una referencia de modelo o modificar predicados puede exigir nuevos mappings y, por tanto, un reinicio. RSPM despliega el archivo de mappings autorizado anterior al principio del arranque si el despliegue automático está activado. Después de la primera conversión correcta, reinicia Geyser para cargar los mappings nuevos y vuelve a conectar el cliente Bedrock.

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 no hay mappings de ítems convertibles ni archivos permitidos de entidades, RSPM retira la publicación e intenta borrar las salidas locales anteriores y su mapping desplegado en Geyser. Un archivo que quede bloqueado no sigue autorizado para su distribución. La ruta /bedrock.zip del backend devuelve 404 para indicar que ese backend no aporta contenido de Bedrock. Los paquetes de solo entidades sí se publican. Sustituir únicamente texturas de bloques Java o texturas vanilla no produce un paquete convertido; hace falta un paquete Bedrock creado por separado.

Desactivar bedrockAutoDeployToGeyser elimina el mapping que RSPM había desplegado durante la reconciliación. Cambiar bedrockGeyserFolder también limpia el destino anterior del que RSPM era responsable. Ninguna acción modifica los mappings ya cargados en Geyser; reinícialo para aplicar el nuevo conjunto.

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)

Poses de ítems en mano

Cada attachable 3D recibe animaciones de primera persona, tercera persona y cabeza. Las poses en mano proceden de las transformaciones display.firstperson_righthand y display.thirdperson_righthand del modelo Java. RSPM traslada cada transformación a través del rig vanilla del jugador de Bedrock, de modo que el modelo en mano queda donde lo dibuja Java, con la misma posición, orientación y escala por eje. Una ranura que el modelo no define usa la transformación identidad de Java. La animación de cabeza procede de display.head.

No hay nada que ajustar. Para cambiar cómo queda un ítem en la mano, cambia las transformaciones display del modelo Java; Java y Bedrock siguen entonces los mismos valores. El rig usa el brazo ancho (Steve), así que con skins de brazos finos Bedrock puede diferir de Java en medio píxel.

Las versiones anteriores añadían desplazamientos ajustados a mano desde plugins/ResourcePackManager/bedrock_display_offsets.yml. Ese archivo y sus opciones firstPerson* y thirdPerson* ya no se leen, y RSPM regenera los paquetes de Bedrock en caché tras la actualización. Puedes borrar una copia antigua del archivo.

Partículas de ítems en mano

Un plugin productor puede añadir partículas a un ítem 3D en mano con un archivo auxiliar en assets/<namespace>/rspm_item_particles/<model path>.json, donde <model path> es la ruta del modelo Java en mano (display/wand para freeminecraftmodels:display/wand). El archivo auxiliar asigna nombres de efecto a identificadores de partículas que el plugin incluye en su paquete de entidades, enumera locators en píxeles del modelo Java y contiene una timeline de partículas en bucle. RSPM añade los locators a la geometría del ítem y reproduce la timeline como una animación adicional del attachable, así que los clientes de Bedrock dibujan las partículas en la mano en primera y tercera persona. FreeMinecraftModels escribe estos archivos auxiliares para los ítems con efectos de partículas. Un archivo auxiliar ilegible se omite con una advertencia.

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.
• Un JSON de definición de ítem que no se pueda analizar aborta la conversión con Bedrock conversion failed: .... En cambio, un JSON válido sin modelo o con un nodo no compatible puede omitirse con un mensaje de depuración. Revisa el error y el recuento de mappings resultante; no toda definición omitida es un error fatal de análisis.
• 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 admite cancelación cooperativa. RSPM prepara el ZIP y los mappings y sustituye la publicación como un conjunto. Si falla o se cancela durante la sustitución, intenta restaurar el conjunto anterior; un fallo de conversión previo a la sustitución retira la salida antigua. Los hashes publicados y los metadatos del conjunto permiten rechazar generaciones obsoletas o mezcladas. La existencia de un ZIP en disco no demuestra que esté autorizado ni que un cliente Bedrock lo haya renderizado.
• Cuando el paquete fusionado no contiene mappings convertibles ni archivos permitidos de entidades, RSPM retira la publicación anterior e intenta borrar sus salidas. Un paquete de solo entidades se publica aunque tenga 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.