feat: add README.md for Hytale ChainLightning Sceptre plugin
- Introduced a comprehensive README.md detailing the ChainLightning Sceptre plugin for Hytale. - Included sections on functionality, quick start instructions, development setup, known limitations, and a call for collaboration. - Highlighted the proof of concept nature of the project and the need for visual and audio asset contributions. Build: README added successfully.
This commit is contained in:
@@ -0,0 +1,127 @@
|
|||||||
|
# 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.
|
||||||
Reference in New Issue
Block a user