ChaAssets 资源加密 ​

ChaAssets 把必须分发到玩家客户端的图片、动图、字体、音效、模型和粒子资源构建为经过平台认证的 .chaassets 文件。ChaUI 与 ChaEngineMod 都通过同一资源底座读取，原有相对路径不需要因为加密而改变。

本教程从项目创建开始，依次完成 ZIP 准备、上传构建、版本下载、服务器身份和服务器授权，并说明未连接服务器时应如何选择安全域。

适用资源 ​

ChaAssets 适合保护：

• ChaUI 的页面图片、动图、字体与音效；
• ChaEngineMod 的模型、动画、贴图与基岩版粒子资源；
• 以后接入 ChaAssets 虚拟资源根的其他客户端模块。

例如 ChaUI 中的 gui/logo.png 仍填写 gui/logo.png；ChaEngine 配置中的 guardian/guardian.geo.json 仍相对于 model/ 填写。ChaAssets 只改变资源的保存和授权方式，不改变业务配置路径。

使用前准备 ​

1. 可以登录猹件用户中心。
2. 需要读取加密资源的客户端已安装 ChaAssetsMod。
3. 使用 SESSION 时，服务端已安装并正常启用 ChaAssets。
4. 原始资源能在未加密状态下被对应模块正常读取。
5. 已备份原始资源工程；平台输入是 ZIP，输出是新的 .chaassets，无需覆盖原文件。

创建资源项目 ​

进入用户中心的 ChaAssets 页面并创建项目。项目、版本、服务器身份和授权默认只对项目所有者可见。

需要在标题主菜单等进服前场景读取的本地资源使用 BOOTSTRAP。只应在玩家连接指定服务器并获得授权后读取的资源使用 SESSION。

项目生成版本后不要随意改变资源根。资源根参与最终寻址，改变后原有相对路径会落入另一个命名空间。

准备 ZIP ​

平台接受“直接资源结构”和“保留项目根目录”两种形式，但同一 ZIP 中只能选择一种。

直接资源结构 ​

ChaEngine 项目可直接以 model、particles、textures 等目录为 ZIP 根：

model/...
model/guardian/guardian.geo.json
model/guardian/guardian.animation.json
model/guardian/guardian.png
particles/chaengine.index.json

ChaUI 项目可直接以实际资源目录为 ZIP 根：

gui/...
gui/main-menu/background.png
sounds/click.ogg

保留项目根目录 ​

也可以直接压缩完整资源根：

ChaEngine/model/guardian/guardian.geo.json
ChaEngine/model/guardian/guardian.png

或：

ChaUI/model/...
ChaUI/gui/main-menu/background.png
ChaUI/sounds/click.ogg

平台构建时会移除最外层项目根。因此 ChaEngine/model/guardian/guardian.png 与直接结构中的 model/guardian/guardian.png 最终是同一个资源路径。

禁止混用 ​

以下 ZIP 同时包含带根和不带根的路径，平台会拒绝：

ChaEngine/model/a.png
model/b.png

同时避免绝对路径、盘符、反斜杠、.、..、重复文件名、损坏 ZIP，以及数量或体积异常的文件。

上传与构建 ​

1. 打开项目详情中的“上传与构建”。
2. 选择准备好的 ZIP。
3. 点击“上传并构建”；大文件会分片上传并显示进度。
4. 等待平台检查目录、加密资源并完成认证。
5. 最近构建变为 SUCCEEDED 后，进入“版本与下载”。

网络中断时，页面会保留可恢复的上传编号。重新进入项目并选择同一个 ZIP，可以从未完成分片继续。网页不会把原始内容或资源密钥保存在浏览器本地。

构建失败时先读取最近构建的明确原因。目录混用、危险路径、文件过大、压缩率异常和 ZIP 损坏会分别提示。

版本与下载 ​

每次成功构建都会产生一个不可变版本。进入“版本与下载”，核对版本号、安全域、文件大小与清单摘要，然后下载。

扩展名必须保留为 .chaassets，文件名可以按用途整理：

ui.chaassets
models.chaassets
models-2026-08.chaassets

