模块 Module

模块是独立、完整的技能树单元。每个模块由独立的数据包 JSON 文件定义，包含名称、描述、解锁条件、初始状态、心得列表与选择 / 完成奖励。

本页介绍 Module 数据包格式。其他数据包类型:Insight / Epiphany / Path。

文件位置

data/<namespace>/epiphany/module/<path>.json

• <namespace>:你的模组 / 数据包命名空间(如 mymod)
• <path>:可以是单层文件名,也可以是子文件夹结构
• 模块的注册 ID = <namespace>:<path>
  • data/mymod/epiphany/module/combat.json → mymod:combat
  • data/mymod/epiphany/module/class/warrior.json → mymod:class/warrior

完整样例

{
    "name": "Saber",                                    // 可选
    "description": "手持刀剑的职阶",  // 可选
    "icon": "minecraft:textures/item/diamond_sword.png",  // 可选
    "item_icon": "minecraft:diamond_sword",            // 可选
    "condition": {                                     // 可选
        "type": "epiphany:or",
        "conditions": [
            { "type": "epiphany:kill_entity", "entity": "#minecraft:zombies", "count": 3 },
            { "type": "epiphany:block_broken", "block": "#minecraft:base_stone_overworld", "count": 100 }
        ]
    },
    "condition_description": "击杀 3 只亡灵 或 挖掘 100 个石头",  // 可选
    "initial_state": "locked",                         // 可选，默认为 selectable
    "on_select_reward": [                              // 可选；对象或数组
        { "type": "epiphany:item", "item": "minecraft:shield", "count": 1 },
        { "type": "epiphany:attribute", "attribute": "minecraft:generic.armor", "amount": 1.0 }
    ],
    "on_select_reward_description": "获得一面盾牌并增加 1 点护甲",  // 可选
    "on_complete_reward": [                            // 可选；对象或数组
        { "type": "epiphany:aptitude", "amount": 200 },
        { "type": "epiphany:insight_points", "amount": 1 }
    ],
    "on_complete_reward_description": "+200 阅历和 +1 心得点",  // 可选
    "insights": [                                      // 可选，默认空
        { "id": "epiphany:weapon_mastery", "depth": 0 },
        { "id": "epiphany:shield_wall",   "depth": 0 },
        { "id": "epiphany:battle_cry",    "depth": 0 },
        { "id": "epiphany:whirlwind",     "depth": 0 }
    ],
    "weight": 75                                       // 可选，默认 100
}

上例同时写出 icon 和 item_icon 以展示两种配置方式，实际使用时可以只配置其中一个。两者同时存在时，系统优先使用能够加载的 icon 纹理；纹理缺失时再尝试 item_icon。Module 当前尚未在 UI 中渲染图标，这两个字段会保留在数据中供后续界面使用。

文本组件与 i18n

name / description / *_description 字段均为 Minecraft 的 Component 文本组件，支持三种写法：

"name": "战士"                                       // 1. 纯字符串(等价于 literal)
"name": { "text": "战士", "color": "gold" }          // 2. 带样式的 literal
"name": { "translate": "mymod.module.combat.name" }  // 3. 翻译键(查 lang 文件)

i18n

当不填写 name / description / *_description 字段时，系统会自动回退到约定的翻译键，以此实现多语言：

module.<namespace>.<path>.<field>

例如模块 mymod:combat 的 name 缺省 → 自动用 module.mymod.combat.name 作为翻译键查 lang 文件。

你只需在 assets/<namespace>/lang/zh_cn.json 中提供翻译：

{
    "module.mymod.combat.name": "Saber",
    "module.mymod.combat.description": "手持刀剑的职阶",
    "module.mymod.combat.condition_description": "击杀 3 只亡灵 或 挖掘 100 个石头"
}

若 lang 文件中也未定义该键，Minecraft 会显示原始 key 字符串（如 module.mymod.combat.name）。

适用字段一览（各文档同名字段相同规则）：

• 所有类型：name / description
• Module：额外支持 condition_description / on_select_reward_description / on_complete_reward_description
• Insight：额外支持 reward_description
• Epiphany：额外支持 condition_description / reward_description

字段说明

name（可选）

• 类型：Component（字符串、样式对象或翻译键）
• 默认：缺省时回退翻译键 module.<ns>.<path>.name（详见上方"文本组件与 i18n"）

description（可选）

• 类型：Component
• 默认：缺省时回退翻译键 module.<ns>.<path>.description
• 显示在模块卡片与详情中，用于向玩家说明模块的设定与玩法

