The Bloodharbour Ripper

# The Bloodharbour Ripper — Items, Abilities and Plans

## Short list of added items

- bone_skewer_skeleton
- bone_skewer_raw
- bone_skewer (the strongest variant)
- jaull_fish_vial (rare material)

---

## Item descriptions

### bone_skewer_skeleton
- The basic, lightweight version of the harpoon/dagger built from bone.
- Mechanics: can be thrown at range (behaves like a simple throw); deals 1 more damage than an iron sword.
- Durability: iron-level durability.
- Role: early-game / throw-and-recover; entry into the upgrade progression toward higher variants.

### bone_skewer_raw
- Mid-tier variant. Damage is comparable to a diamond sword +1.
- Mechanics: longer throw range (like a trident); on hit applies Slowness II for 2 seconds.
- Durability: diamond-level durability.
- Crafting: recipe requires `bone_skewer_skeleton` and a `jaull_fish_vial` (see recipe JSON files for details).

### bone_skewer
- The strongest variant; the end-point item in the progression.
- Damage: capped at 15 (nerfed to 15 damage in the current implementation).
- Additional on-hit effects: Slowness II for 4 seconds and an extended Witherite effect (duration increased — currently ~32s by default in code).
- Throw mechanics: same long-range throw as `bone_skewer_raw`, but with a faster projectile speed.
- Durability: netherite-level durability.
- Crafting: `bone_skewer_raw` in the center with 8 × `jaull_fish_vial` around it (shaped recipe).

### jaull_fish_vial
- A rare component used to upgrade skewers.
- Acquisition: can only be found in chests generated in Ancient Cities.
- Limit and chance: maximum 1 vial per Ancient City, with a 33% chance (configurable in code/data).

---

## Key mechanics / abilities

All mechanics are designed to create a coherent progression between the three skewer variants and add tactical options in PvE and PvP encounters.

### Throwing and returning the harpoon
- Throwing: the item remains "equipped" (does not disappear from the inventory). Its state is locked on a cooldown until the harpoon returns.
- Right-click while the harpoon is in flight: immediately initiates the harpoon's return to the player (if it is in flight) and sets a cooldown that lasts until the return completes. This prevents item duplication.
- When the harpoon returns and lands near the player, the item becomes usable again after the cooldown ends.
- Default trident sounds are removed/muted for our harpoons; only custom sounds are used (for example: `bone_skewer_charging`, `bone_skewer_release`, `bone_skewer_hit`, `bone_skewer_return`).

### Pulling (hook attraction)
- The harpoon can pull a hit mob toward the player.
- Pull strength scales with the skewer variant (higher variant → stronger pull).
- Strength is tuned so the mob can move almost directly to a position near the player (not past the player).

### Durability & speed
- Each skewer variant has material-based durability: skeleton = iron, raw = diamond, best = netherite.
- The top-tier skewer has increased projectile speed.

### Execution ("Death From Below")
- Activation: hold Shift to highlight a target (target highlight), then press the configured keybind (renamed to `Death From Below` — configurable in controls).
- Range: the highlight and execution range are separate from weapon throw range — execution range is based on the highlight radius.
- Indicator: an X appears under the targeted mob (custom pixel art; a larger X option is available).
- Execution condition: target must have less than 33% HP (configurable). Does not work on allies or players in the same team.
- Timing and delay: after pressing the key, an execution sound is played; after 0.65 seconds the actual execution occurs. There is a 5‑second cooldown after execution.
- Execution effect: ignores defenses (shields, armor reductions, etc.) and deals the maximum possible damage (i.e., instant kill if the HP condition is met). Execution yields double loot and double experience.
- Visual: sea-themed particles spawn at the target's death location, and the player is teleported to the target's position as part of the effect.

### Cooldowns and interaction locks
- Initiating harpoon return (right-click during flight) starts a cooldown that lasts until the harpoon returns — preventing immediate re-throws and duplication.
- Execution has a separate 5s cooldown.
- Abilities (dash / execution) are visible and usable only when the player is holding the appropriate skewer.

### Dash and player phantom
- Available only for the top-tier skewer (`bone_skewer`): dash becomes an ability while holding the item.
- Dash mechanics: on activation the player performs a fast dash; a ghost clone of the player (using the player's skin) is left at the starting location.
- Ghost behavior: after ~0.6s the ghost quickly returns to the player and merges/vanishes; anything between the player and the ghost during the return is stunned and damaged.
- Additionally: targets hit by the dash are prevented from attacking for a short duration.
- Visuals: particles plus a ghost model that uses the player's current skin (not the default Steve skin). The ghost spawns slightly behind the player (not in the camera view).
- Sounds: custom dash sound and dash-hit sound are played.

---

## Sounds and visuals
- Sound names are standardized (e.g., `bone_skewer_charging`, `bone_skewer_release`, `bone_skewer_hit`, `bone_skewer_return`, `bone_skewer_dash`, `bone_skewer_dash_hit`, `bone_skewer_execution`).
- Vanilla trident sounds are disabled for our harpoons; only custom sounds are used.
- Pose for charging: adjusted so the harpoon is held by the handle with the blade in front of the player. The flying harpoon combines dynamic rotation (direction of flight) with static correction (rotation + translation + scale) for a better angle and position.
- An X indicator appears under a highlighted target (size adjustable via resource settings).

---

## Configuration and keybinds
- Keybind `Death From Below` (execution) is configurable in the controls menu.
- Many values (effect durations, cooldowns, ranges, chance for `jaull_fish_vial` in Ancient City) are exposed via the mod configuration for easy tweaking.

---

## Technical notes and caveats
- Crafting recipes are registered as shaped recipes (data files in `data/*/recipes/`). If you don't see recipes in JEI or the recipe book, verify that the JSON files are valid and properly registered (use `minecraft:crafting_shaped` and correct item IDs).
- `jaull_fish_vial` is restricted to Ancient City loot: max 1 per city, 33% chance — these values are configurable.
- Execution ignores most defensive mechanics and is designed to be an instant-kill when the condition (<33% HP) is met. It does not affect allies or teammates.

---

## Development plans: boss "Pyke" and future additions
- Main plan: add a unique boss codenamed `Pyke` that ties into harpoon and execution mechanics:
- Pyke will feature pull attacks, teleportation mechanics, and resistances to raw execution (special patterns required for a true kill).
- The boss will be integrated into the mod's lore (dark waters, port legends) and drop unique items that further expand the `bone_skewer` progression.
- Planned fight: multi-phase encounter that leverages the player's skewers (Pyke reacts to thrown skewers/executions) and environmental mechanics (e.g., pulling sections of the arena, breaking bridges).