数据包自定义

服主专区 — 面向整合包作者与服主。普通玩家请从新手上路开始。

本指南说明如何通过数据包、资源包与配置文件，在不修改 MOD 源码的前提下调整命途的天赋、法术、配方与 TXP 相关行为。

你能自定义什么

方式	可自定义内容	是否需要重启
数据包	天赋、法术、天赋门控配方、标签（挖矿 TXP 等）	`/reload` 即可
资源包	天赋/法术名称与描述、效果提示文本	客户端重载资源包
配置文件	TXP 奖励、先天数量、魔力、发育型天赋参数等	需重启

重要限制： 天赋的 effects[].type 与法术的 type 必须是 MOD 已实现的类型（见下文参考表）。数据包不能凭空创造全新的机制逻辑，只能组合、调参或替换现有内容。

快速开始

1. 创建数据包

在存档或服务器的 datapacks/ 目录下新建文件夹，例如 my_fatepath_pack/，结构如下：

my_fatepath_pack/
├── pack.mcmeta
└── data/
    └── mypack/                    ← 你的命名空间（建议不要用 fatepath，避免与 MOD 内置文件冲突）
        ├── talents/
        │   └── combat/
        │       └── heavy_strike.json
        ├── spells/
        │   └── heavy_strike_smite.json   ← 若需要配套法术
        └── recipe/
            └── special_sword.json

pack.mcmeta 示例：

json

{
  "pack": {
    "pack_format": 48,
    "description": "My Fatepath Custom Talents"
  }
}

pack_format 请与目标 Minecraft 版本匹配（1.21.1 通常为 48）。

2. 启用并重载

单人：创建世界时启用数据包，或在世界设置中启用
服务器：将数据包放入 world/datapacks/，执行 /reload
整合包：在 kubejs/ 同级或启动器的默认数据包列表中加入

重载后查看服务端日志，应出现类似：

Loaded N talents from data
Loaded N spells from data

若 JSON 有误，日志会打印 Failed to load talent ... 或 Failed to load spell ...。

天赋（Talents）

文件位置

data/<命名空间>/talents/<任意子路径>.json

每个文件包含一个天赋对象。文件名不影响逻辑，但建议与天赋 ID 对应以便维护。

完整字段参考

字段	类型	必填	说明
`id`	字符串	是	天赋 ID，格式 `命名空间:分类/名称`，如 `mypack:combat/heavy_strike`
`type`	字符串	是	`talent`（天赋）或 `skill`（技能）；兼容旧值 `innate` / `acquired`
`category`	字符串	skill 必填	TXP 分类：`combat` / `mining` / `farming` / `fishing` / `crafting` / `exploration`
`max_level`	整数	是	最高等级
`cost_per_level`	整数数组	skill 建议填	每级升级 TXP 消耗，长度须 ≥ `max_level`（索引 0 = 升到 1 级）
`prerequisites`	数组	否	前置天赋，见下文
`effects`	数组	否	效果列表，见下文
`on_death`	对象	否	死亡惩罚
`mutually_exclusive`	字符串数组	否	互斥天赋 ID 列表
`weight`	整数	先天建议填	随机抽取权重，越大越常见
`rarity`	字符串	否	`common` / `uncommon` / `rare` / `epic`，默认 `common`
`hidden`	布尔	否	`true` 时不在天赋 UI 中显示
`grant_on_join`	整数或对象	否	首次加入时直接授予的等级
`toggleable`	布尔	否	`true` 时玩家可在 UI 中开关该天赋

示例：技能（被动）

json

{
  "id": "mypack:combat/heavy_strike",
  "type": "skill",
  "category": "combat",
  "max_level": 3,
  "cost_per_level": [20, 40, 80],
  "prerequisites": [
    { "talent": "fatepath:combat/strength", "level": 2 }
  ],
  "effects": [
    { "type": "fatepath:attack_damage", "value": [1.0, 2.0, 3.0] }
  ],
  "rarity": "uncommon"
}

示例：先天天赋

json

{
  "id": "mypack:talent/sturdy",
  "type": "talent",
  "max_level": 1,
  "effects": [
    { "type": "fatepath:armor", "value": 3.0 }
  ],
  "weight": 20,
  "rarity": "common"
}

示例：带死亡惩罚

json

{
  "on_death": { "lose_levels": 1, "min_level": 0 }
}

也可使用 "lose_all": true 表示死亡后清零。

效果（effects）

每个效果对象：

