Emaki Series

简体中文

English

简体中文

English

Appearance

宝石定义 ​

宝石定义描述一颗宝石能提供哪些效果、可以镶嵌到哪些插槽、费用配置以及升级路径。文件位于 gems/*.yml，文件名即为宝石的内部标识。

顶层字段 ​

字段类型必填说明
idstring是宝石唯一 ID。加载时转为小写；为空则该文件不会加载。
display_namestring否宝石显示名（MiniMessage 格式）。默认使用 id。
lorelist否宝石物品自身的 Lore。
gem_typestring否宝石类型，用于插槽兼容性匹配（如 attack、defense、utility、universal）。默认 universal。
levelinteger否宝石基础等级，升级后递增。默认 1，最小 1。
item_sourceslist是宝石物品来源（格式 "提供者-物品ID"）。无法解析时该宝石不会加载。
custom_model_datainteger否自定义模型数据。
effectslist否宝石效果列表（统一格式，见下方说明）。
socket_compatibilitylist否允许镶嵌的插槽类型列表。留空表示可镶嵌任意插槽类型。
required_gemslist否依赖的宝石 ID 列表。
conflicting_gemslist否冲突的宝石 ID 列表。
inlay_costobject否镶嵌费用配置。
extract_costobject否拆卸费用配置。
extract_returnobject否拆卸返还模式。
upgradeobject否升级配置。
actions.inlay_successlist否镶嵌成功时执行的动作行。
actions.extract_successlist否提取成功时执行的动作行。

socket_compatibility 中写入 universal 时，该宝石可镶嵌到任意类型插槽。

效果系统（effects） ​

宝石效果统一使用 effects 列表，通过 type 字段区分类型：

type载荷键说明
variablesvariables表达式引擎变量，用于 Lore 占位符渲染。
ea_attributeea_attributesEmakiAttribute PDC 属性，写入装备 PDC。
es_skilles_skillsEmakiSkills 技能附加。
name_actionname_actions镶嵌后对装备名称的修改。
lore_actionlore_actions镶嵌后对装备 Lore 的修改。

variables 与 ea_attributes 的值可以是数值或表达式，可引用 %level%；同一块中先解析的键可作为后续表达式的变量。

顶层写法 ​

除 effects 列表外，解析器同样接受直接写在宝石根节点上的 variables、ea_attributes、name_actions、lore_actions：

yaml
variables:
  physical_attack: 8
ea_attributes:
  physical_attack: 8.0

variables 与 ea_attributes 会合并两种写法的结果，effects 中的同名键覆盖顶层键；name_actions 与 lore_actions 在顶层存在时优先，不再读取 effects 中的对应项。技能只能通过 effects 中的 es_skill 声明。

yaml
effects:
  - type: "variables"
    variables:
      physical_attack: 8
      physical_crit_rate: 3
  - type: "ea_attribute"
    ea_attributes:
      physical_attack: 8.0
      physical_crit_rate: 3.0
  - type: "name_action"
    name_actions:
      - action: "append_suffix"
        value: " <red>[%display_name%]</red>"
  - type: "lore_action"
    lore_actions:
      - action: "append"
        content:
          - "<red>◆ %display_name%: 物理攻击+%physical_attack% 暴击率+%physical_crit_rate%%</red>"

最小示例 ​

yaml
id: "ruby_basic"
display_name: "<red>红宝石</red>"
gem_type: "attack"
level: 1
item_sources:
  - "minecraft-redstone"
socket_compatibility:
  - "attack"
  - "universal"
effects:
  - type: "variables"
    variables:
      physical_attack: 5
  - type: "ea_attribute"
    ea_attributes:
      physical_attack: 5.0

费用配置 ​

镶嵌费用 ​

yaml
inlay_cost:
  currencies:
    - provider: "vault"
      currency_id: ""
      base_cost: 1000
      cost_formula: "%base_cost% * %level%"
      display_name: "<gold>金币</gold>"
  materials:
    - item_sources:
        - "minecraft-gold_nugget"
      amount: 1

拆卸费用 ​

yaml
extract_cost:
  currencies:
    - provider: "vault"
      currency_id: ""
      base_cost: 500
      cost_formula: "%base_cost% * %level%"
      display_name: "<gold>金币</gold>"

拆卸返还模式 ​

字段说明
mode"original"（原样返还）、"destroy"（销毁）、"downgrade"（按概率降级返还）。别名：destroyed 等同 destroy，degraded 等同 downgrade；无法识别的值回退为 original。
downgrade_levels降级时降低的等级数。最小 1，默认 1。
degraded_chance触发降级的概率，取值 0.0~1.0。0.0 表示从不降级，1.0 表示必定降级。仅在 mode: downgrade 时生效。

降级后等级小于等于 0 时，宝石不会返还。

yaml
extract_return:
  mode: "original"
  downgrade_levels: 1
  degraded_chance: 0.0

升级系统 ​

宝石支持内置升级系统，通过消耗材料和金币提升等级，解锁更强效果。

升级顶层字段 ​

字段说明
enabled是否启用升级。
max_level最大等级。
gui_template升级 GUI 模板。
failure_penalty升级失败惩罚："none"、"downgrade"、"destroy"。
economy全局默认经济配置（各等级可单独覆盖）。
success_rates各等级升级成功率。
levels各等级详细配置。

等级配置 ​

每个等级可包含：

字段说明
display_name该等级的显示名称。
effects升级后的效果（覆盖基础 effects）。
materials升级所需材料。
economy单独覆盖此等级的经济配置。
success_rate单独覆盖此等级的成功率。
failure_penalty单独覆盖此等级的失败惩罚。
actions升级成功/失败时的动作。

升级示例 ​

yaml
upgrade:
  enabled: true
  max_level: 4
  gui_template: "upgrade/default"
  failure_penalty: "none"
  economy:
    enabled: true
    currencies:
      - provider: "vault"
        currency_id: ""
        base_cost: 2000
        cost_formula: "%base_cost% * %target_level%"
        display_name: "<gold>金币</gold>"
  success_rates:
    2: 100.0
    3: 80.0
    4: 60.0
  levels:
    2:
      display_name: "<red>红宝石 II</red>"
      effects:
        - type: "variables"
          variables:
            physical_attack: 12
            physical_crit_rate: 4
        - type: "ea_attribute"
          ea_attributes:
            physical_attack: 12.0
            physical_crit_rate: 4.0
        - type: "lore_action"
          lore_actions:
            - action: "append"
              content:
                - "<red>◆ 红宝石 II: 物理攻击+12 暴击率+4%</red>"
      materials:
        - item_sources:
            - "minecraft-gold_nugget"
          amount: 3
      actions:
        success:
          - 'sendmessage text="<gold>红宝石升级至 II！</gold>"'
        failure: []
    4:
      display_name: "<red>红宝石 IV</red>"
      effects:
        - type: "variables"
          variables:
            physical_attack: 22
            physical_crit_rate: 7
        - type: "ea_attribute"
          ea_attributes:
            physical_attack: 22.0
            physical_crit_rate: 7.0
        - type: "es_skill"
          es_skills:
            - "ruby_burst"
        - type: "lore_action"
          lore_actions:
            - action: "append"
              content:
                - "<red>◆ 红宝石 IV: 物理攻击+22 暴击率+7%</red>"
                - "<gold>  ★ 解锁技能: 红宝石爆发</gold>"
      materials:
        - item_sources:
            - "minecraft-netherite_ingot"
          amount: 1
      economy:
        enabled: true
        currencies:
          - provider: "vault"
            currency_id: ""
            base_cost: 5000
            cost_formula: "%base_cost%"
            display_name: "<gold>金币</gold>"
      success_rate: 60.0
      failure_penalty: "downgrade"
      actions:
        success:
          - 'sendmessage text="<gold>成功将红宝石升级至 IV！</gold>"'
        failure:
          - 'sendmessage text="<red>升级失败，宝石降级了...</red>"'

全局升级默认值 ​

如果单颗宝石没有单独配置 success_rate、success_rates 或 failure_penalty，系统会使用 config.yml 中的全局升级配置：

yaml
upgrade:
  global_success_rates:
    2: 100.0
    3: 80.0
    4: 60.0
    5: 45.0
    6: 30.0
  global_failure_penalty: "none"
字段说明
global_success_rates按目标等级配置升级成功率。key 为升级后的等级。
global_failure_penalty全局失败惩罚，支持 none、downgrade、destroy。

失败惩罚说明：

值行为适合场景
none失败不改变宝石等级。新手服、低风险养成。
downgrade失败降低 1 级，最低保留 1 级。中高阶成长线。
destroy失败销毁宝石。高价值、强消耗玩法。

单颗宝石或单个等级中的 failure_penalty 优先级高于全局配置。设计高阶宝石时，可以低等级使用 none，高等级逐步改为 downgrade，只在极高阶使用 destroy。

插槽类型设计 ​

常见插槽类型分类：

类型适用装备推荐宝石方向
attack武器攻击、暴击、穿透。
defense防具防御、生命、减伤。
utility饰品功能性属性（速度、吸血、冷却）。
universal所有装备通用属性（经验加成、掉落率）。

建议不超过 4 种插槽类型，否则玩家理解成本过高。