Extensión de Geyser y entidades personalizadas de Bedrock

La conversión del paquete proporciona las texturas y modelos de objetos compatibles. Las entidades personalizadas, como un jefe modelado con aspecto y animaciones propios, también necesitan código dentro de Geyser. La extensión de Geyser de RSPM aporta esa integración a los plugins productores compatibles y sus recursos de entidades Bedrock.

No la descargas por separado. El mismo ResourcePackManager.jar que instalas como plugin es la extensión.

Un jar, tres funciones

ResourcePackManager.jar es simultáneamente:

• el plugin de backend de Bukkit/Paper,
• el plugin de proxy de Velocity y BungeeCord,
• y una extensión de Geyser.

Cada cargador usa su punto de entrada correspondiente. Las versiones antiguas incluían un ResourcePackManager-GeyserBridge.jar separado. Ese archivo está retirado. Si el instalador lo encuentra, prepara el jar universal en la cola de actualización de Geyser para sustituirlo al reiniciar.

Cómo se instala

RSPM instala la extensión por ti en los casos en los que puede. Lo que ocurre depende de dónde viva Geyser:

Tu configuración	Qué hace RSPM
Geyser-Spigot en el mismo servidor	En la primera instalación, copia el jar en ejecución a plugins/Geyser-Spigot/extensions/ResourcePackManager.jar. Si el jar existente tiene bytes distintos, prepara su sustitución mediante extensions/update/, respetando la protección contra versiones anteriores. Una instalación nueva o una sustitución preparada genera una petición de reinicio; un jar actual idéntico no requiere copia.
Geyser en el proxy (Geyser-Velocity / Geyser-BungeeCord)	El rol de proxy hace lo mismo en la carpeta Geyser-*/extensions/ del proxy.
Floodgate local, Geyser externo (Geyser se ejecuta en un proceso aparte)	Exporta una copia bajo plugins/ResourcePackManager/geyser-extension/. Sigue la ruta exacta de la consola; puede apuntar a la subcarpeta update/ si existe una exportación antigua. Copia ese jar a extensions/ del Geyser externo y reinicia Geyser. Exportar la extensión por sí solo no configura la entrega externa del paquete ni la carga de definiciones al arrancar.
Ni Geyser ni Floodgate presentes	Nada que hacer — RSPM registra una línea informativa y omite la instalación.

El instalador conserva una versión válida más reciente que encuentre en el jar universal instalado, el puente antiguo o una actualización preparada. Compara sumas de comprobación además de versiones, por lo que unos bytes distintos con la misma versión también pueden requerir sustitución.

La instalación siempre requiere un reinicio. Geyser carga las extensiones al arrancar, así que un jar recién copiado o preparado no hace nada hasta que el servidor o el proxy se reinicien.

Desactivar la instalación automática

Cada rol tiene su propio interruptor, y son independientes:

Dónde	Opción	Por defecto
Backend plugins/ResourcePackManager/config.yml	geyserExtensionAutoInstall	true
Proxy config.yml	geyser-extension-auto-install	true

Poner cualquiera de los dos en false impide que ese rol instale la extensión o prepare una actualización para ella, y registra una línea diciéndolo. Lee bien la semántica:

• Impide la instalación futura y la preparación de actualizaciones.
• No elimina un jar instalado ni cancela una actualización ya preparada. Para desactivar el puente, pon las opciones correspondientes en false y detén Geyser por completo. Elimina ResourcePackManager.jar de extensions/ y de extensions/update/, junto con cualquier ResourcePackManager-GeyserBridge.jar antiguo en esas carpetas, y vuelve a iniciar Geyser. Una copia que quede en la cola puede restaurar la extensión al arrancar. Elimina solo estos archivos de RSPM.
• Desactivar esta opción no afecta a la conversión de paquetes, a su entrega ni a una extensión ya instalada. Eliminar la extensión desactiva la integración de entidades personalizadas de Bedrock; la conversión de objetos y la entrega de paquetes son funciones independientes.

