Geyser 扩展与基岩版自定义实体

资源包转换提供受支持的物品贴图和模型。自定义实体，例如具有独特外观和动画的模型 Boss，还需要 Geyser 内部的代码。RSPM Geyser 扩展为兼容的内容生产插件及其基岩版实体资源提供这种集成。

你不需要单独下载它。你作为插件安装的那个 ResourcePackManager.jar 本身就是这个扩展。

一个 Jar，三种角色

ResourcePackManager.jar 同时是：

• Bukkit/Paper 后端插件，
• Velocity 与 BungeeCord 代理插件，
• 以及一个 Geyser 扩展。

每个加载器使用对应入口。旧版本曾单独提供 ResourcePackManager-GeyserBridge.jar，现在已经停用。安装器发现这个文件时，会将通用 jar 放入 Geyser 更新队列，等待重启时替换。

它是如何安装的

在 RSPM 力所能及的情况下，它会替你安装这个扩展。具体行为取决于 Geyser 所在的位置：

你的架构	RSPM 的行为
Geyser-Spigot 在同一个服务器中	首次安装时，将运行中的 jar 复制到 plugins/Geyser-Spigot/extensions/ResourcePackManager.jar。若现有 jar 的字节不同，会在降级保护允许的情况下将替换文件暂存到 extensions/update/。新安装或已暂存的替换会提示重启；相同的当前 jar 不需要复制。
Geyser 位于代理端（Geyser-Velocity / Geyser-BungeeCord）	代理角色会执行相同的操作，目标是代理的 Geyser-*/extensions/ 文件夹。
Floodgate 在本地，Geyser 在外部（Geyser 运行在独立进程中）	在 plugins/ResourcePackManager/geyser-extension/ 下导出副本。请使用控制台中的确切路径；存在旧导出时，路径可能指向 update/ 子目录。将该 jar 复制到外部 Geyser 的 extensions/ 并重启 Geyser。仅导出扩展并不会配置外部资源包分发或启动定义加载。
Geyser 与 Floodgate 都不存在	无事可做 —— RSPM 记录一行提示信息并跳过安装。

安装器会保留在已安装通用 jar、旧桥接 jar 或暂存更新中找到的较新有效版本。它同时比较版本和校验和，因此相同版本但字节不同的文件仍可能需要替换。

安装总是需要重启一次。 Geyser 只在启动时加载扩展，因此刚刚复制或暂存的 jar 在服务器或代理重启之前不会生效。

关闭自动安装

每个角色都有自己的开关，彼此独立：

位置	设置项	默认值
后端 plugins/ResourcePackManager/config.yml	geyserExtensionAutoInstall	true
代理 config.yml	geyser-extension-auto-install	true

把其中任意一个设为 false，都会让对应角色停止安装该扩展或为其暂存更新，并记录一行说明。请仔细理解其语义：

• 它阻止后续的安装与更新暂存。
• 不会移除已安装的 jar，也不会取消已经暂存的更新。要禁用桥接，请将相关开关设为 false 并完全停止 Geyser。从 extensions/ 和 extensions/update/ 中删除 ResourcePackManager.jar，以及这些目录中残留的旧 ResourcePackManager-GeyserBridge.jar，然后启动 Geyser。队列中留下的副本可能在启动时恢复扩展。只删除这些 RSPM 文件。
• 关闭设置不会影响资源包转换、分发或已安装的扩展。移除扩展才会禁用自定义基岩版实体集成；物品转换和资源包分发相互独立。

在后端关闭设置，也会跳过将已下载的 RSPM 更新暂存到本地 Geyser-Spigot 更新队列。扩展和插件因此可能不同步。请手动保持文件一致；下文的兼容性检查针对必需的 Geyser 类和二进制兼容性，并不检查插件与扩展的版本是否相同。

这个扩展实际做了什么

