Skip to content

Home

Jump to bottom
endixon edited this page Jan 1, 2026 · 11 revisions
EndSectors Banner

EndSectors

Java 21 Microservices License



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

EndSectors is a production-ready microservice framework that runs a single Minecraft world across multiple Paper 1.21.4 servers (sectors). It uses NATS for messaging and Redis for atomic player-state synchronization so players experience one continuous world while servers scale horizontally.

Quick links

Tip

EndSectors is designed for production. If you plan to run it on a public network, use private networks, TLS for NATS, and persistent Redis with backups.

What EndSectors gives you

  • Seamless multi-server single-world experience — borders are invisible to players.
  • Real-time, atomic player state sync (inventory, enderchest, health, gamemode, potion effects).
  • Global chat, queues and cross-server commands.
  • Horizontal scalability: add sectors as JVMs when you need capacity.
  • Fail-safe orchestration: Common service enforces safe shutdown on critical failure.

Architecture — at a glance

  • Common Service (The Brain) — central orchestrator; must run first. If Common becomes unavailable, sectors will shut down to avoid desync.
  • Velocity Proxy (The Connector) — merges sectors, manages queues & MOTD, and holds the sector map.
  • Paper / Spigot Sectors (The Game) — each sector is a Paper server running the exact same world folder and the Paper plugin.
  • NATS — low-latency messaging backbone (all packet and command traffic).
  • Redis — authoritative store for player snapshots and short-lived locks.

Important

Map consistency is critical. All sectors MUST use the IDENTICAL world folder. Do not split or manually modify region files between sectors — copy the same world to every sector host.

Project modules

Install in the exact order below (Common first).

Module File Placement
Common App EndSectors-application.jar standalone — place config.json next to jar
Proxy Plugin EndSectors-proxy.jar Velocity → plugins/
Paper Plugin EndSectors-paper.jar Paper/Spigot → plugins/
Tools Plugin EndSectors-tools.jar Paper/Spigot → plugins/ (optional helper & API examples)

Configuration paths (critical): ensure natsUrl and redisPassword are identical in Common, Proxy and Paper configs.

Minimal startup sequence

  1. 🔴 Start Common (java -jar EndSectors-application.jar)
  2. 🟡 Start Velocity with EndSectors-proxy plugin (wait for registration)
  3. 🟢 Start Paper sector servers (they register to Common automatically)

Key features

  • Smart Border Handover — precise edge detection and immediate transfer
  • Atomic State Sync — Redis-backed, single-writer semantics to avoid duplicates
  • Global Chat & Commands — NATS-broadcasted messaging across sectors
  • Queueing & Load Balancing — global queue with last-known-sector preference
  • Fail-safe Shutdown — prevents split-brain and data corruption

Quick configuration preview

Proxy (map layout) — plugins/EndSectorsProxy/config.json (excerpt)

{
  "natsUrl": "nats://127.0.0.1:4222",
  "redisHost": "127.0.0.1",
  "sectors": {
    "SPAWN": {
      "spawn_1": { "pos1X": -200, "pos1Z": -200, "pos2X": 200, "pos2Z": 200, "type": "SPAWN", "world": "world" }
    }
  }
}

Paper (local) — plugins/EndSectors/config.json (excerpt)

{
  "currentSector": "spawn_1",
  "redisHost": "127.0.0.1",
  "natsUrl": "nats://127.0.0.1:4222",
  "natsConnectionName": "spawn_1"
}

Common — ./config.json (next to the jar)

{
  "redisHost": "127.0.0.1",
  "redisPort": 6379,
  "redisPassword": "CHANGE_ME",
  "natsUrl": "nats://127.0.0.1:4222",
  "natsConnectionName": "common-service"
}

Localization & texts

  • All player-facing strings are externalized to JSON (message.json). Default language in packaged files is Polish — translate to English by editing these files.
  • Supports MiniMessage formatting (gradients, hex colors, bold, hover).

Production checklist (short)

  • Common running on stable host with auto-restart (systemd)
  • Redis protected and backed up (AOF/RDB)
  • NATS with auth/TLS (HA recommended)
  • Identical world folder on all sectors (verify with file hashes)
  • Monitoring for JVM, Redis, NATS, TPS (Prometheus/Grafana)
  • Backups and restore tested

Want help?

I can:

  • Convert this home page into a README-ready variant.
  • Generate Docker Compose (NATS + Redis + Common + sample Paper stubs) for local testing.
  • Create systemd units or Helm charts for production.

If you want the Home page to match the README exactly, tell me which README section you want copied verbatim (e.g., full config tables, full scoreboard templates, exact Polish messages converted to English) and I will produce the final polished variant.

(Full footer available here: https://github.com/endixons/EndSectors/wiki/Footer)

Clone this wiki locally