Skip to content

Architecture

Jump to bottom
endixon edited this page Dec 31, 2025 · 2 revisions

Architecture

This page explains the architecture and the responsibilities of each component in the EndSectors ecosystem. Understanding this design is critical for scalability, reliability, and safe operations.

Core components

  • Common Service (The Brain)

    • Standalone Java application (EndSectors-application.jar).
    • Central coordinator: validates and authenticates sector registrations, stores global configuration in-memory, orchestrates certain cross-server tasks.
    • Acts as a single source of truth for runtime topology.
    • Safety behavior: if Common disconnects or terminates unexpectedly, all sectors are instructed to perform an emergency shutdown to avoid split-brain state or data inconsistencies.

  • Velocity Proxy (The Connector)

    • Plugin EndSectors-proxy.jar deployed to Velocity's plugins/.
    • Hosts the “map” configuration (the sectors layout).
    • Handles server list / MOTD, and decides the target sector when players connect or are queued.
    • Forwards players between sectors when a handover is required.

  • Spigot / Paper Sector Plugin (The Game)

    • Plugin EndSectors-paper.jar deployed to each Spigot/Paper server.
    • Each server is a sector instance that runs the same world folder (this must be identical on all sectors — see consistency notes).
    • Detects boundary crossings and triggers transfers.
    • Uses Redis for atomic player data synchronization and NATS for inter-server events.

  • Tools Plugin (Optional, API example)

    • Plugin EndSectors-tools.jar provides ready commands like /spawn, /rtp, /home.
    • Also serves as a reference for integrating other plugins with the EndSectors API.

  • NATS

    • High-throughput, low-latency messaging for all inter-service packets and commands.
    • Subjects are used for commands, player transfers, diagnostics, and events.
    • Use TLS and authentication in production.

  • Redis

    • Persistent datastore for player state snapshots (inventory, health, gamemode, enderchest, potion effects, etc.).
    • Also used for ephemeral state (locks, locks timeouts), global counters and short-term caches.
    • Use Redis persistence (AOF or RDB) and replication for durability.

Design principles

  • Single world illusion: All sectors must use an identical world folder to guarantee absolute map continuity at borders.
  • Defensive shutdown: If Common is unreachable, sectors perform a safe shutdown to prevent desync and item duplication.
  • Atomic state operations: Player state is written/read in atomic steps to avoid inconsistent states during transfer.
  • Minimal trust between services: Credentials (Redis + NATS) must match across all modules.

Failure modes & handling

  • Common unavailable → sectors shut down (fail-safe).
  • Redis unavailable → transfer and state operations will fail; players should be prevented from crossing sectors or be queued.
  • NATS unavailable → messaging and cross-server commands fail; metrics and manual operations fail.
  • Map mismatch → visual artifacts and world corruption at borders. Strongly avoid by copying identical world folder to all sectors.

Operational recommendations

  • Run Common on a stable host with automated restarts.
  • Use managed Redis (with replication) and a clustered or highly-available NATS deployment.
  • Use monitoring (Prometheus + Grafana) for Redis, JVM, NATS, and TPS per sector.
  • Backup world folders and Redis snapshots frequently.

See Installation for deployment examples and Configuration for full config semantics.

Clone this wiki locally