字段	说明
`type`	效果类型 ID，必须为 `fatepath:<名称>`（见下表）
`value`	单个数值，或按等级排列的数组
`scope`	可选，部分效果使用（如洞察的范围类型）
`range`	可选，整数或整数数组

属性类效果（直接修改玩家属性，每级取 value 对应项）：

type	作用
`fatepath:attack_damage`	攻击力 +N
`fatepath:armor`	护甲 +N
`fatepath:max_health`	生命上限 +N
`fatepath:luck`	幸运 +N
`fatepath:mining_speed`	挖矿速度 +N%（0.1 = 10%）
`fatepath:movement_speed`	移动速度 +N%
`fatepath:fishing_speed`	钓鱼速度 +N%

事件类效果（由 MOD 逻辑驱动，通常只需声明 type，数值按具体效果填写）：

type	作用
`fatepath:night_vision`	永久夜视
`fatepath:water_breathing`	永久水下呼吸
`fatepath:fire_resistance`	永久抗火
`fatepath:poison_resistance`	抗毒性（发育型）
`fatepath:thermal_skin`	热肤（发育型）
`fatepath:mining_fortune`	额外掉落几率
`fatepath:catalyst_smelting`	催化熔炼（挖矿时几率掉落熔炼成品）
`fatepath:fishing_loot_tier`	钓鱼战利品等级
`fatepath:auto_reel`	自动收杆
`fatepath:crop_plant_chance`	种植触发概率（常与 `crop_plant_growth` 搭配）
`fatepath:crop_plant_growth`	种植成熟度提升比例
`fatepath:cobblestone_refine`	解锁炼石配方
`fatepath:imbued_ash`	武器/箭矢附加灼烧
`fatepath:magma_armor`	熔岩铠甲（低血量触发）
`fatepath:fireball`	解锁火球术（需配套 spell JSON）
`fatepath:holy_smite`	解锁圣光惩戒
`fatepath:flame_dash`	解锁烈焰冲击
`fatepath:firestorm`	解锁火雨术
`fatepath:swift_surge`	解锁迅涌
`fatepath:cloud_vortex`	解锁云涡
`fatepath:ignite`	解锁点火术（空手交互）

若 type 不在上表中，天赋仍可加载，但不会产生实际效果（日志中会出现 Unhandled talent effect）。

法术（Spells）

文件位置

data/<命名空间>/spells/<名称>.json

字段参考

字段	类型	说明
`id`	字符串	法术 ID，如 `mypack:my_fireball`
`type`	字符串	法术逻辑类型（见下表）
`required_talent`	字符串	关联天赋 ID，玩家须拥有该天赋才能施放
`color`	字符串	技能轮盘颜色，如 `"#FF6622"`
`icon`	字符串	轮盘图标物品 ID，如 `"minecraft:fire_charge"`
`hidden`	布尔	隐藏法术（不显示在轮盘/命令补全）
`radius`	浮点	区域法术半径（火雨、云涡等）
`duration_ticks`	整数	持续时间（tick，20 = 1 秒）
`angular_speed`	浮点	云涡角速度
`mana_cost`	整数	顶层魔力消耗（部分法术以 levels 内为准）
`levels`	数组	各等级数值，长度建议与天赋最高等级一致

法术类型（type）

type	施放方式	说明
`fatepath:projectile_fireball`	技能轮盘	火球弹射物
`fatepath:holy_smite`	技能轮盘	落雷
`fatepath:flame_dash`	技能轮盘	向前突进 + 火墙
`fatepath:area_firestorm`	技能轮盘	范围火雨
`fatepath:swift_surge`	技能轮盘	短时加速
`fatepath:area_vortex`	技能轮盘	云涡
`fatepath:ignite`	空手右键	不显示在技能轮盘

levels 数组字段

字段	说明
`damage`	伤害
`scale`	弹射物大小（火球）
`sets_fire`	是否点燃
`pierce`	穿透数量
`cooldown_ticks`	冷却（tick）
`speed`	弹射物/突进速度等
`mana_cost`	该等级魔力消耗
`explosion_radius`	爆炸半径
`target_range`	目标/突进距离
`splash_radius` / `splash_ratio`	溅射范围与比例
`undead_multiplier`	对亡灵倍率
`debuff_duration_ticks`	负面效果持续时间

示例：自定义火球（3 级）

天赋侧：

json

{
  "id": "mypack:combat/arcane_bolt",
  "type": "skill",
  "category": "combat",
  "max_level": 3,
  "cost_per_level": [25, 50, 100],
  "effects": [{ "type": "fatepath:fireball" }],
  "rarity": "rare"
}

