Sword Qi

# 重大更新，剑鞘加入！

# Major Update: The Scabbard Is Here!

> 版本区间：**1.3.2 → 2.0.0（含 2.0.0 之后的修复）** ｜ Version range: **1.3.2 → 2.0.0 (plus post-2.0.0 fixes)**

---

## 1.4.0 — 剑鞘系统上线 ｜ The Scabbard System

### 中文

**新增物品：剑鞘**

- 合成：皮革 + 木板 + 铁锭（见游戏内配方书）｜耐久 **2500**，放在**副手**使用。
- 主手持剑、副手持鞘，按 **R** 收剑入鞘（约 **0.7 秒**动画），再按 R 拔剑。
- 收剑动画期间**无法攻击**；主手物品被丢弃 / 切换 / 受伤时自动复位。
- 入鞘后**第三人称主手剑消失**（纯视觉效果，物品栏完全不受影响）。
- 每次释放剑气消耗剑鞘 **1 点耐久**，原版耐久附魔与经验修补正常生效。

**长按 Q 蓄力**

- 入鞘后**长按 Q** 蓄力：移动速度降到 **5%**，脚下显示**三圈旋转的风粒子**（锥形，模拟气流）。
- 每 **1 秒**升一阶，最多 **3 阶**；满 **6 秒**自动射出。
- 每升一阶：周围爆发少量**彩色粒子**（每阶颜色不同）+ 音效提示。
- 蓄力中切换 / 丢弃物品 / 受到伤害都会**打断**蓄力。
- 松开发射**竖向**剑气，伤害为普通剑气的 **130% / 160% / 200%**；特效等级按**蓄力后的伤害**重新计算，所以满蓄的剑气非常大。
- 发出后自动恢复持剑状态。

**两个新附魔**

| 附魔 | 最高等级 | 效果 |
|---|---|---|
| **蓄势**（剑鞘专用） | 3 | 满级蓄力速度 **+50%** |
| **玉碎**（宝藏附魔，仅远古城市战利品） | 1 | 满蓄造成 **500%** 伤害，并消耗剑 **1500 点耐久（无视耐久附魔）** |

- 玉碎的出现概率与**迅捷潜行**相当，只从**远古城市**的箱子里开出。

**其他**

- 剑鞘与 Q 键均为**可改键位**，出现在「选项 → 控制 → 游戏」分类里。

### English

**New item: Scabbard**

- Crafted from leather + planks + iron ingot; **2500 durability**, used in the **off hand**.
- Sword in main hand + scabbard in off hand: press **R** to sheath (~**0.7 s** animation), press R again to draw.
- You **cannot attack** while sheathing; dropping/switching the main-hand item or taking damage resets the state.
- While sheathed the main-hand sword is **hidden in third person** — purely visual, your inventory is untouched.
- Each shot costs the scabbard **1 durability**; Unbreaking and Mending work normally.

**Hold Q to charge**

- While sheathed, **hold Q**: movement speed drops to **5%** and three rings of spinning wind particles form a cone under your feet.
- One stage per **1 second**, up to **3 stages**; **auto-fires after 6 s**.
- On each stage-up: a burst of **coloured particles** (a different colour per stage) plus a sound cue.
- Switching or dropping an item, or taking damage, **interrupts** the charge.
- Release to fire a **vertical** blade at **130% / 160% / 200%** of the normal damage; the visual tier is recalculated from the charged damage, so a full charge looks huge.
- You return to the drawn state after firing.

**Two new enchantments**

| Enchantment | Max | Effect |
|---|---|---|
| **Charged Momentum** (scabbard only) | 3 | **+50%** charge speed at max level |
| **Jade Shatter** (treasure, ancient city chests only) | 1 | Full charge deals **500%** damage and costs the sword **1500 durability** (ignores Unbreaking) |

- Jade Shatter is about as rare as Swift Sneak and only appears in **ancient city** chests.

**Misc**

- Both the qi key and the sheathe key are rebindable under **Options → Controls → Gameplay**.

---

## 1.4.1 — 数值与视觉微调 ｜ Number & Visual Tweaks

**中文**

- 玉碎伤害 **300% → 500%**。
- 蓄力风环**固定为白色**，不再随阶段变色；只有**升阶瞬间**才出现彩色粒子。

**English**

- Jade Shatter damage **300% → 500%**.
- The charge wind rings are now **always white** and no longer change colour per stage; coloured particles appear **only on stage-up**.

---

## 1.4.2 — 收剑与 Q 键 ｜ Sheathing & the Q Key

**中文**

- 修复：入鞘后主手剑在第一人称仍然显示。
- 修复：入鞘状态下长按 Q 会把剑丢出去（现在 Q 完全不会丢剑；想丢物品请用 **Shift + Q**）。

**English**

- Fixed: the sheathed sword was still visible in first person.
- Fixed: holding Q while sheathed could drop the sword (Q now never drops it — use **Shift + Q** to actually drop items).

---

## 1.5.0 — 手感与展示 ｜ Feel & Presentation

**中文**

- 剑鞘加入**创造模式物品栏**。
- 蓄力时镜头**轻微拉近**（FOV 变化），竖斩与十字斩各有独立粒子表现。
- 剑鞘有了**手持时的显示模型**，并作为 **3D 模型挂在腰间**，不会再出现「手持 2D、入鞘突然变 3D」的突兀感。

**English**

- The scabbard now appears in the **creative inventory**.
- Charging slightly **zooms the camera** (FOV change); vertical and cross slashes each got their own particle treatment.
- The scabbard got a proper **held display model** and is rendered as a **3D model worn at the waist**, so it no longer pops from a flat 2D item into a 3D model when you sheath.

---

