Skip to content

User Manual

Jump to bottom
XiaoyuLack edited this page Jul 17, 2026 · 3 revisions

SLB 用户说明

SLB — 一个拔刀剑附属模组框架。基于 JSON + OBJ 的数据驱动设计，让你无需写 Java 代码就能为自己的刀添加 SE（特殊效果）。自带 slb_ses.json 提供参考示例。

安装

环境要求

依赖 | 版本 -- | -- Minecraft | 1.21.1 NeoForge | 21.x SlashBlade Resharped | ≥ 2.0.3

自检步骤

修改完 JSON 后，打开 JSONLint 之类的在线校验工具，把 JSON 贴进去检查：

  1. ✅ 所有 key 和字符串值都用双引号

  2. ✅ 每行属性末尾有逗号（最后一行不要逗号）

  3. ✅ { 和 }、[ 和 ] 数量配对

  4. ✅ 路径用正斜杠 /，不是反斜杠

  5. ✅ 数字不加引号，字符串必须加引号

参考模板 _example_blank.json.example

SLB 自带一个 _example_blank.json.example 文件作为格式参考。后缀是 .json.example，不是 .json，所以 SlashBlade 不会加载它，也就不会因为缺少模型文件而崩溃。

想用这把刀时，把文件名改成 _example_blank.json，然后把 model.obj 和 texture.png 放到 assets/slb/model/example_blank/ 目录下即可。

许可

All Rights Reserved. 仅供学习交流使用。

# SLB 用户说明

SLB — 一个拔刀剑附属模组框架。基于 JSON + OBJ 的数据驱动设计，让你无需写 Java 代码就能为自己的刀添加 SE（特殊效果）。自带 slb_ses.json 提供参考示例。

安装

环境要求

依赖 版本
Minecraft 1.21.1
NeoForge 21.x
SlashBlade Resharped ≥ 2.0.3

步骤

  1. 安装 NeoForge 1.21.1
  2. 安装 SlashBlade Resharped 2.0.3+
  3. 把 SLB.jar 丢进 .minecraft/mods/
  4. 启动游戏

快速上手：四步加一把刀

不需要编程工具，只要一个能打开 zip 的软件（WinRAR / 7-Zip / Bandizip）。

用压缩软件打开 SLB.jar（不要解压，直接在里面操作）。

第 1 步：放模型

把模型文件拖进 assets/slb/model/ 目录，一个刀一个文件夹：

SLB.jar/assets/slb/model/
└── 你的刀名/           ← 新建文件夹
    ├── model.obj       ← 3D 模型文件
    └── texture.png     ← 贴图文件

第 2 步：写 JSON 定义

在 data/slb/slashblade/named_blades/ 里新建一个 JSON 文件，命名随意，比如 my_sword.json：

{
  "name": "slb:my_sword",
  "properties": {
    "attack_base": 12.0,
    "max_damage": 200,
    "slash_art": "slashblade:judgement_cut",
    "sword_type": ["bewitched"],
    "special_effects": ["slb:swift_edge", "slb:blood_edge"]
  },
  "render": {
    "model": "slb:model/my_sword/model.obj",
    "texture": "slb:model/my_sword/texture.png",
    "carry_type": "katana"
  },
  "enchantments": [
    { "id": "minecraft:sharpness", "lvl": 5 },
    { "id": "minecraft:unbreaking", "lvl": 3 }
  ]
}

name 里的 slb: 前缀不要改，冒号后面的名字跟你文件夹名字保持一致就行。

第 3 步：添加物品模型

每把刀需要一个物品模型 JSON，否则在 JEI 和物品栏里会显示为透明。

在 assets/slb/models/item/ 目录下创建 <刀名>.json，内容只有一行：

{"parent": "slb:item/slb_blade"}

slb_blade.json 是 SLB 自带的模板，引用了 builtin/entity 父模型来触发 SlashBlade 的自定义 OBJ 渲染器。

如果不想手写，可以直接复制已有的文件（比如 yamazakura_aoi.json）改名。

第 4 步：加中文名

打开 assets/slb/lang/zh_cn.json，加一行：

{
  "item.slb.my_sword": "我的刀",
  "item.slb.my_sword.desc": "§b这是一把很厉害的刀"
}

英文同理，打开 en_us.json。

