Sword Qi

# Sword Qi

**Sword Qi** turns every sword into a ranged weapon. Press **Q** while holding any sword to unleash a crescent blade of energy that flies forward and cuts down whatever it hits. Craft a **Scabbard**, sheathe your sword, and **hold Q to charge** a far larger vertical slash.

> Short summary (for the one-line field): *Press Q with any sword to fire a glowing crescent of sword qi — tiered by damage, with five qi enchantments. Sheathe it in a scabbard, charge up, and release a giant vertical blade with two more scabbard enchantments.*

---

## Features

### Fire sword qi with Q

* Works with **any sword** — wooden to netherite, including modded swords tagged `#minecraft:swords`.
* **Q never drops your sword**: the mod consumes the key press before vanilla's drop action runs. Hold **Shift + Q** if you actually want to drop the item.
* **3 second cooldown**, and each slash costs **3 durability** (Unbreaking applies as usual).
* **Cannot fire while blocking with a shield** — no blocks, no cooldown, no durability spent.
* The player swings their arm and a sweep sound plays, so it reads correctly in third person and multiplayer.

### Damage and range scale with your sword

* Qi damage = **50% of the sword's attack damage**, increased by the *Keen Qi* enchantment.
* Flight distance = **3 blocks + 1 block per point of qi damage** (so a stronger sword also reaches further).
* The blade is a single target projectile: it hits one entity, deals damage, applies knockback, and vanishes. It also dissipates on impact with a solid block.

### Appearance

* A translucent crescent rendered as a flat horizontal sheet: seen **from above or below it is a clear arc**, seen **from the front or back it is a thin sliver** of light.
* Colour and size are tiered by damage: **cyan → blue → purple → gold → crimson → neon → cold white → prismatic**.
* A light particle trail follows the blade so you can track its flight, and it keeps rendering out to 128 blocks.

### Epic tiers

At **50 / 100 / 200 / 500** qi damage the slash unlocks progressively grander effects. The particle budget stays flat, so an epic slash costs the same to render as a normal one:

| Qi damage | Tier | Added effect |
|---|---|---|
| 50+ | Crimson | A large halo at the blade's core, plus end-rod sparks |
| 100+ | Neon | A rotating ring of dust around the flight axis |
| 200+ | Cold white | Periodic colour flash along the blade |
| 500+ | Prismatic | A sonic-boom ripple and a cycling rainbow accent |

From the **gold tier upward** (10+ damage) a few extra accent particles in the blade's own hue glitter around it — purely cosmetic, no extra cost.

### Dual wielding: cross slash

Hold a sword in **both hands** and the slash becomes a **cross slash** — two crescent sheets crossing along the flight axis.

| Property | Source |
|---|---|
| Size, colour, visual | **Main hand only** |
| Enchantment effects (Sword Intent, Split Wave, Swift Shadow) | **Main hand only** |
| Flight distance | **Main hand only** |
| Damage | **Main hand qi damage + 50% of off-hand qi damage** |

Durability and cooldown are still resolved once, for the main-hand sword.

### Scabbard: sheath, charge, release

Craft a **Scabbard** (leather + planks + iron ingot) and hold it in your **off hand**. With a sword in your main hand press **R** to sheath it (0.7 s animation), press **R** again to draw. While sheathed the main hand sword is hidden in third person — this is purely visual, your inventory is untouched.

* **Hold Q to charge** while sheathed: you move at 5% speed, three rings of wind particles spin under your feet, and the charge steps up one stage per second (max 3 stages, auto-fires after 6 s).
* Release Q to fire a **vertical** qi blade. Stage damage is **130% / 160% / 200%** of the normal slash; visual tier is recalculated from the charged damage, so a charged slash looks much bigger.
* Switching or dropping an item, or taking damage, cancels the charge. Firing returns you to the drawn state.
* The scabbard has **2500 durability** and loses **1 point per shot**; Unbreaking and Mending work normally.
* Both the qi key and the sheathe key are normal key bindings — rebind them in **Options → Controls**.

### Two more enchantments

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

Jade Shatter drops from ancient city chests at roughly the rarity of Swift Sneak (1 in 6 rolls of its pool).
### Works with vanilla sword enchantments

Damage is resolved through the vanilla data-driven enchantment pipeline, so **Sharpness**, **Fire Aspect**, **Smite** and **Bane of Arthropods** all apply to qi hits exactly as they would to a melee swing — including setting the target on fire and bonus damage against undead or arthropods.

---

## Enchantments

All five enchantments apply to swords, occupy the main-hand slot, and can appear at an enchanting table (they are part of `#minecraft:non_treasure`).

| Enchantment | Max | Weight | Effect |
|---|---|---|---|
| **Keen Qi** | 5 | 10 | +20% qi damage per level, based on sword damage. Level 5 = **150% of sword damage**. |
| **Long Trace** | 4 | 8 | +25% flight distance per level. |
| **Split Wave** | 1 | 4 | Fires two additional slashes, ±20° to the left and right. |
| **Sword Intent** | 3 | 5 | The hit detonates: 50% of the qi damage to everything in a radius (1.3 / 2.7 / 4 blocks). No block damage, no knockback from the blast. **Mutually exclusive with Split Wave.** |
| **Swift Shadow** | 3 | 6 | +33% flight speed per level (double speed at level 3) and a denser particle trail. |

At level 3, *Sword Intent* covers a radius of 4 blocks — the same blast radius as TNT, but it only hurts entities and leaves the terrain intact.

---

## Requirements

| | |
|---|---|
| Minecraft | **26.3** (separate jars for **1.21.11** and **1.20.1**) |
| Mod loader | **Fabric Loader 0.19.5+** |
| Dependency | **Fabric API** |
| Java | **25** (21 for 1.21.11, 17 for 1.20.1) |
| Side | Client **and** server (server-authoritative damage) |

## Installation

1. Install Fabric Loader for your Minecraft version.
2. Drop [Fabric API](https://modrinth.com/mod/fabric-api) into `mods/`.
3. Pick the jar matching your game version and drop it into `mods/`:
   * `swordqi-2.0.0-fabric-26.3.jar`
   * `swordqi-2.0.0-fabric-1.21.11.jar`
   * `swordqi-2.0.0-fabric-1.20.1.jar`
4. Launch the game — no configuration needed.

## Trying it out

Give yourself a sword and fire away:

```mcfunction
/give @s netherite_sword[enchantments={"swordqi:qi_sharpness":5,"swordqi:qi_reach":4,"swordqi:qi_swift":3}]
```

Dual-wield cross slash:

```mcfunction
/give @s netherite_sword[enchantments={"swordqi:qi_sharpness":5}]
/give @s diamond_sword[enchantments={"swordqi:qi_sharpness":3}]
```

Sword Intent explosion (incompatible with Split Wave):

```mcfunction
/give @s diamond_sword[enchantments={"swordqi:qi_intent":3,"swordqi:qi_reach":4}]
```

---

## Notes

* The qi blade is intentionally paper-thin when viewed head-on — it is meant to look like a horizontal arc cutting through the air.
* Everything is data-driven where Minecraft allows it: the enchantments are datapack JSON files, so other datapacks can retune or disable them.
* Mod id: `swordqi`.