## 1.6.x — 腰间剑鞘定型 ｜ Waist Scabbard Refined

**中文**

- 腰间剑鞘重做：**鞘口朝前上方 30°**、鞘身向后下延伸、**梯形鞘尾**，加金属包边与银箍；尺寸放大、加长。
- 入鞘时在鞘口**接上剑柄**（护手 + 握把 + 剑首），剑鞘本体位置不变。
- 蓄力阶段倍率调整为 **130% / 160% / 200%**。
- 玉碎改为**剑鞘副手槽**的附魔（此前误放在剑上）。
- 修复 `fabric.mod.json` 里版本号不刷新的构建问题。

**English**

- Waist scabbard rebuilt: the **mouth points 30° forward-up**, the body runs back-down, with a **trapezoid tip**, metal rim and silver band; scaled up and lengthened.
- When sheathed, a **hilt** (guard + grip + pommel) is attached at the mouth while the scabbard itself stays put.
- Charge stage multipliers adjusted to **130% / 160% / 200%**.
- Jade Shatter moved to the **scabbard's off-hand slot** enchantment (it was wrongly on the sword).
- Fixed the build issue where the version inside `fabric.mod.json` was not refreshed.

---

## 1.7.0 – 1.7.2 — 越肩视角兼容 ｜ Shoulder-Surfing Compatibility

**中文**

- 兼容 **Shoulder Surfing Reloaded** 等自由视角：蓄力时**身体与头部对准准心方向**，不再出现「看着这边、剑气朝那边」。
- 蓄力期间**瞄准角度随网络包上传**，服务端按你实际瞄准的方向生成剑气（含 R 键蓄力释放）。
- 修复蓄力时**头部 180° 扭曲**、头部转速与视角不同步、发射后身体瞬移转向等问题；改为平滑混合（blend）。

**English**

- Compatible with **Shoulder Surfing Reloaded** and other free-look setups: while charging, the **body and head face the crosshair**, so qi no longer flies somewhere else than where you look.
- The **aim yaw/pitch is sent with the packet**, so the server spawns the slash exactly along your aim (including charged release with R).
- Fixed the **head twisting 180°** while charging, the head not matching camera speed, and the body snapping around after firing; rotations are now smoothly blended.

---

## 2.0.0 — 多版本支持 ｜ Multi-Version Support

**中文**

- 现在同时支持 **Minecraft 26.3 / 1.21.11 / 1.20.1**，功能一致：剑气、十字斩、剑鞘、蓄力、五个附魔 + 蓄势/玉碎、史诗特效。
- 产物文件名带上游戏版本：`swordqi-2.0.0-fabric-26.3.jar`、`-fabric-1.21.11.jar`、`-fabric-1.20.1.jar`。
- 1.20.1 分支按那个年代的 API 重新实现：附魔为 Java 注册、渲染为立即模式、战利品用 NBT 写入，并实测远古城市开箱概率与 26.3 一致。

**English**

- Now supports **Minecraft 26.3 / 1.21.11 / 1.20.1** with identical features: qi slashes, cross slash, scabbard, charging, the five enchantments plus Charged Momentum / Jade Shatter, and the epic tiers.
- Jar filenames now carry the game version: `swordqi-2.0.0-fabric-26.3.jar`, `-fabric-1.21.11.jar`, `-fabric-1.20.1.jar`.
- The 1.20.1 branch is re-implemented against that era's API: Java-registered enchantments, immediate-mode rendering and NBT loot injection; ancient-city drop rates were verified to match 26.3.

---

## 2.0.0 之后的修复 ｜ Post-2.0.0 Fixes

**中文**

- **Q 键彻底不再丢剑**：原版 `handleKeybinds()` 在丢弃成功后会顺手挥一次手，之前只拦丢弃会变成「一直挥手」；现在两者都拦掉。
- 1.20.1 上模组键位与原版丢弃同绑 Q 时可能收不到按键，已加同键识别兜底。
- 1.20.1 蓄力时**视角异常放大**修复。
- 1.20.1 **剑鞘歪斜**修复（几何与 26.3 对齐）。
- 1.20.1 修复第三人称手上剑鞘/剑重复显示。

**English**

- **Q truly never drops the sword now**: vanilla's `handleKeybinds()` swings the arm after a successful drop, so suppressing only the drop turned holding Q into endless swinging; both are suppressed now.
- On 1.20.1, when the mod key and vanilla drop were both bound to Q the press could be missed — added a same-key fallback.
- Fixed the **camera zoom blowing up** while charging on 1.20.1.
- Fixed the **crooked waist scabbard** on 1.20.1 (geometry aligned with 26.3).
- Fixed duplicated scabbard/sword rendering in the hand on 1.20.1.

---

## 附：五个剑气附魔速查 ｜ Appendix: The Five Qi Enchantments

| 附魔 / Enchantment | 最高 / Max | 效果 / Effect |
|---|---|---|
| 锐芒 / Keen Qi | 5 | 每级 +20% 剑气伤害，满级 150% 剑伤 · +20% qi damage per level, 150% at max |
| 长溯 / Long Trace | 4 | 每级 +25% 飞行距离 · +25% flight distance per level |
| 分浪 / Split Wave | 1 | 左右 ±20° 各再来一道 · two extra slashes at ±20° |
| 剑意 / Sword Intent | 3 | 命中爆炸，半径 1.3 / 2.7 / 4 格，50% 伤害，不破坏地形 · hit detonates, 1.3 / 2.7 / 4 blocks, 50% damage, no terrain damage |
| 掠影 / Swift Shadow | 3 | 每级 +33% 飞行速度（满级翻倍）+ 更密拖尾 · +33% speed per level (double at max) and a denser trail |