保存文件，压缩软件会问"是否更新到压缩包？"选是。搞定，进游戏就有了。

JSON 字段参考

properties（属性）

字段 类型 说明 示例
attack_base float 基础攻击力（一般 8~20） 12.0
max_damage int 锻造耐久上限 150
slash_art string 右键释放的必杀技 "slashblade:sakura_end"
sword_type string[] 剑类型 ["bewitched"]
special_effects string[] 挂载的特殊效果 ["slb:swift_edge"]

sword_type 可选值

值 效果
"bewitched" 妖刀（可成长）
"enchanted" 附魔光泽
"sealed" 封印刀（需解封）

常用 slash_art

值 效果
slashblade:drive_vertical 纵斩
slashblade:drive_horizontal 横斩
slashblade:wave_edge 剑气波
slashblade:circle_slash 回旋斩
slashblade:sakura_end 樱之终焉
slashblade:judgement_cut 审判切割

render（渲染）

字段 类型 说明 示例
model string OBJ 模型路径 "slb:model/xxx/model.obj"
texture string PNG 贴图路径 "slb:model/xxx/texture.png"
carry_type string 携带方式 "katana"
summon_sword_color hex 刀光颜色（16 进制） 0xFFFF69B4

常用 carry_type

值 效果
"katana" 别在腰间（默认）
"ninja" 背在背后
"pso2" 悬浮在身旁

enchantments（附魔）

[
  { "id": "minecraft:sharpness", "lvl": 5 },
  { "id": "minecraft:unbreaking", "lvl": 3 }
]

语言文件

{
  "item.slb.<刀名>": "刀的名称",
  "item.slb.<刀名>.desc": "§b描述文字"
}

配置文件

首次运行后生成 config/slb.json5，可用记事本修改：

{
  "damage": {
    "globalDamageMultiplier": 1.0   // 全局伤害倍率，0.1~10.0
  },
  "sword_type": {
    "enableBewitchedByDefault": true  // 默认是否妖刀
  },
  "debug": {
    "logDiscoveredBlades": true       // 是否在日志列出所有刀
  }
}

改完重启游戏生效。

特殊效果（SE）系统

SLB 通过 slb_ses.json 为你的刀增加了特殊效果系统——每把刀可以挂载被动特效，比如吸血、点燃敌人、加移动速度等。所有 SE 由 JSON 定义，无需修改 Java 代码。

为刀添加 SE

在刀 JSON 的 properties 里加上 special_effects 数组：

"properties": {
  "attack_base": 12.0,
  "special_effects": ["slb:swift_edge", "slb:blood_edge"]
}

一把刀可以同时挂载多个 SE，效果叠加。如果玩家等级没达到 SE 的等级要求，该 SE 不生效。

自定义 SE

打开 SLB.jar，编辑 slb_ses.json，在 ses 对象里加一段：

"我的绿光闪闪": {
  "requestLevel": 5,
  "isCopiable": true,
  "isRemovable": true,
  "effects": [
    { "type": "potion", "id": "minecraft:regeneration", "amplifier": 1, "trigger": "held" },
    { "type": "potion", "id": "minecraft:resistance", "amplifier": 0, "trigger": "held" }
  ]
}

保存后，在刀 JSON 里写 "special_effects": ["slb:我的绿光闪闪"] 即可。

惩罚效果（Penalty）

SE 可以加一个 penalty 字段，当玩家等级不足时自动受到负面效果。格式与 effects 一致：

"swift_edge": {
  "requestLevel": 8,
  "effects": [
    { "type": "potion", "id": "minecraft:speed", "trigger": "held" }
  ],
  "penalty": [
    { "type": "potion", "id": "minecraft:slowness", "trigger": "held" }
  ]
}

低于 8 级的玩家手持这把刀时会获得缓慢效果。

penalty 专用效果类型

在普通效果类型（potion）之外，penalty 还支持以下独占类型：

type 效果 参数
potion 对玩家施加负面药水 id = 状态ID
amplifier = 等级，默认 0
duration = 持续刻数，默认 100
trigger = held / hit
self_ignite 点燃玩家自身 seconds = 燃烧秒数，默认 3
interval_ticks = 触发间隔（20=1秒），默认每次
trigger = held
self_lightning 雷劈玩家自身 interval_ticks = 触发间隔
trigger = held
self_damage 攻击时自伤（魔法伤害） amount = 伤害量，默认 1.0
trigger = hit
block_ps 阻止获得荣耀之魂 trigger = ps

