EndSectors

EndSectors

See it in action: YouTube Demo
️ Interactive Map: Sectors Generator

EndSectors — professional Minecraft sector framework for Paper 1.21.4 with NATS & Redis ️

EndSectors allows you to run a single Minecraft world across multiple Spigot servers, each representing a sector.
All sectors are connected via Velocity, giving players the feeling of one seamless world.

• Each sector has its own boundaries (default 10k per axis)
• Players can move seamlessly between sectors
• Player data (inventory, gamemode, enderchest, etc.) is synced in real-time via Redis
• Inter-server messaging and packets are handled by NATS
• Common service coordinates proxy and sectors, handles core logic, and ensures proper communication

TIP
Production Ready Architecture
This framework is designed for horizontal scaling and high-stability environments.

Architecture

• Common Service (The Brain) – The core of the system. It processes logic and monitors the network. If Common stops, all connected servers automatically shut down to ensure data safety.
• Velocity Proxy (The Connector) – Merges all sectors into one seamless world and handles player switching between servers.
• Spigot Sectors (The Game) – Dedicated servers running specific parts of the world. They detect sector boundaries and sync with the rest of the system.
• NATS – The high-speed transport layer responsible for all packet communication between services.
• Redis – Strictly used for data storage and synchronizing player state (inventory, enderchest, stats).

IMPORTANT
Map Consistency is Critical
For the illusion of a single world to work, all sector servers MUST use the exact same world map (identical world folder).

Example: If you have a fully built spawn on spawn_1, you must upload this exact world folder to all surrounding sectors ( w1, n1, s1, e1).
The terrain and builds at the border must perfectly match across all instances. Do not try to split the map file manually.

Project Modules & Installation

The project consists of 4 artifacts. You must install and configure them in the correct order.

Module List

Configuration Paths (Critical)
Each module generates its own config.json. You MUST ensure that NATS and Redis credentials are IDENTICAL in all of them.

CAUTION
❌ Mismatched Credentials = Network Failure
If the redisPassword or natsUrl differs even by one character between Common, Proxy, and Paper, the connection will be rejected.
Copy-paste your connection details to ensure consistency across all servers.

Startup Sequence
The system must be launched in this strict order to establish connections correctly:

1. Start Common App (java -jar common-1.6-BETA-all.jar)
2. Start Velocity Proxy (Wait for it to connect to Common)
3. Start Spigot Sectors (They will register themselves to the network)

✨ Key Features

• Smart Border Handover – The system calculates player position relative to sector boundaries. Crossing a line triggers an instant, seamless transfer to the neighbor server.
• Atomic Data Sync – Inventory, HP, Food, Enderchest, and Potion Effects are synchronized via Redis. No item duplication or rollback glitches.
• Synchronized Chat – Chat is global. A message sent on spawn_1 is instantly visible on spawn_2.
• ⚖️ Queue & Load Balancing – If a sector is full, players are queued globally. The system also remembers the player's last known sector.
• ️ Fail-Safe Protocol – If the Common App loses connection, all sectors execute an emergency shutdown to prevent data desynchronization.

⚙️ Configuration Example

This section explains how to link the physical server map with individual sector instances.

IMPORTANT
The "Name Trinity" Rule
The sector name MUST be identical in three places for the system to link correctly:
1. velocity.toml (The server name registered in Velocity's [servers] section)
2. proxy/config.json (The JSON Key inside the sectors object)
3. paper/config.json (The currentSector value)

1. Proxy Configuration (The Map Layout)
Located in: plugins/EndSectorsProxy/config.json

Click here to view PROXY CONFIGURATION on GitHub

2. Paper Configuration (The Local Settings)
Located in: plugins/EndSectors/config.json

Click here to view PAPER CONFIGURATION on GitHub

3. Common Configuration (The Brain Settings)
Located in: ./config.json (In the same directory where you placed the .jar file).

Click here to view COMMON CONFIGURATION on GitHub

Localization & Messages

We treat text seriously. Hardcoded strings are strictly forbidden.
EndSectors embraces the Separation of Concerns principle:

• Proxy Messages: Global network notifications, MOTD, queue status, and connection handling.
• Paper Messages: Chat formatting, action bars, titles, GUIs, and interaction feedback.

Language Support
By default, all configuration files ship with Polish (PL) messages.
However, since the system is fully externalized to JSON:

1. You can translate it to English (or any other language) manually by editing the message.json files.
2. Roadmap: We are working on out-of-the-box multi-language support (switching locales via config).

Format Support
We support MiniMessage (gradients, hex colors <#RRGGBB>, hover events) to make your server look like a AAA title.

• Docs: MiniMessage Viewer

1. Proxy Messages (plugins/endsectors-proxy/message.json)
Handles entry point interactions. Notice the structured motd section allowing for complex server list formatting.

Click here to view PROXY MESSAGES on GitHub

2. Paper Messages (plugins/EndSectors/message.json)
Handles in-game feedback, GUIs, and command responses.

Click here to view PAPER MESSAGES on GitHub

Contributing
Feel free to open an Issue if you find a bug or a Pull Request if you want to improve the logic.
Special thanks to all testers!!