Desactivarlo en el backend también impide preparar una actualización descargada de RSPM en la cola de Geyser-Spigot local. La extensión y el plugin pueden quedar en versiones distintas. Mantén sus archivos sincronizados manualmente; la protección de compatibilidad descrita abajo comprueba las clases de Geyser necesarias y la compatibilidad binaria, no la igualdad de versiones entre plugin y extensión.

Qué hace realmente la extensión

• Registra en Geyser las definiciones de entidades de Bedrock personalizadas de RSPM al arrancar, leyendo los identificadores de entidad del paquete de Bedrock generado. Las propiedades de cada entidad se recogen de los controladores de animación y de renderizado a los que hace referencia su archivo de entidad de cliente, emparejados por identificador de controlador, así que los paquetes cuyas rutas de archivo largas se acortaron siguen registrando sus propiedades y animaciones.
• Cambia la definición de Bedrock de las entidades que aparecen, de modo que una entidad modelada aparezca como su entidad de Bedrock personalizada en lugar del respaldo vanilla.
• Aplica datos de entidad y sobrescrituras de propiedades en vivo mientras la entidad existe.
• Prepara con antelación los IDs de red de recetas de Geyser, lo que evita una clase de problemas de colisión de IDs de recetas en Geyser 2.11.

Los recursos proceden de los conjuntos de entidades descritos en Conversión a Bedrock. Un plugin proporciona archivos nativos de entidades Bedrock bajo assets/<namespace>/rspm_bedrock_pack/ y RSPM los importa al paquete generado. El productor también debe marcar las entidades Java correspondientes mediante el puente; un conjunto de recursos por sí solo no convierte entidades arbitrarias en modelos personalizados.