不要用内容不同的同名文件覆盖已投入使用的版本。更新素材时重新构建新版本，再将新文件分发给客户端。

客户端放置位置 ​

.chaassets 固定放在当前游戏目录的 resourcepacks/<资源根>/，与该消费者的普通资源位于同一根目录：

.minecraft/
└─ resourcepacks/
   ├─ ChaUI/
   │  ├─ ui.chaassets
   │  └─ gui/
   │     └─ temporary-preview.png
   └─ ChaEngine/
      ├─ models.chaassets
      └─ model/
         └─ local-test/

常用完整路径：

.minecraft/resourcepacks/ChaUI/ui.chaassets
.minecraft/resourcepacks/ChaEngine/models.chaassets

不要放进 Minecraft 原版资源包的 assets/<namespace>/，也不要把容器文件名写入页面或模型路径。

服务器身份 ​

SESSION 资源需要确认玩家连接的是已授权服务器。新版流程不要求手工准备身份字段或上传密钥，只需用网页生成的一次性命令配对。

下面以一个 ChaEngine 模型项目为例：

项目名称：修仙主题模型资源
资源根：ChaEngine
安全域：SESSION
资源版本：版本 1
服务器身份：修仙主题服务器

用一次性命令配对 ​

1. 确认服务端 ChaAssets 至少正常启动过一次。
2. 在用户中心进入“服务器身份”，点击“添加服务器”。
3. 填写 修仙主题服务器，生成配对命令。
4. 在目标服务器控制台执行网页显示的完整命令。
5. 保持弹窗打开，等待网页显示配对成功和身份可用。

下面只是排版示例，示例码不能使用：

/chaassets pair J7K9-P2MX

配对码有效期较短且只能成功使用一次。过期或输错时关闭弹窗，再生成新命令。配对只产生一次明确的服务器到平台 HTTPS 请求，不开启后台常驻连接。

多台子服共享身份 ​

完全受信任且属于同一管理边界的子服可以共享完整 plugins/ChaAssets/keys/：

1. 在子服 A 完成配对。
2. 完全停止 A、B 两台服务器。
3. 把 A 的整个 plugins/ChaAssets/keys/ 复制到 B，不要只复制单个文件。
4. 分别启动每个节点；每个节点仍独立执行启动检查。

共享 keys 的节点代表同一服务器身份，共享资源授权和撤销结果。撤销该身份会在各节点后续启动检查中一起生效。所有 keys 副本丢失时，应创建新身份，不尝试恢复或轮换旧密钥。

服务器授权 ​

配对后，在项目页面保存资源版本与服务器的启用关系：

1. 打开项目的“服务器授权”。
2. 点击“启用资源”。
3. 选择 版本 1 · SESSION。
4. 选择 修仙主题服务器。
5. 保存并启用。
6. 确认页面显示：

配置已保存，将在服务器下次启动检查时生效。

不需要重新构建或重新下载 .chaassets。正常重启服务器后，ChaAssets 只在启动阶段取得当前启用配置。共享 keys 的集群需分别重启每个节点；未重启节点继续使用本次运行已加载的快照。

停止授权、撤销或删除服务器身份同样在节点下一次成功启动检查时应用。平台不会中断正在运行的服务器或玩家会话。

平台连接时机 ​

没有运行期心跳、定时授权轮询、WebSocket、SSE 或长轮询。玩家登录和每次读取资源都不会请求平台；会话授权通过现有 Minecraft 网络通道完成。六个客户端版本使用同一个通用 ChaAssets 服务端 Jar，服务器进程 Java 仍由 Bukkit/Paper 核心要求决定。

每个插件启动阶段只进行一次平台授权检查；启动完成后使用固定快照，不再轮询。

启动时暂时无法访问平台，会尝试读取上一次经过平台验证并保存在本地的授权快照。快照仍完整可信时，服务器可继续使用它，本次运行也不会受之后网络波动影响。

全新身份从未取得启动快照且首次检查失败时，服务器仍能启动，但本次运行不开放加密资源。网络恢复后正常重启即可，无需重新配对或修改资源包。

普通文件与加密包共存 ​

