# Hytale ChainLightning Sceptre

A magical sceptre for **Hytale** that fires chain lightning at mobs — right-click a target and the bolt jumps to up to 5 nearby enemies within 8 blocks, dealing decreasing damage with every hop.

<p align="center">
  <img src="https://img.shields.io/badge/Java-25-orange" alt="Java 25"/>
  <img src="https://img.shields.io/badge/Gradle-Shadow-green" alt="Gradle Shadow"/>
  <img src="https://img.shields.io/badge/Hytale-2026.03.26-blueviolet" alt="Hytale 2026.03.26"/>
  <img src="https://img.shields.io/badge/status-proof--of--concept-yellow" alt="POC"/>
  <img src="https://img.shields.io/badge/license-TBD-lightgrey" alt="License"/>
</p>

---

## ⚠️ Proof of concept — and I need help

This is first and foremost a **proof of concept** I built to learn the Hytale Plugin API while it's still in early access. I'm a Java dev, **not a 3D / VFX artist** — I don't know how to author proper custom assets (models, particle systems, SFX). Everything visual here reuses **builtin Hytale assets**:

- The wand model is the builtin `Items/Weapons/Wand/Wood.blockymodel`
- The chain-hit particles use the builtin `Splash` system
- Sounds use the builtin `ISS_Weapons_Wand` set

→ The visuals are placeholder and the plugin is rough around the edges. **If you're a 3D artist, VFX artist, sound designer, or Hytale plugin dev and want to make this look great — please reach out.** Issues, PRs, or a quick email are all welcome.

---

## What Does It Do?

- **Right-click a mob**: chain lightning resolves, jumping up to **5 targets** within **8 blocks** of each previous hop.
- **Damage falls off per hop** (configurable in code, tested via JUnit).
- **Left-click**: normal attack (engine fallback — sceptre still works as a basic weapon).
- **4-second cooldown** between casts.

---

## Quick Start

1. Drop `hytale-chain-lightning-<version>.jar` into your server's `Plugins/` folder.
2. Boot the server.
3. Spawn the item with the standard Hytale `/item give` flow (item id `chain_lightning_sceptre`).
4. Equip, face a mob, **right-click**.

---

## Stack

- **Java 25** (records, sealed types, modern API).
- **Gradle 8 + Shadow** for the fat jar.
- **Hytale Plugin API** core (`Interaction`, `EntityEffect`, `ParticleUtil`, `EffectControllerComponent`).
- **JUnit 5** for the pure chain-resolution algorithm.

---

## How It Works

```
Player right-clicks mob
        │
        ▼
ChainLightningSceptreInteraction.firstRun(Secondary)
        │
        ├─ Cooldown gate (4s)
        ├─ HytalePlayerRayCaster   ──> primary target ref
        ├─ HytaleEntitySource      ──> nearby entity snapshot
        │
        ▼
ChainResolver.resolve()  (pure Java, JUnit-tested)
        │   BFS over hops, max 5 targets, max 8 blocks/hop
        ▼
ChainHit list
        │
        ├─ ChainDamageApplier.apply()      ──> dégressive damage per hop
        └─ HytaleVfxEmitter.playChainEffects()
                 ├─ ParticleUtil.spawnParticleEffect("Splash", pos)   (direct broadcast — bypasses client-side effect dedup)
                 └─ EffectControllerComponent.addEffect("Chain_Hit_Effect")  (blue tint, 0.05s)
```

The chain-resolver is decoupled from Hytale via small interfaces (`RayCaster`, `EntitySource`, `ChainEntity`), so the algorithm is unit-tested without a running server. Hytale-bound adapters live in `sceptre/`.

---

## Known Limitations

- **Splash particles sometimes silent on client** — server logs confirm `5/5` `SpawnParticleSystem` packets per cast every time, but the early-access Hytale renderer appears to throttle/cull duplicate `systemId` particles at nearby positions. Likely a client-side issue, can't fix from the plugin.
- **No custom model** — sceptre reuses the builtin wand. A real 3D model would help a lot.
- **No custom particle system** — `Splash` is functional but not *electric*. A proper arc/branch particle would sell the fantasy.
- **No custom SFX** — uses the generic wand sound set.

---

## Development

* JDK 25, Gradle, Hytale Plugin API (from https://maven.hytale.com/release), local dev server.
* Source: `src/main/java/com/mythlane/chainlightning/`
* Tests: `src/test/java/` (pure algorithm, no server needed).

### Building

```bash
./gradlew shadowJar     # fat jar
./gradlew test          # unit tests
```

---

## Help Wanted

Genuinely open to help. If any of these match you:

- **3D artist** — design and model a proper sceptre (`.blockymodel`).
- **VFX artist** — author an electric arc / branching lightning particle system that beats `Splash`.
- **Sound designer** — cast / hit / loop SFX.
- **Hytale plugin dev** — review the API usage, suggest better patterns, or pair on the splash-on-client mystery.

Open an issue, send a PR, or email **contact@mythlane.com**.

---

## Credits

Made by [Mythlane](https://mythlane.com)

---

## License

License to be decided. Ping contact@mythlane.com for questions.