# KSOpenAopt **Repository Path**: bili_zero123/ksopen-aopt ## Basic Information - **Project Name**: KSOpenAopt - **Description**: 适用于网易我的世界 KID动作优化/剑魂 的扩展(数据包) API/解决方案 - **Primary Language**: Python - **License**: BSD-3-Clause - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 8 - **Forks**: 2 - **Created**: 2025-01-06 - **Last Updated**: 2026-09-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: Python ## README # KSOpenAopt 开放功能 > [!WARNING] > **模型标准资产使用警告** > > 本项目提供的相关模型标准资产仅供 AOPT 适配及扩展包开发使用，其中美术资产所有权保留于原作者。 > > 近期发现大量开发者未经授权，使用相关模型资产或基于其修改、衍生的内容开发独立项目，特此说明。 > > 下文关于工具及扩展项目的开放使用、修改、分发与商业化授权，**不包含相关模型标准资产在上述范围之外的使用授权**。 > [!IMPORTANT] > **当前文档已过时。** 以下内容为历史版本说明，接口、参数、构建流程及兼容性描述可能与现行版本不一致，仅供参考。实际使用时，请以所使用版本的源码、随附说明及开发者确认为准。 KSOpenAopt 提供适用于网易《我的世界》「KID 动作优化」的扩展（数据包）API 与解决方案。本文后续使用 **AOPT** 简称。 ## 1. 自动化构建 BuildTools 提供适用于 AOPT 的低代码扩展包构建解决方案。 ### 1.1 开始构建 执行 `QBlockBuilder.exe` 即可开始构建。若无异常，将在指定输出目录生成 Addon 包。 ### 1.2 构建清单：MANIFEST.json `MANIFEST.json` 是 QBlockBuilder 的构建配置清单。通用构建系统说明见 [QBlockBuilder](https://gitee.com/bili_zero123/QBlockBuilder)。 本文带注释的 JSON 示例使用 `jsonc` 代码块展示；实际文件是否允许注释，以所使用版本的构建工具为准。 ```jsonc { "package": "test_package", // 修改为您的项目名，需遵循命名规范 "jsonOptimize": true, "pyReload": true, // "debug": false, // "addon++": false, "modules": [ { "lib": "libs/KAOBuildLib", "path": "aopt", // 扩展配置与资源所在目录 "description": "[v1.0.0] KID动作优化扩展包构建支持" }, { "lib": "libs/CheckAOPT", "description": "用于生成运行时的前置环境检查(AOPT), 如果不存在则弹出提示" } ] } ``` 双 AOPT 构建可通过添加对应的两个构建库 DLL，并让它们引用同一 `aopt` 目录实现。上例仅列出 KID 构建支持与前置环境检查模块；另一 AOPT 的构建库名称及配置请以实际提供的文件为准。 ### 1.3 配置与资源路径 在构建清单的 `path` 目录（例如 `aopt`）中创建 JSON 文件，并通过 `type` 声明扩展类型。文件名可自定义，允许使用中文。 资源引用规则： - 支持相对路径，以及以 `path` 目录为起点的完整路径引用。 - 必须包含文件后缀，不支持无后缀引用。 - 不支持向上的相对路径引用（例如 `../`）。 ## 2. 自定义默认皮肤 在 `path` 目录中创建配置文件，例如 `自定义皮肤.json`，将 `type` 设为 `custom_skin`。 ```jsonc { "type": "custom_skin", "skin_name": "这是一个测试皮肤", // "skin_id": "test1", // 未指定时自动分配 "icon": "apple.png", // 皮肤头像 "texture": "apple.png" // 64×64 皮肤纹理 // ,"skin_type": "slim" // 可选；未指定时默认为粗手模型 } ``` | 参数 | 说明 | | --- | --- | | `type` | 固定为 `custom_skin`。 | | `skin_name` | 皮肤显示名称。 | | `skin_id` | 可选；未指定时自动分配。 | | `icon` | 皮肤头像纹理路径。 | | `texture` | 皮肤纹理路径，尺寸为 64×64。 | | `skin_type` | 可选；`slim` 表示细手模型，未指定时默认为粗手模型。 | ## 3. 自定义 3D 外观（自由模型） 在 `path` 目录中创建配置文件，将 `type` 设为 `custom_3d_skin`。 ```jsonc { "type": "custom_3d_skin", "skin_name": "这是一个3D的皮肤", "icon": "apple.png", "texture": "apple2.png", "geometry": "geometry.test_model", // 可选：面部表情渲染，默认禁用；仅KID动作优化生效。 "allow_face_expressions": true, // 可选：持续循环播放的默认动画，用于调整模型细节或表现 "default_animation": "animation.armor_stand.brandish_pose" } ``` 历史版本仅开放单个 `default_animation` 自定义动画参数。 动画与模型（1.12+）资源可直接放置在构建 `path` 目录中的任意位置，构建时会自动复制到 Addon 的目标位置。 ### 3.1 自定义模型标准 通用模型规范文件：`Models/global_3d_model.json`。 **面部表情** 为兼顾兼容性，无论是否使用 KID 面部表情，都应设计面部模型。若需要同时支持 KID 面部表情，可将常态面部向后移动 `0.01` 单位，以避免面部重叠闪烁。 **刀光位置** `global_3d_model` 提供的定位器用于确定刀光渲染位置，不可缺失，但允许调整位置。 ### 3.2 骨骼兼容要求 由于 KID 动作优化的历史实现问题，部分骨骼（`bones`）不可缺少，否则可能出现动画异常。 | 部位 | 要求 | | --- | --- | | `*_covered` | 不可缺失。 | | 双层皮肤、弯曲凹凸部位 | 可以缺失。 | | `_kid_move_root` | 已废弃，可保留或删除。 | 建议直接基于模型模板修改：不需要的骨骼可清空其中的模型块，但保留骨骼组。 ## 4. 自定义刀光纹理 在 `path` 目录中创建配置文件，将 `type` 设为 `custom_sword_trail_textures`。 ```jsonc { "type": "custom_sword_trail_textures", "textures": [ "apple.png", "test2.png" ] } ``` 为控制性能开销，刀光纹理尺寸建议不超过 512×512 像素。 ## 5. 自定义攻击动作（ATE） 本文对应的历史版本仅支持自定义普通连续攻击，暂不支持蓄力、跳劈和翻滚技。 ### 5.1 参数约定 - 配置类型为 `default_attack`。 - 除非另有说明，具有默认值的参数均可省略。 - 标记为“标准”的参数应由双 AOPT 一致支持。 - 非标准参数的行为由具体运行环境决定。 - `rt_` 前缀参数由构建系统生成，供 Python 运行时使用，不应作为用户配置填写。 ### 5.2 配置示例 ```jsonc { "type": "default_attack", "ate_id": "custom_attack_1", // 必填 "ate_name": "常态攻击", // [标准] 未填写时使用 ate_id "default_items": [], // 可选：为指定物品默认添加此攻击预设 "attack_type": "default", // 可选 random：随机选择子节点攻击 "custom_sounds": {}, // [标准] 向玩家资源添加自定义 sounds "off_hand": false, // 声明是否为副手 ATE "attack_childs": [ { "attack_time": 2.0, "can_break_time": 0.5, "anim_time": 0.5, "play_anims": ["animation.xxx", "animation.xxx2"], "hit_time_line": { "0.0": { "type": "front_aoe", "range": 2, "hurt_mut": 1.8, "hurt_vec": [0, 0, 0], "break_block": false, "args": {} } }, "cmd_time_line": { "0.5": [ "/say 唱跳RAP", "/say 我是雪豹", "xxx(1, true)", "server::myMod::xxxFile::func(...)", "client::myMod::xxxFile::func(...)" ] }, "blockbench": false, "stop_mot_when_end": false, "lock_pos_y": false, "move_time_line": { "0.0": [0, 0, 0], "0.2": [0, 0, 0] } } // 继续添加子节点，即可定义后续连击 ] } ``` 以上动画、函数与资源名称均为示例；`func(...)` 中的 `...` 表示待填写的实际参数。 ### 5.3 ATE 基础参数 | 参数 | 默认值 / 必填性 | 说明 | | --- | --- | --- | | `ate_id` | 必填 | 攻击预设标识；缺失时构建会抛出异常警告。 | | `ate_name` | 默认使用 `ate_id` | **标准**。攻击预设名称。 | | `default_items` | 可选 | 为指定物品默认添加此攻击预设。 | | `attack_type` | `default` | 设为 `random` 时随机选择子节点攻击。 | | `custom_sounds` | 可选 | **标准**。向玩家资源添加自定义 `sounds`；不同 MOD 使用相同键名会互相覆盖，应避免非重复资源重名。 | | `off_hand` | `false` | 是否为副手 ATE。 | | `attack_childs` | 子节点列表 | 定义各段攻击的动画、命中、命令与移动时间线。 | ### 5.4 子节点时序与动画 | 参数 | 默认值 / 必填性 | 说明 | | --- | --- | --- | | `attack_time` | 必填 | 整段攻击的持续时间。超过该时间视为自然结束，无法继续衔接下一个子节点。 | | `can_break_time` | 必填 | 从该时间开始，攻击可以被打断并衔接到下一个子节点。 | | `anim_time` | 默认与 `can_break_time` 相同 | 有效动画时间。若非移动打断动作，超过该时间会打断动画并回到待机；这不代表攻击结束，攻击结束仍以 `attack_time` 为准。 | | `play_anims` | 可选 | 攻击动画，支持字符串或字符串列表。 | 上述时间参数以秒为单位。 ### 5.5 命中时间线：hit_time_line 以时间字符串为键，指定对应时刻的攻击效果。 | 参数 | 默认值 | 说明 | | --- | --- | --- | | `type` | `front_aoe` | 支持 `front_aoe`、`aoe`。 | | `range` | `3` | 攻击半径。 | | `hurt_mut` | `1` | 攻击伤害倍率。 | | `hurt_vec` | `[0, 0, 0]` | **标准**。击退向量；默认不作击退向量处理。也可填写单个数值 `v`，自动构造为 `[0, 0, v]`。 | | `break_block` | `false` | **标准**。是否破坏方块（裂地）。 | | `args` | 未注明 | 非标准传递参数，由具体运行环境处理。 | ### 5.6 命令时间线：cmd_time_line **标准功能**。以时间字符串为键，每个时刻支持一个字符串或字符串列表。 | 写法 | 行为 | | --- | --- | | `/say 示例` | 仅以 `/` 开头的内容作为游戏指令执行。 | | `xxx(1, true)` | 调用内置自定义函数；参数类型遵循 JSON，例如布尔值使用 `true` / `false`，而非 Python 的 `True` / `False`。 | | `server::myMod::xxxFile::func(...)` | 在服务端调用 `myMod.xxxFile` 中的 `func`，会在参数最前面额外传入 `playerId`。 | | `client::myMod::xxxFile::func(...)` | 在客户端调用 `myMod.xxxFile` 中的 `func`。 | ### 5.7 移动时间线与运动控制 以下均为**标准参数**。 | 参数 | 默认值 | 说明 | | --- | --- | --- | | `blockbench` | `false` | 启用后，`move_time_line` 的 Z 轴反向解析，移动单位按像素处理，16 像素为 1 格。 | | `stop_mot_when_end` | `false` | 启用后，在动作结束时重置当前瞬时速度，可按需用于避免滑动。 | | `lock_pos_y` | `false` | 启用后，`move_time_line` 严格处理 Y 轴位置，可实现滞空；关闭时，Y 轴为 `0` 的数据会混合重力加速度。 | | `move_time_line` | 未注明 | 以时间字符串为键；值支持三维数值列表或单个数值 `v`，后者在运行时自动构造为 `[0, 0, v]`。 | ### 5.8 构建系统生成的运行时参数 以下参数仅供 Python 层使用，无需在用户配置中手动填写。 ```jsonc { "rt_bind_query": "query.mod.xxx", "rt_anim_load": "ks_aopt_{&ate_id}_root", "rt_anims_kv": { "ks_aopt_{&ate_id}_root": "controller.animation.ks_aopt_{&ate_id}" } } ``` | 参数 | 说明 | | --- | --- | | `rt_bind_query` | **标准**。必定生成，用于控制攻击下标，`0` 表示终止。 | | `rt_anim_load` | **标准**。对应动画控制器的 key，应持续工作，以便及时混合动画。 | | `rt_anims_kv` | **标准**。静态初始化资源映射，包含的控制器与动画应全部加载到玩家。 | ### 5.9 动画资源与命名 动画开发模型标准：`Models/work_model.json`。 `animations` 资源可放置在构建 `path` 目录中，也可放置在 `src/{RES_PACK}/animations` 中。 构建系统不会自动重命名动画资源。为避免多个 MOD 之间发生名称冲突，建议使用作者名或项目名作为动画名称前缀。 ## 6. 进阶：API 接入 `MOD_API` 提供适用于 AOPT 的开放接口。调用相关功能前，应先通过 `KAPI.hasMod()` 判断 AOPT 是否存在。 ### 6.1 原生 MOD 项目 建议监听 `LoadClientAddonScriptsAfter` 事件，在确认 AOPT 存在后进行操作。部分接口具有特殊调用时机要求，应以接口说明为准。 ```python # -*- coding: utf-8 -*- import mod.client.extraClientApi as clientApi from KID_OpenSdk.ClientAPI import KAPI ClientSystem = clientApi.GetClientSystemCls() class MySystem(ClientSystem): def __init__(self, namespace, systemName): ClientSystem.__init__(self, namespace, systemName) self.ListenForEvent( clientApi.GetEngineNamespace(), clientApi.GetEngineSystemName(), "LoadClientAddonScriptsAfter", self, self.LoadClientAddonScriptsAfter ) def LoadClientAddonScriptsAfter(self, args): if KAPI.hasMod(): # 在此调用 AOPT 接口 pass ``` ### 6.2 QuMod 项目 QuMod 1.3.3+ 可直接在 `modMain.py` 中判断并处理。 ```python # -*- coding: utf-8 -*- from QuModLibs.QuMod import * MOD = EasyMod() @PRE_CLIENT_LOADER_HOOK def QRT_KID_API(): from KID_OpenSdk.ClientAPI import KAPI if KAPI.hasMod(): MOD.Client("KAOPT_RT") ``` 详细功能请查阅对应版本的 Python 文件定义，或联系相关开发者咨询。 ## 7. 工具与扩展项目商业化授权 使用本创作工具开发的 MOD 扩展项目开放使用，允许自由使用、修改、分发和商业化本工具及其衍生作品，无需获得额外授权或支付费用。 **上述授权不改变相关模型标准资产的所有权与使用范围。** 相关模型标准资产归原作者所有，仅供 AOPT 适配及扩展包开发使用；如需将其用于独立项目或其他超出该范围的用途，应另行取得原作者授权。