Kronos HCF

A production-ready Hardcore Factions plugin for Spigot 1.13.2 servers, built with a clean Domain-Driven Design architecture and full async I/O.

Tech Stack

Component	Technology
Minecraft server	Spigot 1.13.2
Dependency injection	Google Guice 5
Primary persistence	MongoDB (via MongoDB Java Driver)
Timer / deathban cache	Redis (via Lettuce async client)
Economy bridge	Vault
Event bus	Guava EventBus
Build system	Gradle 8 + Shadow plugin 8.3.5
Java target	Java 11

---

Module Overview

Module	Artifact	Description
kronos-common	library	Shared utilities: command framework, DB factories, SOTW/EOTW service, config helpers, exception hierarchy
kronos-api	library	Public read-only API exposed to external plugins via Bukkit ServicesManager
kronos-economy	library	Vault economy wrapper with async CompletableFuture API
kronos-players	library	HCF player profiles, deathban (Redis-backed), crate locations
kronos-timers	library	Per-player timers (combat tag, PvP, enderpearl, etc.) stored in Redis with TTL
kronos-factions	library	Faction domain: members, roles, DTK, ally/enemy relations, faction bank
kronos-claims	library	Chunk-based territory system with SafeZone, WarZone, KOTH, and Faction claim types
kronos-koth	library	King of the Hill event zones, creation sessions, capture lifecycle
kronos-classes	library	HCF combat classes (Archer, Bard, Rogue, Miner, Knight, Diamond)
kronos-spawn	library	Protected spawn zone with wand-based setup
kronos-scoreboard	library	Sidebar scoreboard with 1-second timer updates and 5-second async stat refresh
kronos-plugin	plugin jar	Bootstrap module: Guice wiring, command and listener registration, API exposure

---

Architecture Overview

Module Dependency Graph

kronos-plugin
  ├── kronos-api
  │     └── (all domain modules)
  ├── kronos-scoreboard
  │     ├── kronos-timers
  │     ├── kronos-factions
  │     ├── kronos-economy
  │     └── kronos-koth
  ├── kronos-factions
  │     ├── kronos-players
  │     ├── kronos-economy
  │     └── kronos-common
  ├── kronos-claims
  │     └── kronos-factions
  ├── kronos-koth
  │     └── kronos-common
  ├── kronos-players
  │     └── kronos-common
  ├── kronos-timers
  │     └── kronos-common
  ├── kronos-spawn
  │     └── kronos-common
  ├── kronos-classes
  │     └── kronos-players
  └── kronos-economy
        └── kronos-common

Event Flow (Guava EventBus)

All cross-module communication uses domain events posted on a shared EventBus singleton bound by RootModule. The flow is:

1. A service layer completes a business operation (e.g. a faction member dies).
2. The service posts a domain event (e.g. FactionDtkDecrementedDomainEvent).
3. Any @Subscribe-annotated listener in any module receives the event synchronously.
4. Listeners react without coupling directly to the originating service.

Examples of domain events:

Event	Source module	Typical consumer
PlayerTimerStartedDomainEvent	kronos-timers	ScoreboardManager, TimerListener
PlayerTimerExpiredDomainEvent	kronos-timers	ScoreboardManager, TimerListener
FactionCreatedDomainEvent	kronos-factions	Logging, tab-list
FactionRaidableDomainEvent	kronos-factions	PvpListener, announcements
FactionDtkDecrementedDomainEvent	kronos-factions	ScoreboardManager
FactionClaimedDomainEvent	kronos-claims	ClaimListener cache invalidation
KothStartedDomainEvent	kronos-koth	ScoreboardManager
KothCapturedDomainEvent	kronos-koth	ScoreboardManager, crate delivery

Async Pattern (CompletableFuture)

All I/O operations return CompletableFuture<T>. The rule is:

• Never block the Bukkit main thread with database calls.
• MongoDB operations run on the MongoDB driver's thread pool.
• Redis operations run on Lettuce's Netty event loop.
• Vault operations must run on the main thread — VaultEconomyService uses a custom mainThreadExecutor that dispatches via BukkitScheduler.runTask when called from async context.
• Results are applied back to domain objects in .thenAccept / .thenCompose callbacks.

Guice DI

RootModule is the composition root. It installs each domain module (TimersModule, FactionsModule, ClaimsModule, etc.) and binds configuration values from config.yml as @Named constants. All service singletons are wired here.

---

Prerequisites

• Java 11 or newer
• Gradle wrapper included (./gradlew)
• A running MongoDB instance (default: mongodb://localhost:27017)
• A running Redis instance (default: localhost:6379)
• A Spigot 1.13.2 server with Vault and a compatible economy plugin

---

Building

./gradlew :kronos-plugin:shadowJar

The output jar is generated at kronos-plugin/build/libs/. Copy it to your server's plugins/ folder.

---

Directory Structure

kronos/
├── build.gradle.kts               # Root build: plugins, repos, Java 11 target
├── settings.gradle.kts            # Lists all subproject includes
├── kronos-api/                    # Public read-only API for external plugins
├── kronos-common/                 # Shared utilities, DB connections, commands
├── kronos-economy/                # Vault economy wrapper
├── kronos-players/                # Player profiles, deathban, crates
├── kronos-timers/                 # Player timers backed by Redis TTL
├── kronos-factions/               # Faction domain (members, DTK, bank, relations)
├── kronos-claims/                 # Chunk territory system
├── kronos-koth/                   # KOTH event zones
├── kronos-classes/                # HCF combat classes
├── kronos-spawn/                  # Spawn zone protection
├── kronos-scoreboard/             # Sidebar scoreboard
├── kronos-plugin/                 # Bootstrap: Guice wiring, commands, listeners
└── docs/                          # Developer documentation (this folder)

---

Documentation

Module	Doc file
kronos-api	docs/api.md
kronos-timers	docs/timers.md
kronos-factions	docs/factions.md
kronos-claims	docs/claims.md
kronos-koth	docs/koth.md
kronos-players	docs/players.md
kronos-spawn	docs/spawn.md
kronos-economy	docs/economy.md
kronos-classes	docs/classes.md
kronos-scoreboard	docs/scoreboard.md
kronos-common	docs/common.md
kronos-plugin	docs/plugin.md