interval_ticks：设置间隔刻数避免每 tick 重复触发。如 interval_ticks: 60 = 每 3 秒触发一次。 block_ps 仅在 trigger: "ps" 时有效。

原子效果类型参考

每个效果的 JSON 参数说明如下。加粗 = 必填，其余可选（不填则用默认值）。

type 效果 参数详解
potion 给自己加状态 id = 状态ID（如 minecraft:speed）
amplifier = 等级，默认 0
duration = 持续刻数（20刻=1秒），默认 100
potion_target 给敌人加状态 id = 状态ID
amplifier = 等级，默认 0
duration = 持续刻数，默认 100
chance = 触发概率 0~1，默认 1.0
fire_target 点燃敌人 seconds = 燃烧秒数，默认 5
chance = 触发概率 0~1，默认 1.0
damage 额外伤害 ratio = 伤害比例（0.3=基础伤害的30%），默认 0
condition = 触发条件，默认 always
chance = 触发概率 0~1，默认 1.0
lightning 召唤闪电 chance = 触发概率 0~1，默认 1.0
double_in_rain = 雨天概率翻倍，默认 false
life_steal 吸血 ratio = 吸血比例（0.03=造成伤害的3%），默认 0.03
heal_on_kill 击杀回血 amount = 回复血量，默认 2.0
double_strike 概率二连击 chance = 触发概率 0~1，默认 1.0
ratio = 二连击伤害比例（0.6=基础伤害的60%），默认 0.6
aoe_potion 范围状态 id = 状态ID
amplifier = 等级，默认 0
duration = 持续刻数，默认 60
radius = 范围半径，默认 5.0
void_tear 虚空撕裂（真实伤害） chance = 触发概率 0~1，默认 1.0
damage_ratio = 真实伤害倍率（2.0=基础伤害×2），默认 2.0
void_explosion 虚空爆炸（范围真实伤害） chance = 触发概率 0~1，默认 1.0
damage_ratio = 伤害倍率，默认 0.8
radius = 爆炸半径，默认 3.0
sonar_pulse 声呐脉冲（透视发光） range = 探测范围，默认 15.0
duration = 发光持续刻数，默认 100
proud_soul_mult 荣耀之魂获取倍率 multiplier = 倍率（1.5=获取量×1.5），默认 1.5
kill_count_mult 击杀计数获取倍率 multiplier = 倍率，默认 1.5
explosion_break 刀损坏时爆炸 damage_ratio = 伤害倍率，默认 1.0
power = 爆炸威力，默认 3.0
radius = 伤害范围，默认 4.0

