Geyser 扩展与基岩版自定义实体
转换资源包可以让基岩版玩家获得正确的物品贴图与模型。但要让他们看到真正的自定义实体——一个能够正常渲染并播放动画的建模 Boss，而不是显示为一个盔甲架——就需要有代码运行在 Geyser 内部。这正是 RSPM Geyser 扩展所做的事情。
你不需要单独下载它。你作为插件安装的那个 ResourcePackManager.jar 本身就是这个扩展。
一个 Jar，三种角色
ResourcePackManager.jar 同时是：
- Bukkit/Paper 后端插件，
- Velocity 与 BungeeCord/Waterfall 代理插件，
- 以及一个 Geyser 扩展。
由哪个加载器打开它，它就会选用与之匹配的入口点。较早的版本曾单独发布过 ResourcePackManager-GeyserBridge.jar；该文件已废弃，RSPM 会自动清理残留。
它是如何安装的
在 RSPM 力所能及的情况下，它会替你安装这个扩展。具体行为取决于 Geyser 所在的位置：
| 你的架构 | RSPM 的行为 |
|---|---|
| Geyser-Spigot 与服务器在同一台机器上 | 将正在运行的 jar 复制到 plugins/Geyser-Spigot/extensions/ResourcePackManager.jar。如果那里已经存在一个不同版本，则改为通过 Geyser 自身的更新队列 extensions/update/ 暂存新版本。无论哪种情况，你都会看到一行提示你重启一次的控制台信息。 |
| Geyser 位于代理端（Geyser-Velocity / Geyser-BungeeCord） | 代理角色会执行相同的操作，目标是代理的 Geyser-*/extensions/ 文件夹。 |
| Floodgate 在本地，Geyser 在外部（Geyser 运行在独立进程中） | RSPM 无法访问该进程。它会将一份副本导出到 plugins/ResourcePackManager/geyser-extension/，并提醒你把这个 jar 复制到外部 Geyser 的 extensions/ 文件夹中，然后重启 Geyser。 |
| Geyser 与 Floodgate 都不存在 | 无事可做 —— RSPM 记录一行提示信息并跳过安装。 |
extensions/ 中已存在的较新版本，绝不会被较旧版本覆盖。
安装总是需要重启一次。 Geyser 只在启动时加载扩展，因此刚刚复制或暂存的 jar 在服务器或代理重启之前不会生效。
关闭自动安装
每个角色都有自己的开关，彼此独立：
| 位置 | 设置项 | 默认值 |
|---|---|---|
后端 plugins/ResourcePackManager/config.yml | geyserExtensionAutoInstall | true |
代理 config.yml | geyser-extension-auto-install | true |
把其中任意一个设为 false，都会让对应角色停止安装该扩展或为其暂存更新，并记录一行说明。请仔细理解其语义：
- 它阻止后续的安装与更新暂存。
- 它不会移除已经位于
extensions/中的扩展 jar。Geyser 正打开着那个文件。要真正禁用桥接，请把该开关设为false，停止 Geyser，手动从extensions/中删除 RSPM 的 jar，然后再启动它。 - 关闭它不会影响资源包转换或资源包分发。物品、贴图和模型照常转换并照常分发；只有基岩版自定义实体会停止工作。
在后端关闭它，同时也会跳过把下载到的 RSPM 更新暂存进本地 Geyser-Spigot 更新队列的步骤，因此扩展与插件的版本可能逐渐脱节——这正是下文兼容性防护要捕捉的状态。
这个扩展实际做了什么
- 在启动时向 Geyser 注册 RSPM 的基岩版自定义实体定义，实体标识符从生成的基岩版资源包中读取。
- 替换生成实体的基岩版定义，使建模实体以其自定义基岩版实体的形式生成，而不是使用原版兜底方案。
- 在实体存在期间实时应用实体数据与属性覆盖。
- 提前预置 Geyser 的配方网络 ID，从而避免 Geyser 2.11 上的一类配方 ID 冲突问题。
这些定义所引用的基岩版侧资源，来自 基岩版转换 中介绍的实体资源包 —— 插件在 assets/<namespace>/rspm_bedrock_pack/ 下附带原生的基岩版实体文件，RSPM 会将它们带入生成的资源包中。
Geyser 版本要求
该扩展面向 Geyser 2.11+。
它的描述符刻意声明了一个更低的 Geyser API 级别（2.9.0），这样较旧的 Geyser 会乐意加载它，而不是直接拒绝这个 jar。真正的版本要求是在运行时强制执行的：扩展会探测自己所需的类，在这些类缺失时自我禁用，从而给出一条清晰的信息，而不是抛出一个服主根本无法解读的加载期拒绝。
它经过刻意设计，会在类/链接不兼容时以“关闭”状态失败，而不会连带拖垮 Geyser。扩展外壳只引用长期稳定的 Geyser API 类型；对版本敏感的类会在核心启动之前被探测。如果你的 Geyser 构建没有附带桥接所需的某个类，桥接会自行禁用并给出说明：
Disabled the RSPM custom Bedrock entity bridge: this Geyser build does not ship
<class>. Geyser itself is unaffected, but custom Bedrock entities will not appear until a ResourcePackManager update matches this Geyser version.
在这种状态下，物品、贴图和模型仍会正常转换并正常分发 —— 只有自定义实体会受影响。解决办法是更新 Geyser，或者等待与你的 Geyser 构建相匹配的 RSPM 版本。
早期的 RSPM 版本是通过把 Geyser 某个内部数据包转换器的内置副本替换进 Geyser 的注册表来实现同样效果的。那种转换器替换已经取消：扩展现在使用 Geyser 2.11 的公开实体生命周期/事件来完成注册与生成定义的替换。核心仍会探测一小部分 Geyser 内部实现，用于构造定义实例并接收来自下游插件的消息，这也是兼容性防护以及 RSPM 与 Geyser 版本精确匹配依然重要的原因。
加载顺序：为什么有时需要重启
Geyser 会在自身启动窗口期内注册实体定义。如果 RSPM 在该窗口关闭之后才完成基岩版资源包的生成 —— 全新安装时正是如此，因为启动时还根本不存在资源包 —— 那么这些定义就来得太晚，无法进入 Geyser 已经冻结的注册表。RSPM 会把它们保留到下次启动，并向你发出警告：
RSPM custom Bedrock entity definitions became available after Geyser closed its startup registration windows ... restart the proxy once to activate the newly generated custom models.
请在首次成功生成资源包之后，把承载 Geyser 的那个服务器或代理进程重启一次。仅仅重新连接是无法激活错过启动窗口的定义的。后续每次启动的顺序都是正确的，因为 Geyser 打开注册窗口时资源包已经存在了。
验证它是否生效
- 检查目标
extensions/文件夹中确实存在ResourcePackManager.jar。 - 启动时，Geyser 应当把该扩展列为已加载，同时 RSPM 会记录它注册了多少个基岩版自定义实体定义。
- 用基岩版加入游戏并观察一个建模实体。如果看到的是盔甲架而不是模型，那么原因要么是扩展未加载，要么是资源包没有送达客户端，要么是定义来得太晚 —— 请按这个顺序检查上文提到的各项警告。
疑难解答
“扩展已加载，但实体仍然是盔甲架。” 资源包和扩展是彼此独立的两半。请先确认基岩版资源包本身已经送达客户端（参见 基岩版转换）；没有资源包中的实体资源，这些定义就没有任何东西可以渲染。
“原本是好的，我更新了 Geyser 之后实体就坏了。” 请查找上文提到的自行禁用信息。Geyser 更新可能会挪动桥接所探测的 API 接口。
“extensions/ 里从来就没被装进任何东西。” 请在控制台中查找 Automatic Geyser extension installation is disabled by geyserExtensionAutoInstall（后端）或 ... by geyser-extension-auto-install（代理）。是有人关掉了这个开关。如果本地既没有 Geyser 也没有 Floodgate，你看到的会是 Geyser-Spigot and Floodgate were not detected locally; skipping automatic Geyser extension installation —— 那是 RSPM 正确地判断出没有可安装的目标。
“我更新了 RSPM，但扩展仍是旧版本。” 扩展只在重启时被替换；如果 RSPM 是通过 Geyser 的更新队列暂存它的，则需要重启一次才能完成替换。请让插件 jar 与扩展 jar 保持同一版本 —— 它们本来就是同一个文件，所以重新复制一次插件就够了。
在 Velocity 上，Geyser 的自动扩展订阅机制不像在其他平台那样触发，因此代理插件会自行转发这些生命周期事件。此过程由内部处理，无需任何配置。
下一步
- Bedrock / Geyser 转换 —— 哪些内容会被转换，以及资源包是如何分发的
- 代理网络 —— 部署在代理端的 Geyser
- 疑难解答