kayjaydee/hytale-gravity-flip
1
0
Fork 0
Code Issues Pull Requests Releases Activity
Files
2b23d87c805cc113812f9130f4b7d3ed36d84253
hytale-gravity-flip/README.md
T
kayjaydee 2b23d87c80 docs: update README.md for clarity and structure 
- Simplified project description and improved readability.
- Changed section titles for better organization (e.g., "Showcase" to "Demo").
- Reformatted screenshots into a markdown table for a cleaner layout.
- Enhanced the "What Does It Do?" section to clearly outline features.
- Streamlined the Quick Start and Commands sections for easier navigation.
2026-04-24 18:11:02 +02:00

211 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
<p align="center">
<img src="https://img.shields.io/badge/Java-25-orange" alt="Java 25"/>
<img src="https://img.shields.io/badge/Gradle-Shadow-green" alt="Gradle Shadow"/>
<img src="https://img.shields.io/badge/Hytale-2026.03.26-blueviolet" alt="Hytale 2026.03.26"/>
<img src="https://img.shields.io/badge/v1-shipped-brightgreen" alt="v1 shipped"/>
<img src="https://img.shields.io/badge/license-TBD-lightgrey" alt="License"/>
</p>
---
### Demo
<!-- Replace VIDEO_ID with the YouTube video id once uploaded -->
<p align="center">
<a href="https://www.youtube.com/watch?v=VIDEO_ID">
<img src="https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg" alt="Gravity Flip — video demo" width="720"/>
</a>
</p>
<p align="center"><sub>Click to watch</sub></p>
#### Screenshots
| ![](docs/screenshots/01-wand-selection.png) | ![](docs/screenshots/02-region-outline.png) | ![](docs/screenshots/03-walk-on-ceiling.png) |
| --- | --- | --- |
| ![](docs/screenshots/04-item-fountain.png) | ![](docs/screenshots/05-dense-particles.png) | ![](docs/screenshots/06-showcase-arena.png) |
---
## 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-<version>.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 <region_name>` — 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 <name>` | Defines a region from your selection. |
| `/gravityflip list` | Lists all registered regions and their info. |
| `/gravityflip delete <name>` | Removes a region. |
| `/gravityflip toggle <name>` | Enables/disables a region. |
| `/gravityflip tp <name>` | 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 <name>`
---
## 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 <HytaleServer>/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 socials@mythlane.com for questions.
Reference in New Issue View Git Blame Copy Permalink