icon（可选）

• 类型：ResourceLocation，指向资源包中的纹理文件

item_icon（可选）

• 类型：物品注册 ID，例如 "minecraft:diamond_sword"
• 适合直接使用原版或其他模组物品模型，无需查找贴图路径
• Module 当前尚未在 UI 中渲染图标，该字段会保留在数据中供后续界面使用

图标自动回退

系统按以下顺序选择第一个可用图标：

1. 存在的显式 icon 纹理
2. 有效的 item_icon 物品
3. 自动拼接路径 textures/gui/<type>/<registryId>.png
   • Module:查 textures/gui/module/<path>.png
   • Insight:查 textures/gui/insight/<path>.png
   • Epiphany:查 textures/gui/epiphany/<path>.png
4. 类型默认物品图标（Module = writable_book、Insight = diamond、Epiphany = goat_horn）

显式纹理缺失或物品 ID 无效时不会中断数据包加载，而是继续执行下一层回退。

区分纹理路径与物品 ID

icon 必须是资源包纹理路径；物品注册 ID 应写入 item_icon：

"icon": "mymod:textures/gui/module/combat.png",
"item_icon": "minecraft:diamond_sword"

两者同时存在时，能够加载的 icon 优先。

condition（可选）

• 类型：条件对象（Condition Codec）
• 默认：无条件
• 仅在 initial_state == "locked" 时有意义：条件满足时模块自动解锁
• 完整 condition 类型与字段见 Condition

condition_description（可选）

• 类型：Component
• 默认：缺省时回退翻译键 module.<ns>.<path>.condition_description
• 当模块因 condition 未满足而不可选时，该文字在 UI 上以红色提示玩家"需要做什么才能解锁"

initial_state（可选）

• 类型：字符串枚举，"locked" 或 "selectable"
• 默认："selectable"
• 决定模块的初始可见性 / 可选性

值	含义
"selectable"	玩家开局即可见、可选（通常不配 condition）
"locked"	玩家初始看不到。若有 condition，满足后自动解锁；若无 condition，仅能通过 API / 命令解锁

on_select_reward（可选）

• 类型：奖励对象或奖励对象数组（InsightReward Codec）
• 默认：无奖励
• 玩家选择该模块时，奖励按数组顺序立即应用
• 继续兼容旧单对象写法；[] 表示无奖励
• 完整 reward 类型与字段见 Reward

on_select_reward_description（可选）

• 类型：Component
• 默认：缺省时回退翻译键 module.<ns>.<path>.on_select_reward_description
• 玩家悬停模块卡片（按住 Shift）时可见的选择奖励说明
• UI 中直接展示此文本，不会自动从 reward 类型推导 —— 务必手写一段玩家能看懂的话

on_complete_reward（可选）

• 类型：奖励对象或奖励对象数组（InsightReward Codec）
• 默认：无奖励
• 模块完成时（所有心得被点亮）按数组顺序额外应用奖励
• 重置时，列表奖励按逆序移除
• 系统完成模块时会自动 +1 顿悟槽，该字段是额外奖励

on_complete_reward_description（可选）

• 类型：Component
• 默认：缺省时回退翻译键 module.<ns>.<path>.on_complete_reward_description
• 说明同 on_select_reward_description，用于完成奖励

insights（可选）

• 类型：list of { id, depth }
• 默认：空 list
• 列出该模块依赖的所有心得，及其在树形结构中的层级

WARNING

树形结构规则

• depth = 0 为根节点（最顶层）
• 同一 depth 的多个心得是 AND 关系：全部点亮才能解锁下一层
• 第 N 层的父节点 = 数组中最靠后的 depth = N-1 心得（它们之间靠顺序形成父子链）

示例：

"insights": [
    { "id": "epiphany:eldritch_sight", "depth": 0 },   // 根
    { "id": "epiphany:dark_pact",      "depth": 1 },   // 父 = eldritch_sight
    { "id": "epiphany:eldritch_blast", "depth": 2 }    // 父 = dark_pact
]

详见 Insight 中对 depth 的解释。

insights 内的心得 ID 必须存在

该字段只是引用 insight 的注册 ID，不会定义心得内容。你需要另外在 data/<ns>/epiphany/insight/<name>.json 中定义该心得。引用不存在的心得会导致树渲染异常。

weight（可选）

• 类型：int
• 默认：100
• UI 排序的权重，越小越靠前显示
• 可为负数