KumoAddon: MobExtra

KumoAddon: MobExtra

这是 KumoDesu: Ascension 的附属模组，将进化和技能系统扩展到原版 Minecraft 生物。任何拥有 JSON 数据文件的实体都会成为 KumodesuMob，具备完整的属性追踪、升级、技能使用和成长功能——无需修改代码。

概览

KumoAddon: MobExtra 可以将普通生物（僵尸、骷髅、苦力怕等）变成功能齐全的 Kumodesu 生物，并接入 Spider/Stats/Skills 系统。每种生物都有自己的属性，可以升级、获得技能点，甚至可以通过 GenericMasterSkillGoal 使用技能。

功能

• 通用生物系统：为任意 LivingEntity 添加 JSON 文件即可转换，无需注册实体或编写代码
• 可配置属性：通过数据包 JSON 设置基础 HP、MP、SP、攻击、防御、魔法、抗性和速度
• 逐级成长：通过 JSON 中的 growth_per_level 定义每级属性增长
• 生成等级范围：使用 level_range（min/max）随机生成等级，并为每个高于 1 级的等级应用 growth_per_level
• 等级不设上限：最高等级可配置（默认为 99999），并提供 can_level_up 开关
• 随机技能点：生成时在最小值与最大值范围内随机发放技能点
• 技能使用：启用 GenericMasterSkillGoal，让生物施放 mob_skills/ JSON 配置中定义的技能
• 选择性同步属性：控制需要同步的原版属性（生命值、速度、攻击力），只同步你配置的属性
• NBT 持久化：等级、属性、技能、冷却时间和技能点都会在存档中保留
• 原版属性回退：没有附属模组数据的生物仍会报告其实际原版属性（生命值、攻击力、护甲、速度），用于鉴定和战斗计算
• 无需修改主模组：从自己的 kumo_mobextra 数据命名空间加载，可与主模组并行运行且不会冲突

需求

• Minecraft：1.20.1
• Forge：1.20.1-47.x（47.2.0+）
• KumoDesu: Ascension 0.3.9+

JSON 文件格式

生物数据（mob_data）

位置：data/kumo_mobextra/mob_data/{namespace}/{entity}.json

{
  "evolution_id": "",
  "race_id": "",
  "max_level": 99999,
  "level_range": { "min": 1, "max": 10 },
  "can_level_up": true,
  "skill_points_per_level": { "min": 1, "max": 5 },
  "base_stats": {
    "raw_hp": 40,
    "raw_mp": 20,
    "raw_sp_yellow": 20,
    "raw_sp_red": 20,
    "raw_attack": 10,
    "raw_defense": 5,
    "raw_magic": 5,
    "raw_resistance": 5,
    "raw_speed": 10
  },
  "growth_per_level": {
    "hp": 5,
    "mp": 2,
    "sp_yellow": 2,
    "sp_red": 2,
    "attack": 3,
    "defense": 2,
    "magic": 2,
    "resistance": 2,
    "speed": 1
  },
  "can_use_skills": true,
  "sync_stats": ["health", "speed", "attack"]
}

level_range为可选项（默认值为 1-1）。新生时，附属模组会在 min 和 max 之间（含两端）随机生成等级（上限为 max_level），并对每个高于 1 级的等级应用一次 growth_per_level。已保存的生物会保留其 NBT 等级。

条件等级范围（level_ranges）——新格式

新的 level_ranges 数组支持带条件的多个等级范围。使用第一个匹配的条目。没有条件的条目会作为回退选项。

{
  "level_ranges": [
    {
      "min": 20,
      "max": 30,
      "dimension_id": "minecraft:the_end",
      "player_total_stats": { "min": 500, "max": 1000 },
      "player_specific_stats": { "attack": { "min": 50, "max": 100 } },
      "player_radius": 20
    },
    {
      "min": 10,
      "max": 20,
      "dimension_id": "minecraft:the_nether"
    },
    {
      "min": 1,
      "max": 10
    }
  ]
}

条件字段：

• dimension_id（字符串）：仅当生物在此维度生成时才匹配（例如 minecraft:overworld、minecraft:the_nether、minecraft:the_end）
• player_total_stats（包含 min/max 的对象）：当附近至少有一名拥有 Kumodesu 数据（PlayerSpiderData）的玩家，其总属性（生命值、魔力值、耐力值、攻击、防御、魔法、抗性、速度之和）处于此范围内时匹配
• player_specific_stats（将属性名称映射到最小值/最大值的对象）：当附近至少有一名拥有 Kumodesu 数据的玩家，其指定属性处于范围内时匹配。有效属性名称：hp、mp、sp_yellow、sp_red、attack、defense、magic、resistance、speed
• player_radius（整数，默认值为 15）：玩家条件的搜索半径。覆盖 player_total_stats 和 player_specific_stats 检查默认的 15 格半径

评估顺序：

1. 按数组中的顺序检查条目
2. 选择第一个所有指定条件均匹配的条目
3. 没有条件的条目（空对象 {} 或仅包含 min/max）会作为通用回退项
4. 如果使用旧版 level_range 对象，则会将其转换为不带条件的单个条目

生物技能（mob_skills）

位置：data/kumo_mobextra/mob_skills/{namespace}/{entity}.json

{
  "mob_id": "minecraft:zombie",
  "global_cooldown": 20,
  "skills": [
    {
      "skill_id": "poison_fang",
      "level": 1,
      "frequency": 1.0
    },
    {
      "skill_id": "hit",
      "level": 1,
      "frequency": 2.0
    }
  ],
  "custom_mp_costs": {},
  "custom_sp_costs": {},
  "custom_cooldowns": {},
  "custom_casting_times": {}
}

示例：转换僵尸

1. 创建包含所需属性和配置的 data/kumo_mobextra/mob_data/minecraft/zombie.json
2. （可选）创建 data/kumo_mobextra/mob_skills/minecraft/zombie.json 以启用技能使用
3. 生成僵尸——它们会带有已配置的属性、生命值、技能点和技能

工作原理

1. 能力附加：AddonMobCapability会为任何拥有匹配 mob_data JSON 条目的 LivingEntity 附加 AddonMobData 能力，并通过实体类型 ID 查找条目（例如 minecraft:zombie）
2. Mixin 集成：LivingEntityMixin会在所有 LivingEntity 实例上实现 KumodesuMob，有能力数据时委托给该数据，否则回退到原版属性
3. 技能加载：AddonMobSkillLoader会从 kumo_mobextra:mob_skills/ 加载技能配置，并支持按实体类型 ID 查找
4. 生成：生成时（EntityJoinLevelEvent），附属模组会初始化资源（MP/SP 恢复至上限）、授予随机技能点、加载技能、同步已配置的属性，并可选择注入 GenericMasterSkillGoal
5. 升级：生物会获得经验值、升级并提升属性，还会根据技能阶级获得容量加成——最高等级受配置的 max_level
6. 限制刻更新：每 10 刻同步一次已配置的属性。技能冷却时间会递减。生命恢复机制与玩家生物的 MP/SP 恢复机制相同。