From d67b8a76676c813792014c33025a7c32f2ee49ec Mon Sep 17 00:00:00 2001 From: kayjaydee Date: Tue, 28 Apr 2026 08:59:00 +0200 Subject: [PATCH] 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. --- README.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c37ff77 --- /dev/null +++ b/README.md @@ -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. + +

+ Java 25 + Gradle Shadow + Hytale 2026.03.26 + POC + License +

+ +--- + +## ⚠️ 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-.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.