hytale-gravity-flip/SHOWCASE.md

Hytale Gravity Flip

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

Click to watch on YouTube

---

Screenshots

---

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-<version>-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 <name>	Creates a region from the caller's current wand selection.
/gravityflip list	Prints every registered region with coords and enabled state.
/gravityflip show <name>	Highlights a region's outline for quick visual lookup.
/gravityflip remove <name>	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<T> 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

# Build the plugin jar
./gradlew shadowJar

# Copy to your Hytale server
cp build/libs/MythlaneGravityFlip-*-all.jar "<HytaleServer>/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

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

Plugin references: inspired by the structure of VotePipe and the myth_* Hytale plugin family (Kotlin DSL scaffolding, CamelCase manifests, gradle.properties conventions).