diff --git a/SHOWCASE.md b/SHOWCASE.md new file mode 100644 index 0000000..17dbf11 --- /dev/null +++ b/SHOWCASE.md @@ -0,0 +1,144 @@ +# Hytale Gravity Flip + +![Java 25](https://img.shields.io/badge/Java-25-orange) +![Gradle](https://img.shields.io/badge/Gradle-Shadow-green) +![Hytale](https://img.shields.io/badge/Hytale-2026.03.26-blueviolet) +![Status](https://img.shields.io/badge/v1-shipped-brightgreen) + +> A Hytale server plugin that lets builders create **inverted-gravity zones** entirely in-game — no code, no restarts. Define a region with a wand, name it, and every player, NPC, or item inside immediately flips upward. + +--- + +## Video Showcase + +[![Gravity Flip Demo](https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg)](https://www.youtube.com/watch?v=VIDEO_ID) + +*Click to watch on YouTube* + +--- + +## Screenshots + + + +![Wand selection on two corners](docs/screenshots/01-wand-selection.png) +![Defined region with cyan outline overlay](docs/screenshots/02-region-outline.png) +![Player walking on the ceiling](docs/screenshots/03-walk-on-ceiling.png) +![Items rising inside the fountain zone](docs/screenshots/04-item-fountain.png) +![Dense particle visualization](docs/screenshots/05-dense-particles.png) +![Showcase arena, wide shot](docs/screenshots/06-showcase-arena.png) + +--- + +## Features + +- **Six in-game subcommands** — `wand`, `define`, `list`, `show`, `remove`, `reload`. Full workflow without touching config files. +- **Per-UUID wand selection store** — each builder has their own pair of corners, survives rejoin. +- **Persistent regions** — all zones saved to `regions.json`, reloaded at boot. +- **Two visualization modes** — `Outline` (box wireframe) and `Particles` (volumetric fill) with configurable color, opacity, refresh rate, density. +- **Per-entity affect toggles** — target players only, items only, NPCs only, or any combination. +- **Configurable physics** — `VerticalForce` (lift strength) and `GracePeriodMs` (smooth entry transition) per region. +- **Optional fall-damage immunity** — turn off fall damage when leaving a zone so demos don't hurt. +- **Hot reload** — `/gravityflip reload` re-reads `regions.json` without restarting the server. +- **Tick-loop detection** — efficient AABB containment check each tick, scales to dozens of active regions. + +--- + +## Quick Start + +1. **Install** — drop `MythlaneGravityFlip--all.jar` into `Server/mods/` and start the server. +2. **Get the wand** — in-game, run `/gravityflip wand`. You receive the custom *Gravity Flip Wand* item. +3. **Pick two corners** — left-click block A (min corner), right-click block B (max corner). +4. **Name the region** — `/gravityflip define my_zone`. Gravity inverts inside the box immediately. + +--- + +## Command Reference + +| Command | Effect | +| ------------------------------- | ---------------------------------------------------------------------- | +| `/gravityflip wand` | Grants the *Gravity Flip Wand* item to the caller. | +| `/gravityflip define ` | Creates a region from the caller's current wand selection. | +| `/gravityflip list` | Prints every registered region with coords and enabled state. | +| `/gravityflip show ` | Highlights a region's outline for quick visual lookup. | +| `/gravityflip remove ` | Deletes a region from disk and memory. | +| `/gravityflip reload` | Re-reads `regions.json` without restarting the server. | + +--- + +## Technical Highlights + +- **Java 25** — modern pattern matching, records, sealed types. +- **Gradle Shadow** — single fat-jar output (`./gradlew shadowJar`). +- **Hytale plugin API** — integrates with `Config` for typed persistence, `Interaction.CODEC` for the custom wand behavior, and a custom item asset pack for the wand visual. +- **Pure-data selection store** — `WandSelectionStore` keyed by player UUID, testable without a live server. +- **Tick-driven detection** — per-tick AABB containment, entity-type gating, grace-period smoothing. +- **Codec-registered interactions** — wand left/right-click registered through `Interaction.CODEC` so the item reacts natively. + +--- + +## Showcase Regions + +These ship in the `regions.json` bundled with the dev server and cover every plugin capability. Spawn is at `(0, 81, 0)` on a superflat surface. + +| Region | Min | Max | What it demonstrates | +| -------------------------- | ---------------- | ----------------- | --------------------------------------------------------------- | +| `tutorial_walk_on_ceiling` | (10, 81, 10) | (15, 86, 15) | Baseline player-only flip with cyan outline. | +| `item_fountain` | (20, 80, 10) | (23, 100, 13) | Tall vertical zone, items only — drop stuff and watch it rise. | +| `mob_chamber` | (30, 81, 10) | (40, 89, 20) | NPC-only flip with red outline. | +| `full_chaos` | (-15, 81, 10) | (0, 91, 25) | Players + NPCs + items, purple particles. | +| `gentle_lift` | (-40, 80, -20) | (-20, 85, 0) | Soft `VerticalForce=0.05` — slow drift. | +| `strong_launch` | (-15, 80, -15) | (-10, 83, -10) | Aggressive `VerticalForce=0.3` — launch pad. | +| `grace_period_demo` | (15, 81, -20) | (23, 87, -12) | `GracePeriodMs=5000` — smooth fade-in. | +| `no_grace` | (25, 81, -20) | (33, 87, -12) | `GracePeriodMs=0` — instant flip, side-by-side comparison. | +| `fall_damage_off` | (40, 110, 0) | (50, 120, 10) | Elevated zone with `FallDamage=false` — safe exit. | +| `disabled_example` | (-30, 81, 0) | (-25, 86, 5) | `Enabled=false` — persisted but inert, proves state handling. | +| `showcase_arena` | (-80, 81, -80) | (-50, 96, -50) | 30×15×30 gold-outlined arena — hero shot for video. | +| `dense_particles` | (50, 81, 50) | (58, 89, 58) | `VisualParticleDensity=1.0` — maxed visual saturation. | + +--- + +## Installation + +```bash +# Build the plugin jar +./gradlew shadowJar + +# Copy to your Hytale server +cp build/libs/MythlaneGravityFlip-*-all.jar "/Server/mods/" + +# Restart the server — the plugin auto-registers its item, interactions, and tick listener. +``` + +On first boot the plugin creates `Server/mods/Mythlane_GravityFlip/regions.json`. Edit in-game via commands, or hand-edit the file and `/gravityflip reload`. + +--- + +## Development + +```bash +# Run the dev server (auto-deploys the shadow jar into the configured HYTALE_SERVER_DIR) +./gradlew devServer +``` + +Repository layout: + +``` +src/main/java/com/mythlane/gravityflip/ + plugin/ # Entry point, interaction + item registration + regions/ # Region model, store, JSON persistence + wand/ # Wand item, selection store, interaction handlers + command/ # /gravityflip subcommand implementations + tick/ # Per-tick AABB detection and physics application + visual/ # Outline + particle renderers +src/test/java/... # Pure-data unit tests (selection store, region codec, etc.) +docs/screenshots/ # Portfolio assets +``` + +--- + +## License / Credits + +Built by **[Mythlane](https://mythlane.com)**. + +Plugin references: inspired by the structure of VotePipe and the `myth_*` Hytale plugin family (Kotlin DSL scaffolding, CamelCase manifests, `gradle.properties` conventions). diff --git a/docs/screenshots/.gitkeep b/docs/screenshots/.gitkeep new file mode 100644 index 0000000..e69de29