提示：状态ID（id）可参考 [Minecraft 状态效果列表](https://minecraft.fandom.com/zh/wiki/%E7%8A%B6%E6%80%81%E6%95%88%E6%9E%9C)，如 minecraft:speed（速度）、minecraft:strength（力量）、minecraft:regeneration（再生）、minecraft:resistance（抗性）、minecraft:absorption（伤害吸收）等。

触发时机（trigger）

值 说明
held 手持刀时每 tick
hit 击中目标时（默认）
slashart 发动 SA 时
kill 击杀时
ps 获得荣耀之魂时

条件判断（condition，仅 damage 类型可用）

只在 type: "damage" 中有效，其他效果类型不支持此参数。

值 效果
always 总是触发（默认）
target_on_fire 目标燃烧时
target_frozen 目标冰冻时
full_health 目标满血时

组合示例

"吸血+燃烧+加速" SE：

"血火双刃": {
  "requestLevel": 20,
  "effects": [
    { "type": "life_steal", "ratio": 0.05, "trigger": "hit" },
    { "type": "fire_target", "seconds": 3, "chance": 0.5, "trigger": "hit" },
    { "type": "potion", "id": "minecraft:speed", "amplifier": 1, "trigger": "held" }
  ]
}

常见问题

游戏崩溃，提示 No key properties

原因： JSON 里 properties 拼写错误。检查是否写成了 proprties 或 propreties。

游戏里没有 SLB 的刀

SLB 是一个模组框架，本身不附带成品刀。需要你自己添加刀 JSON 和模型文件。参考上面的"四步加一把刀"章节。

刀显示为紫黑方块

原因： 模型或贴图路径不对。检查 JSON 里的 model 和 texture 路径是否跟你放文件的位置一致。

刀在 JEI 或物品栏里是透明的

原因： 缺少物品模型 JSON 文件。

每把刀都需要一个 assets/slb/models/item/<刀名>.json，内容为 {"parent": "slb:item/slb_blade"}。没有这个文件，Minecraft 无法知道怎么渲染这个物品，就显示为透明。参考上面的"第 3 步：添加物品模型"。

所有刀伤害太低 / 太高

改 config/slb.json5 里的 globalDamageMultiplier，2.0=两倍，0.5=一半。

游戏崩溃，提示 Not a string: null

原因： JSON 里某个字段应该填字符串，但写成了 null 或漏掉了。最常见于 render 段的路径：

❌ 错误 — model 字段为空
"render": {
    "model": null,       // ← 应该写 "slb:model/xxx/model.obj"
    "texture": null      // ← 应该写 "slb:model/xxx/texture.png"
}

✅ 正确
"render": {
    "model": "slb:model/example_blank/model.obj",
    "texture": "slb:model/example_blank/texture.png"
}

刀名（name 字段）、技能名（slash_art）、SE ID 等也都是字符串，不能写 null 或漏掉。

JSON 格式检查清单

修改 JSON 文件后如果游戏崩溃，最可能的原因是格式写错了。JSON 对格式要求非常严格，差一个逗号都会崩。对照以下清单检查：

❌ 常见错误 & ✅ 正确写法

# 错误写法 问题 正确写法
1 "attack_base": 12.0,
"max_damage": 200 ← 最后一个属性后面有逗号 		尾随逗号（trailing comma） "attack_base": 12.0,
"max_damage": 200 ← 去掉末尾逗号
2 "attack_base": 12.0
"max_damage": 200 ← 两行之间没逗号 		缺少逗号 "attack_base": 12.0,
"max_damage": 200
3 'name': 'slb:my_sword' 用了单引号，JSON 必须双引号 "name": "slb:my_sword"
4 name: "slb:my_sword" key 没加引号 "name": "slb:my_sword"
5 "max_damage": "200" 数字写了引号（成了字符串） "max_damage": 200
6 "attack_base": 12,0 逗号当小数点（应该是点） "attack_base": 12.0
7 "id": "minecraft:sharpness",
"lvl": 5, ← 数组最后一项有逗号		 数组尾随逗号 "id": "minecraft:sharpness",
"lvl": 5 ← 去掉逗号
8 "sword_type": "bewitched" 本应是数组，写成字符串 "sword_type": ["bewitched"]
9 "model": "slb:model\my_sword\model.obj" 用了反斜杠 \，应该用 / "model": "slb:model/my_sword/model.obj"
10 // 这是一把刀 写在 JSON 中间 JSON 标准不支持注释 删除注释（json5 支持但 blade JSON 不是 json5）
11 漏了 { 或 }，或多了 } 花括号不配对 数一下 { 和 } 数量是否相等
12 "slash_art": slashblade:drive_vertical 字符串没加引号 "slash_art": "slashblade:drive_vertical"

自检步骤

修改完 JSON 后，打开 [JSONLint](https://jsonlint.com/) 之类的在线校验工具，把 JSON 贴进去检查：

  1. ✅ 所有 key 和字符串值都用双引号
  2. ✅ 每行属性末尾有逗号（最后一行不要逗号）
  3. ✅ { 和 }、[ 和 ] 数量配对
  4. ✅ 路径用正斜杠 /，不是反斜杠
  5. ✅ 数字不加引号，字符串必须加引号

参考模板 _example_blank.json.example

SLB 自带一个 _example_blank.json.example 文件作为格式参考。后缀是 .json.example，不是 .json，所以 SlashBlade 不会加载它，也就不会因为缺少模型文件而崩溃。

想用这把刀时，把文件名改成 _example_blank.json，然后把 model.obj 和 texture.png 放到 assets/slb/model/example_blank/ 目录下即可。

许可

All Rights Reserved. 仅供学习交流使用。

Clone this wiki locally