法术侧：

json

{
  "id": "mypack:arcane_bolt",
  "type": "fatepath:projectile_fireball",
  "required_talent": "mypack:combat/arcane_bolt",
  "color": "#AA44FF",
  "icon": "minecraft:ender_pearl",
  "levels": [
    { "damage": 5.0, "scale": 0.4, "cooldown_ticks": 40, "speed": 1.5, "mana_cost": 10, "explosion_radius": 0.0 },
    { "damage": 8.0, "scale": 0.55, "sets_fire": true, "cooldown_ticks": 80, "speed": 1.6, "mana_cost": 15, "explosion_radius": 1.0 },
    { "damage": 14.0, "scale": 0.75, "sets_fire": true, "pierce": 1, "cooldown_ticks": 120, "speed": 1.7, "mana_cost": 25, "explosion_radius": 2.0 }
  ]
}

关联规则： 一个天赋通过 effects 中的 fatepath:fireball 等类型关联法术；法术 JSON 的 required_talent 必须指向对应天赋 ID。每个天赋通常对应一个法术定义。

天赋门控配方

文件位置

data/<命名空间>/recipe/<名称>.json

示例

json

{
  "type": "fatepath:talent_gated",
  "group": "mypack_special",
  "category": "equipment",
  "required_talent": "mypack:crafting/master_smith",
  "ingredients": [
    { "item": "minecraft:iron_ingot" },
    { "item": "minecraft:iron_ingot" },
    { "item": "minecraft:stick" }
  ],
  "result": {
    "id": "minecraft:iron_sword",
    "count": 1
  }
}

仅当玩家拥有且启用 required_talent 时，该配方才会出现在合成书中并可用。可参考 MOD 内置的炼石配方（fatepath:crafting/cobblestone_refine）。

标签（Tags）

通过标签调整 TXP 与部分天赋的判定范围，无需写 Java。

标签	路径	用途
挖矿 TXP 方块	`#fatepath:mining_txp_blocks`	破坏这些方块获得挖矿 TXP
挖矿 TXP 排除	`#fatepath:mining_txp_excluded`	排除不计 TXP 的方块
抗毒训练食物	`#fatepath:poison_resistance_training_food`	计入抗毒性发育进度
催化熔炼矿石	`#fatepath:catalyst_smelting_ores`	触发催化熔炼的方块
催化熔炼肉类	`#fatepath:catalyst_smelting_meat`	触发催化熔炼的物品

扩展示例（在你的数据包中）：

json

{
  "values": [
    "minecraft:deepslate_iron_ore",
    "mymod:custom_ore"
  ]
}

文件路径：data/mypack/tags/block/mining_txp_blocks.json（使用 # 引用时为 data/mypack/tags/block/mining_txp_blocks.json 内 "values": ["#fatepath:mining_txp_blocks", "mymod:custom_ore"]）。

本地化（资源包）

天赋与法术的显示名称不会写在 JSON 里，而是通过语言文件映射。

键名规则

类型	键名格式	示例
天赋名称	`talent.<命名空间>.<路径点分隔>`	`talent.mypack.combat.heavy_strike`
天赋描述	同上 + `.description`	`talent.mypack.combat.heavy_strike.description`
法术名称	`spell.<命名空间>.<路径>`	`spell.mypack.arcane_bolt`
效果提示	`effect.fatepath.<效果名>`	`effect.fatepath.attack_damage`

资源包路径：

assets/mypack/lang/zh_cn.json
assets/mypack/lang/en_us.json

示例 zh_cn.json：

json

{
  "talent.mypack.combat.heavy_strike": "重击",
  "talent.mypack.combat.heavy_strike.description": "每一击都更加致命。",
  "spell.mypack.arcane_bolt": "奥术弹",
  "spell.mypack.arcane_bolt.description": "发射一枚奥术能量弹。"
}

效果提示（effect.fatepath.*）目前由 MOD 内置。若自定义天赋使用了已有效果类型，会自动复用对应描述模板；全新效果类型需 MOD 支持或在资源包中覆盖 effect.fatepath.* 键。

服务端配置

配置文件：config/fatepath-common.toml（修改后需重启）。

常用调整：

toml

talentCount = 2      # 首次加入分配的天赋数量
txpMultiplier = 1.0        # 全局 TXP 倍率