• 加密资源与普通文件可以分别提供不同相对路径。
• 同一路径同时存在时，通过认证并获授权的加密资源优先。
• 加密包声明路径但授权拒绝或包损坏时必须失败关闭，不回退同名普通文件。
• 只有路径未被加密包声明，或 ChaAssetsMod 不可用时，消费者才回退普通文件。
• 解密内容只保留在内存中，不写回明文文件。

资源更新、授权撤销或资源代次变化时，消费者必须清理解码模型、动画、纹理与页面素材缓存；较早发起的异步加载结果不得重新激活。

BOOTSTRAP 与 SESSION ​

BOOTSTRAP 用于尚未连接服务器时必须读取的本地资源，例如启动后立即出现的主菜单素材。客户端取得这类包后，可以在本地启动阶段读取。

SESSION 用于特定服务器会话内的页面、模型与素材。玩家必须连接目标服务器并取得有效授权后才能读取。对服务器专属或付费资源，应优先使用 SESSION。

如果一个功能在未授权时仍必须可用，应提供不含受保护素材的安全降级，不要用同路径明文绕过失败关闭规则。

常见错误 ​

构建提示混用目录结构 ​

决定使用直接结构还是保留项目根结构，并把 ZIP 内所有文件统一。不要同时保留 ChaEngine/model/... 与 model/...。

构建提示路径不安全 ​

检查绝对路径、盘符、反斜杠、.、..、控制字符和空目录段。所有资源路径统一使用 /。

构建提示体积或压缩率异常 ​

删除备份、重复素材和临时文件，确认没有把整个游戏目录压入 ZIP；异常文件重新从原始资源导出。

ZIP 损坏 ​

先在本地完整测试解压。失败时从原始资源目录重新创建普通 ZIP，不要上传分卷包或只改扩展名的其他格式。

NeoForge 启动时提示并行初始化失败 ​

如果启动界面或 latest.log 提示并行初始化失败，并出现 Minecraft.getInstance() ... null，说明客户端仍在使用旧版 ChaAssetsMod。请安装与当前 Minecraft 和加载器对应的 ChaAssetsMod 1.0.2 或更高版本，删除 mods/ 中重复的旧文件，然后完全退出并重新启动客户端。

加入 ChaUI 或 ChaEngineMod 后可能更容易触发这个旧版问题，但不需要删除这两个功能模组。请确认 ChaAssetsMod、ChaUI 和 ChaEngineMod 对应的 Minecraft 版本与加载器一致。

客户端找不到加密包 ​

确认文件位于实际启动实例的 resourcepacks/ChaUI/ 或 resourcepacks/ChaEngine/，资源根与项目一致，并保留 .chaassets 扩展名。

安装后仍读取普通文件 ​

确认 ChaAssetsMod 已加载、容器资源根正确。SESSION 资源还要求服务器完成配对、版本已授权，并在保存授权后至少成功启动检查一次。

未安装 ChaAssetsMod 时加密资源不显示 ​

这是预期行为。未安装 ChaAssetsMod 时忽略 .chaassets，普通文件仍可读取。若资源必须受保护，应把 ChaAssetsMod 列为客户端安装要求。

配对码过期 ​

重新生成并立即执行。示例 J7K9-P2MX 不能用于真实配对。

平台暂时不可用 ​

已成功启动过的身份先确认日志是否加载上一次验证快照。全新身份则需等待网络恢复后正常重启，直到首次启动检查成功。

集群只有部分节点应用新授权 ​

共享 keys 不代表运行期推送。网页保存后每个节点都要分别重启。

安全建议 ​

• 默认每个独立服务器使用独立身份，只在同一管理边界内共享完整 keys。
• 备份整个 plugins/ChaAssets/keys/，不要只备份单个文件。
• 正式资源每次构建新版本，保留旧版本以便平稳回退。
• 停用服务器后在网页停止授权并撤销身份，接受其在下次启动检查生效。
• 不把数据库密码、服务端令牌、账号凭据等机密放进客户端资源。
• 全部 keys 丢失时创建新服务器身份。

完成后，ChaUI 与 ChaEngineMod 都继续使用原相对路径；ChaAssets 统一负责容器验证、授权与内存解密。