Positioning (Fabric/Quilt Mod) - Minecraft 1.21.5

🇪🇸 Spanish version: README.es.md

What Is Positioning?

Positioning is a Minecraft server mod that divides the world into two territories, North and South, using the Z axis. It is designed for PvP servers, team-based worlds, and rule-driven survival experiences where each group must stay on its own side of the map.

Each player belongs to one group and can only explore the territory assigned to that group. The center of the world acts as a neutral zone, while enemy territory triggers warnings, a visual countdown, and final penalties.

• North Zone (Z+)
• South Zone (Z-)
• Neutral Zone: 50 blocks on each side of the Z axis, from Z -50 to Z +50

---

How It Works

• When a player joins for the first time, they choose a group through a native pop-up. No commands or administrator setup are required for the initial selection.
• The selected group is saved automatically and cannot be changed unless the saved data file is removed.
• Each group can explore only its assigned Z-axis hemisphere:
  • North: Z >= 0
  • South: Z <= 0
• Both groups can stay in the neutral zone between Z -50 and Z +50 without penalties.
• Warnings and penalties are applied progressively:
  • Entering enemy territory sends an initial warning.
  • Continuing forward starts a 60-second visual countdown using a boss bar.
  • Reaching the final enemy boundary, Z -50 for North players or Z +50 for South players, kills the player instantly.
• The territory logic only applies in the Overworld. The Nether and End are unrestricted.

---

Installation

1. Download the mod JAR from a release or build it manually from source.
2. Install the JAR in the mods folder of a Minecraft 1.21.5 server running Fabric Loader.
3. Install Fabric API on the server.
4. Optionally install the mod on clients as well. This is recommended for the visual boss bar feedback.

---

Dependencies

• Fabric API, compatible with Minecraft 1.21.5
• Fabric Loader 0.16.14 or newer
• Java 21 or newer
• Minecraft 1.21.5

---

Data Persistence

• Group selections are stored in player_groups.json at the world root, for example ./world/player_groups.json.
• If that file is deleted, players will be asked to choose their group again the next time they join.

---

Code And Contribution

The code is open and intended to be easy to extend or fork.

Contributions are welcome through issues and pull requests, especially for UI improvements, additional gameplay rules, configuration options, or support for different team structures.

---

Roadmap / Future Ideas

• Advanced animations and visual effects for the boss bar
• Invasion event systems and PvP logs
• Compatibility with economy or town/city mods
• Advanced configuration through a dedicated config file

---

License

MIT

Project maintained by Gaston Roman.

---

Usage Example

1. A player joins the server and sees the menu to choose North or South.
2. The player explores the world according to their group, with visual feedback when crossing territory limits.
3. If the player invades enemy territory, they must return before the countdown reaches zero or before they cross the final boundary.