Al arrancar, la extensión busca identificadores en las entradas entity/*.entity.json del paquete local generado por RSPM. Comprueba las rutas habituales del proxy plugins/resourcepackmanager/work/merged/Bedrock.zip y plugins/ResourcePackManager/work/merged/Bedrock.zip, y después la salida del backend plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip, relativas al directorio de trabajo de Geyser. Un proceso externo de Geyser no puede leer automáticamente la salida de otra máquina. Confirma en el registro qué paquete se precargó; copiar la extensión no proporciona por sí solo las definiciones.

Requisitos de versión de Geyser

La extensión está dirigida a Geyser 2.11+.

Su descriptor declara el nivel de API de Geyser 2.9.0. Ese nivel inferior no demuestra compatibilidad con un Geyser antiguo. En ejecución, la extensión comprueba las clases que necesita y desactiva el puente si faltan.

Está diseñada para desactivarse ante incompatibilidades de clases o enlazado sin provocar un fallo de Geyser. La capa externa de la extensión solo referencia tipos de la API de Geyser que existen desde hace mucho; las clases sensibles a la versión se comprueban antes de que arranque el núcleo. Si tu compilación de Geyser no incluye una clase que el puente necesita, el puente se desactiva a sí mismo y lo indica:

Se ha desactivado el puente de entidades personalizadas de Bedrock de RSPM: esta compilación de Geyser no incluye <class>. Geyser no se ve afectado, pero las entidades personalizadas de Bedrock no aparecerán hasta que una actualización de ResourcePackManager sea compatible con esta versión de Geyser.

Desactivar el puente no desactiva el convertidor de objetos ni el proveedor de paquetes, que son independientes. Estos siguen necesitando sus propias API de Geyser compatibles y una entrega correcta del paquete. Usa una combinación compatible de RSPM y Geyser para recuperar las entidades personalizadas.

Las versiones anteriores de RSPM conseguían el mismo resultado intercambiando una copia interna de uno de los traductores de paquetes internos de Geyser dentro del registro de Geyser. Ese reemplazo de traductor ha desaparecido: la extensión ahora usa el ciclo de vida y los eventos públicos de entidades de Geyser 2.11 para el registro y la sustitución de definiciones de aparición. El núcleo todavía comprueba un conjunto limitado de internos de Geyser que usa para construir instancias de definición y recibir mensajes de plugin descendentes, y por eso la protección de compatibilidad y la coincidencia exacta de versiones RSPM/Geyser siguen importando.

Orden: por qué a veces hace falta un reinicio

Geyser registra las definiciones de entidades durante su ventana de arranque. Si RSPM genera el primer paquete Bedrock después de que esa ventana se cierre, las definiciones llegan demasiado tarde para los registros en ejecución. RSPM pide reiniciar para poder precargar el paquete generado en el siguiente arranque:

Las definiciones de entidades personalizadas de Bedrock de RSPM estuvieron disponibles después de que Geyser cerrara sus ventanas de registro al arrancar... reinicia el proxy una vez para activar los modelos personalizados recién generados.

El aviso se emite cuando aparece un nuevo identificador de entidad o un tipo de propiedad nuevo o modificado después de que se cierre el registro. Volver a exportar las mismas definiciones y tipos de propiedades no requiere reiniciar.

Reinicia el proceso del servidor o proxy que aloja Geyser tras la primera generación correcta del paquete. Reconectarse no activa definiciones que llegaron fuera de la ventana de arranque. En el siguiente inicio, el paquete debe estar disponible en la ruta local que lee la extensión y deben recibirse ambas ventanas de registro de definiciones. La línea de estado del arranque indica si ocurrió.

Verificar que funciona

1. Comprueba que la carpeta extensions/ de destino contiene realmente ResourcePackManager.jar.
2. Al arrancar, revisa la línea RSPM Geyser bridge health. Incluye la versión de la extensión, artifactSha256, activationRoute, loadedDefinitions, packUuid y definitionWindows. Para un paquete con entidades personalizadas, espera definiciones registradas, el UUID del paquete previsto y definitionWindows=observed. MISSED o RSPM GEYSER BRIDGE UNHEALTHY indica que se perdió una ventana de registro; que la extensión figure como cargada no basta.
3. Conéctate desde Bedrock y comprueba el aspecto y la animación de una entidad modelada. Si sigue siendo una entidad vanilla, como un soporte para armaduras, revisa la activación del puente, la entrega al cliente, las definiciones registradas y la integración del productor. Un registro de arranque correcto no demuestra que el cliente haya renderizado la entidad.

Solución de problemas

"La extensión está cargada, pero las entidades siguen siendo armor stands." El paquete y la extensión son dos mitades separadas. Confirma primero que el propio paquete de Bedrock llegó al cliente (consulta Conversión a Bedrock); sin los recursos de entidad del paquete no hay nada que las definiciones puedan renderizar.

"Funcionaba, luego actualicé Geyser y las entidades se rompieron." Busca el mensaje de autodesactivación mencionado arriba. Una actualización de Geyser puede mover la superficie de API que el puente comprueba.

"Nunca se instaló nada en extensions/." Busca en la consola Automatic Geyser extension installation is disabled by geyserExtensionAutoInstall (backend) o ... by geyser-extension-auto-install (proxy). Alguien apagó el interruptor. Si Geyser y Floodgate faltan ambos localmente, verás en su lugar Geyser-Spigot and Floodgate were not detected locally; skipping automatic Geyser extension installation — eso es RSPM decidiendo correctamente que no hay nada donde instalar.

"Actualicé RSPM pero la extensión sigue siendo la versión antigua." La extensión solo se reemplaza al reiniciar, y si RSPM la preparó a través de la cola de actualización de Geyser hace falta un reinicio para que se intercambie. Mantén el jar del plugin y el jar de la extensión en la misma versión — son el mismo archivo, así que basta con volver a copiar el plugin.

La extensión instala suscripciones tempranas del ciclo de vida mediante código, además de sus manejadores anotados. En Velocity, el plugin del proxy también retransmite eventos del ciclo de vida y de sesión para cubrir arranques donde no se recibieron las suscripciones automáticas. No requiere configuración. Usa la línea de estado del arranque y los avisos del registro o la retransmisión para diagnosticar fallos de activación.

Próximos pasos

• Conversión a Bedrock / Geyser — qué se convierte y cómo se sirve el paquete
• Redes con proxy — Geyser en un proxy
• Solución de problemas