kayjaydee
0b191c6504
- Portfolio-ready showcase with YouTube placeholder, screenshots gallery, feature list - Command reference table for the 6 subcommands - Inventory of 12 bundled showcase regions with coordinates and purpose - Install / development / license sections - docs/screenshots/.gitkeep to reserve asset location
145 lines
7.5 KiB
Markdown
145 lines
7.5 KiB
Markdown
# 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
|
||
|
||
[](https://www.youtube.com/watch?v=VIDEO_ID)
|
||
|
||
*Click to watch on YouTube*
|
||
|
||
---
|
||
|
||
## Screenshots
|
||
|
||
<!-- Replace with actual 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```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).
|