• 在启动时向 Geyser 注册 RSPM 的基岩版自定义实体定义，实体标识符从生成的基岩版资源包中读取。每个实体的属性从其客户端实体文件所引用的动画控制器和渲染控制器中收集，并按控制器标识符匹配，因此即使资源集合中较长的文件路径被缩短，其属性和动画仍能正常注册。
• 替换生成实体的基岩版定义，使建模实体以其自定义基岩版实体的形式生成，而不是使用原版兜底方案。
• 在实体存在期间实时应用实体数据与属性覆盖。
• 提前预置 Geyser 的配方网络 ID，从而避免 Geyser 2.11 上的一类配方 ID 冲突问题。

资源来自基岩版转换中介绍的实体资源集合。插件在 assets/<namespace>/rspm_bedrock_pack/ 下提供原生基岩版实体文件，RSPM 将它们导入生成的资源包。内容生产插件还必须通过桥接标记对应的 Java 实体；资源集合本身不会将任意实体变成自定义模型。

启动时，扩展从 RSPM 本地生成包的 entity/*.entity.json 条目中读取标识符。它依次检查常规代理输出 plugins/resourcepackmanager/work/merged/Bedrock.zip、plugins/ResourcePackManager/work/merged/Bedrock.zip，然后检查后端输出 plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip，路径相对于 Geyser 工作目录。外部 Geyser 进程无法自动读取另一台机器的输出。请在日志中确认预加载了哪个包，不要认为复制扩展也会自动提供定义。

Geyser 版本要求

该扩展面向 Geyser 2.11+。

描述符声明 Geyser API 级别 2.9.0。这个较低级别不能证明与旧 Geyser 兼容。运行时，扩展检查必需的类，缺失时禁用桥接。

它经过刻意设计，会在类/链接不兼容时以“关闭”状态失败，而不会连带拖垮 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 API 和成功的资源包分发。请使用兼容的 RSPM/Geyser 组合来恢复自定义实体。

早期的 RSPM 版本是通过把 Geyser 某个内部数据包转换器的内置副本替换进 Geyser 的注册表来实现同样效果的。那种转换器替换已经取消：扩展现在使用 Geyser 2.11 的公开实体生命周期/事件来完成注册与生成定义的替换。核心仍会探测一小部分 Geyser 内部实现，用于构造定义实例并接收来自下游插件的消息，这也是兼容性防护以及 RSPM 与 Geyser 版本精确匹配依然重要的原因。

加载顺序：为什么有时需要重启

Geyser 在启动注册窗口内注册实体定义。如果 RSPM 在窗口关闭后才生成首个基岩版包，定义就无法进入运行中的注册表。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 的服务器或代理进程。仅重新连接不能激活错过启动窗口的定义。下次启动时，生成包必须位于扩展读取的本地路径，且两个定义注册窗口都必须被接收。启动状态行会说明是否满足这些条件。

验证它是否生效

1. 检查目标 extensions/ 文件夹中确实存在 ResourcePackManager.jar。
2. 启动时，检查 RSPM Geyser bridge health 行。它包含扩展版本、artifactSha256、activationRoute、loadedDefinitions、packUuid 和 definitionWindows。对含自定义实体的包，应有已注册定义、预期的包 UUID 和 definitionWindows=observed。MISSED 或 RSPM GEYSER BRIDGE UNHEALTHY 表示错过启动注册窗口；显示扩展已加载并不足够。
3. 使用基岩版加入，检查模型实体的外观和动画。如果仍是盔甲架等原版载体，请检查桥接激活、客户端资源包分发、已注册定义和内容生产插件的集成。启动日志正常本身不能证明客户端已渲染实体。

疑难解答

“扩展已加载，但实体仍然是盔甲架。” 资源包和扩展是彼此独立的两半。请先确认基岩版资源包本身已经送达客户端（参见 基岩版转换）；没有资源包中的实体资源，这些定义就没有任何东西可以渲染。

“原本是好的，我更新了 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 上，代理插件也会转发生命周期和会话事件，以覆盖自动订阅被错过的启动路径。无需配置。请使用启动状态行以及注册或转发警告诊断激活失败。

下一步

• Bedrock / Geyser 转换 —— 哪些内容会被转换，以及资源包是如何分发的
• 代理网络 —— 部署在代理端的 Geyser
• 疑难解答