跳到主要内容

进阶功能：行为包与资源包

当前是模板，还未开工

本章目标​

  • 制作行为包和资源包，并验证包结构与内容。
  • 通过布吉岛版 Geyser 向客户端下发行为包与资源包。
  • 配置可选资源包，验证玩家选择、加载与更新流程。

前置准备​

  • 已完成项目部署，确认玩家能够正常进入服务器。
  • 准备独立的测试环境，避免错误的包文件影响正式服玩家登录。
项目本章使用的版本或工具
中国版基岩客户端（待补充：客户端与开发包版本）
Geyser（待补充：分支、提交或构建版本）
包制作工具（待补充：编辑器、打包工具）
示例文件（待补充：示例包或源码下载地址）

一、行为包与资源包的区别​

类型本章用途示例
行为包行为包在当前架构中仅用来操作客户端，本文仅讲基于modsdk开发和打包隐藏语音输入按钮
资源包材质包用来开发界面,替换贴图、文本等自定义UI

支持范围与执行位置​

（待补充：哪些内容由客户端执行，哪些需要 Paper 插件或其他服务端逻辑配合；说明中国版与国际版包格式、接口的区别。）

注意： 包文件下发成功，不代表其中所有功能都能在 Paper + Geyser 架构中生效。本节需要明确行为包的支持范围，避免读者误以为可以直接运行原生基岩服务端的全部行为逻辑。

两类包如何配合​

（待补充：选择一个贯穿本章的最小示例，说明行为包、资源包与服务端插件分别负责什么，以及它们之间的依赖关系。）

二、制作行为包​

1. 创建项目与目录结构​

（待补充：创建步骤、实际目录树、每个文件的作用及截图。）

2. 编写包清单​

（待补充：实际使用的 manifest.json 示例，解释包标识、版本号、模块声明、依赖与最低客户端版本要求。）

3. 实现示例功能​

（待补充：最小可运行示例、文件路径、完整代码，以及需要配合安装的服务端插件。）

4. 打包与本地验证​

（待补充：打包工具或命令、压缩包根目录要求、文件扩展名，以及导入或测试的方法。）

检查项预期结果
包清单与目录结构（待补充）
客户端识别（待补充：日志或界面）
示例功能（待补充：具体操作与可见效果）

三、制作资源包​

1. 创建项目与目录结构​

（待补充：实际目录树、清单文件、材质或其他资源文件的路径。）

2. 编写包清单与依赖​

（待补充：实际使用的 manifest.json 示例，说明如何与行为包关联；若不需要关联，也应说明。）

3. 添加示例资源​

（待补充：与行为包示例配套的材质、模型、声音或界面，说明命名与引用方式。）

4. 打包与本地验证​

（待补充：打包步骤、文件扩展名、客户端加载方法，以及显示效果截图。）

提示： 示例图片、音频、字体等素材应使用自制或已获授权的内容，并保留必要的来源及许可说明。

四、下发行为包与资源包​

1. 准备包文件​

文件用途下发方式服务器放置位置
行为包（待补充）（待补充）（待补充）
资源包（待补充）（待补充）（待补充）

（待补充：明确文件放在 Velocity、Geyser 配置目录还是其他位置；如使用下载地址，说明托管与访问要求。）

2. 配置下发​

（待补充：布吉岛版 Geyser 的实际配置文件路径、完整配置片段，以及各字段的含义。不沿用未核对的其他分支配置。）

3. 加载或重启​

（待补充：修改后需要重启哪个进程，是否支持重新加载，以及客户端是否需要重新进入服务器。）

4. 验证下发与生效​

测试场景操作预期结果
首次进入服务器（待补充）出现预期的下载或加载流程
行为包功能（待补充）（待补充：功能表现）
资源包表现（待补充）（待补充：材质、模型等效果）
已缓存的客户端再次进入（待补充）（待补充：缓存复用行为）
下载失败（待补充）（待补充：客户端提示与服务端日志）

五、使用可选资源包​

1. 功能介绍与适用场景​

（待补充：哪些资源允许玩家自行选择，哪些属于必需资源；说明该功能与强制资源包、普通资源包下发的区别。）

2. 准备可选资源​

（待补充：包之间的独立性、依赖关系、互斥关系与覆盖顺序；未选择可选包时应保留可用的默认表现。）

3. 配置可选资源包​

（待补充：配置文件路径、可直接使用的示例、包标识与文件的对应关系、默认选择状态。）

4. 玩家选择与切换流程​

（待补充：玩家在哪里选择、何时下载、是否需要重新登录、选择是否保存，以及相关界面截图。）

5. 验证选择结果​

测试场景预期结果
不选择可选包（待补充：基础功能与默认表现）
选择单个可选包（待补充：下载与显示效果）
同时选择多个可选包（待补充：允许的组合与覆盖规则）
取消选择后重新进入（待补充：资源是否卸载、选择是否保存）
可选包更新或移除（待补充：旧选择、缓存与下载的处理）

六、更新与回滚​

更新包内容​

（待补充：版本号与包标识的维护规则、关联包的版本同步，以及客户端缓存刷新方式。）

发布与回滚步骤​

  1. 备份现有包文件和对应配置，记录版本关系。
  2. 在测试环境验证新包与现有服务端、客户端的兼容性。
  3. （待补充：正式发布、加载或重启步骤。）
  4. （待补充：失败时恢复包、配置及客户端缓存的具体操作。）

七、常见问题​

1. 客户端没有收到包下载提示​

（待补充：配置路径、文件识别、缓存、日志与排查顺序。）

2. 包下载完成，但行为或资源没有生效​

（待补充：支持范围、目录结构、清单依赖、内容引用与服务端配合的排查方法。）

3. 更新后仍显示旧资源​

（待补充：包版本、客户端缓存与资源覆盖顺序的检查方法。）

4. 可选资源包的选择没有生效​

（待补充：选择保存、重新登录、包依赖与互斥关系的排查方法。）