# Hytale Gravity Flip
Gravity Flip lets you create anti-gravity regions on your Hytale server using a wand — no scripting, no file edits, no server restarts. Want to walk on the ceiling? Place two corners, name the region, and flip the world.
---
## What Does It Do?
- Mark a region in game with a wand tool.
- Instantly flips gravity *inside your box* for players, items, and/or mobs, depending on your config.
- Everything is persisted to disk, no fiddling with configs.
- Toggle regions, delete, teleport, etc., all via `/gravityflip` commands.
- Visualize with outlines or particles. Toggle between modes.
- Built for builders: no code, minimal ceremony.
---
## Quick Start
1. Copy `hytale-gravity-flip-.jar` into your server's `mods` folder.
2. Run your server.
3. Use `/gravityflip wand` in-game to get the Gravity Flip Wand.
4. Left-click a block (corner 1), right-click another (corner 2).
5. Run `/gravityflip define ` — done. Gravity now flips inside that box.
---
## Commands
All commands are subcommands of `/gravityflip`:
| Command | What it does |
| ------------------------------- | --------------------------------------------------------- |
| `/gravityflip wand` | Gives you the wand. |
| `/gravityflip define ` | Defines a region from your selection. |
| `/gravityflip list` | Lists all registered regions and their info. |
| `/gravityflip delete ` | Removes a region. |
| `/gravityflip toggle ` | Enables/disables a region. |
| `/gravityflip tp ` | Teleports you to a region's center. |
---
### How The Wand Works
- Left-click = set pos1
- Right-click = set pos2
- Each player gets their own selection — it sticks until changed/logged out.
- When both corners are set, run `/gravityflip define `
---
## Region Fields
Gravity Flip regions are saved as JSON. Each region needs a `Name` and a `Box` (AABB). The rest have defaults.
| Field | Type | Default | What it means |
|-------------------------|---------|-------------|-------------------------------------------------|
| Name | string | required | The name/id you use in commands. |
| Box | array | required | `{min: [x,y,z], max: [x,y,z]}` |
| Enabled | bool | true | If off, region does nothing. |
| FallDamage | bool | false | Keep vanilla fall damage? (usually off) |
| GracePeriodMs | int | 2500 | Smooths the gravity transition (ms). |
| VerticalForce | float | 0.1 | How strong the anti-grav is. |
| AffectPlayers | bool | true | Flip players? |
| AffectNpcs | bool | true | Flip mobs/NPCs? |
| AffectItems | bool | true | Flip dropped items? |
| VisualColor | string | #00FFFF | Outline/particle color. |
| VisualMode | string | Outline | Outline, Particles, or None. |
| VisualRefreshMs | int | 1000 | How often visuals are updated (ms). |
| VisualOpacity | float | 0.5 | Outline transparency (0–1) |
| VisualParticleId | string | Torch_Fire | Particle id for "Particles" mode. |
| VisualParticleDensity | float | 0.3 | Particle density along edges. |
---
## Visualization
- **Outline**: Wireframe box for editing and debugging.
- **Particles**: Edges emit particles.
- **None**: Go "invisible" for production/live use.
---
## The Region File
Sits at `Server/mods/Mythlane_GravityFlip/regions.json`. Changing regions via commands saves instantly. If you hand-edit, restart the server. First run always seeds a "demo" region.
---
## Prebuilt Regions (for dev/testing)
| Name | Min | Max | Purpose |
|----------------------|---------------|---------------|----------------------------------------|
| tutorial_walk_on_ceiling | (10,81,10) | (15,86,15) | Simple walk-on-ceiling, cyan outline |
| item_fountain | (20,80,10) | (23,100,13) | Items float up, for demos |
| mob_chamber | (30,81,10) | (40,89,20) | Mobs only, red outline |
| full_chaos | (-15,81,10) | (0,91,25) | Players, mobs, items — chaos, purple |
| gentle_lift | (-40,80,-20) | (-20,85,0) | Weak antigrav |
| strong_launch | (-15,80,-15) | (-10,83,-10) | Launch pad settings |
| grace_period_demo | (15,81,-20) | (23,87,-12) | Entry anim with grace period |
| no_grace | (25,81,-20) | (33,87,-12) | Instant flip, for comparison |
| fall_damage_off | (40,110,0) | (50,120,10) | Fall damage off, high up |
| disabled_example | (-30,81,0) | (-25,86,5) | Persisted but disabled |
| showcase_arena | (-80,81,-80) | (-50,96,-50) | 30x15x30 gold-outlined box |
| dense_particles | (50,81,50) | (58,89,58) | Ultra-dense particle effect |
---
## Installing
```bash
./gradlew shadowJar
cp build/libs/hytale-gravity-flip-*.jar /Server/mods/
# Restart your server
```
On first start, `/regions.json` is seeded with a demo region. Use the wand/commands to manage regions.
---
## Development
* Requires **JDK 25**, Gradle, Hytale Plugin API (from https://maven.hytale.com/release), and a dev server.
* Code lives in `src/main/java/com/mythlane/gravityflip/`
* Unit tests: pure-data logic is covered in `src/test/java/`
### Building
```bash
./gradlew shadowJar # Build the fat jar with gson relocation
./gradlew test # Run unit tests
```
For dev fast-deploy, see `copyJarToDevServer` gradle task.
### Extending
- New subcommand? Add a class, register in `GravityFlipCommand`.
- New wand interaction? Register in the plugin `setup()` and hook it in assets.
- New region field? Add to the codec; existing JSON will keep defaults.
---
## How It Works
```
Player/NPC/Item
|
v (checked every tick)
RegionTickLoop
| <---- Regions loaded from regions.json
GravityApplier + FallDamageGuard
|
region effect
Wand:
Player clicks -> WandSelectionStore -> define region -> registry saves to JSON
```
- Tightly integrated Hytale plugin — lifecycle hooks, asset registration, everything inside the jar.
- Tick loop: runs 10x/sec, checks if entities are in zones, flips gravity as needed.
- Threading: regions are snapshotted for fast concurrent reads.
- Plugin self-seeds demo region so you never boot to an empty world.
---
## Stack
- Java 25, modern features (records, sealed types, etc).
- Gradle 8 + shadowJar (Gson relocated out of the global space).
- Hytale Plugin API core (JavaPlugin, Config, Interaction.CODEC).
- JUnit 5 for testing data and codecs.
---
## Credits
Made by [Mythlane](https://mythlane.com). Plugin layout/modeling borrowed from our VotePipe and related plugins.
---
## License
License to be decided. Ping contact@mythlane.com for questions.