[txpRewards]
farmingCropHarvest = 8
miningHardnessMultiplier = 2.0
combatMaxHealthFraction = 0.5
explorationBiomeDiscover = 8
explorationRareBiomeDiscover = 15
explorationDimensionFirst = 25
explorationBiomeSleep = 5

[mana]
max = 100
regenPerSecond = 2.0

完整说明见配置页面。

调试与测试

重载数据

/reload

常用管理命令

命令	用途
`/fatepath talent list [talent\|skill]`	列出所有已加载天赋/技能
`/fatepath talent give <玩家> <天赋ID> [等级]`	授予天赋
`/fatepath txp give <玩家> <分类> <数量>`	授予 TXP
`/fatepath spell cast <法术ID>`	测试法术
`/fatepath innate roll <玩家>`	重roll 先天天赋

权限等级 2 的命令详见命令参考。

排查清单

天赋不显示 — 检查 hidden、分类 category 是否正确、是否已通过 TXP/命令解锁
法术无法施放 — 确认 required_talent 与天赋 effects 类型匹配，魔力/冷却是否满足
效果不生效 — 确认 effects[].type 在支持列表中；查看服务端日志
名称显示为键名 — 补充资源包语言文件
配方不可见 — 确认 required_talent 已授予且未被 toggle 禁用

整合包工作流建议

新建独立命名空间（如 mypack），避免直接覆盖 fatepath: 内置 JSON，便于排查冲突
先复制再修改 — 从 MOD jar 的 data/fatepath/ 复制 JSON 到你的包中，改 ID 与数值
天赋 + 法术成对设计 — 主动技能类天赋务必同时添加 spell JSON
资源包与数据包一起分发 — 确保玩家看到中文/英文名称
用命令快速验证 — 开发阶段用 /fatepath talent give 和 /fatepath spell cast 迭代
平衡性通过配置微调 — TXP 倍率、魔力上限等优先改 fatepath-common.toml

常见场景

调整现有天赋数值

复制 MOD 内置 JSON 到你的数据包，修改 cost_per_level、effects[].value 或 spell levels，保持 id 不变。注意：若多个包定义相同 id，后加载的会覆盖前者（日志会有 Duplicate 警告）。

禁用某个天赋

无法直接“删除”MOD 内置天赋，但你可以：

将 cost_per_level 设为极高值
设置 "hidden": true
在整合包中不授予相关 TXP

新增一条完整技能线

编写 skill JSON（含 prerequisites 链）
若为 active 技能，添加 spell JSON 并关联 required_talent
添加 lang 条目
/reload 后用命令测试

服主微调进度

修改 fatepath-common.toml 中的 txpMultiplier 与各 [txpRewards] 项，重启服务器即可，无需改数据包。

进一步阅读

天赋系统 — 全部内置天赋与机制
法术系统 — 内置法术参数
TXP 系统 — 经验获取规则
配置 — 完整配置项

如需扩展全新的效果类型或法术逻辑，需要修改 MOD 源码并发布 addon；数据包 alone 无法做到。

数据包自定义 ​

你能自定义什么 ​

快速开始 ​

1. 创建数据包 ​

2. 启用并重载 ​

天赋（Talents） ​

文件位置 ​

完整字段参考 ​

示例：技能（被动） ​

示例：先天天赋 ​

示例：带死亡惩罚 ​

效果（effects） ​

法术（Spells） ​

文件位置 ​

字段参考 ​

法术类型（type） ​

levels 数组字段 ​

示例：自定义火球（3 级） ​

天赋门控配方 ​

文件位置 ​

示例 ​

标签（Tags） ​

本地化（资源包） ​

键名规则 ​

服务端配置 ​

调试与测试 ​

重载数据 ​

常用管理命令 ​

排查清单 ​

整合包工作流建议 ​

常见场景 ​

调整现有天赋数值 ​

禁用某个天赋 ​

新增一条完整技能线 ​

服主微调进度 ​

进一步阅读 ​

数据包自定义

你能自定义什么

快速开始

1. 创建数据包

2. 启用并重载

天赋（Talents）

文件位置

完整字段参考

示例：技能（被动）

示例：先天天赋

示例：带死亡惩罚

效果（effects）

法术（Spells）

文件位置

字段参考

法术类型（type）

levels 数组字段

示例：自定义火球（3 级）

天赋门控配方

文件位置

示例

标签（Tags）

本地化（资源包）

键名规则

服务端配置

调试与测试

重载数据

常用管理命令

排查清单

整合包工作流建议

常见场景

调整现有天赋数值

禁用某个天赋

新增一条完整技能线

服主微调进度

进一步阅读