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.

> 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 custom enchantments for power, range, spread, explosions and speed.*

---

## 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.

### 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** |
| Mod loader | **Fabric Loader 0.19.5+** |
| Dependency | **Fabric API** |
| Java | **25** |
| Side | Client **and** server (server-authoritative damage) |

## Installation

1. Install Fabric Loader for Minecraft 26.3.
2. Drop [Fabric API](https://modrinth.com/mod/fabric-api) into `mods/`.
3. Drop the Sword Qi jar into `mods/`.
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`.