# 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).