# sybsuper/terradevserver architecture

> Architecture diagram of the GitHub repository sybsuper/terradevserver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sybsuper/terradevserver
- Repository: https://github.com/sybsuper/terradevserver

## Overview

1. **System role**
   - This repository is a **standalone Kotlin/JVM Minecraft dev server** for Terra packs.
   - Its purpose is to run a local server, load a Terra pack from a `dev/` folder, and support rapid iteration without restarting the server.

2. **Top-level runtime**
   - `Main.kt` is the entry point and likely wires together the server bootstrap, configuration, world creation, command registration, and module activation.
   - The project is built as a single Gradle application, packaged into a runnable jar.

3. **Configuration boundary**
   - `Config.kt` owns server settings such as bind address, port, pack folder, world seed, MOTD, enabled commands, and feature flags.
   - The config file is persisted in the server root and acts as the main switchboard for which subsystems are active.

4. **World and pack lifecycle**
   - `WorldCreator.kt` appears to create or initialize the Minecraft world/instance from the Terra pack.
   - `UpdateDevPack.kt` is the central reload path: it swaps in updated pack content from disk and triggers downstream updates.
   - `events/PackPostLoadEvent.kt` marks the completion of pack loading so other systems can react after the new pack is ready.

5. **Hot-reload and filesystem watching**
   - `modules/WatchFolders.kt` is the filesystem watcher that detects changes inside the dev pack directory.
   - The flow is: file change in `dev/` → pack update/reload → pack post-load event → world/player/module adjustments.
   - This is the core mechanism behind the repository’s “hot-reloading” feature.

6. **Player session and view synchronization**
   - `modules/SyncPositions.kt` keeps players aligned so multiple clients can be used as side-by-side “before/after” views.
   - `modules/PlayerCycleTarget.kt` likely manages which player is used as the reference when cycling between reload views.
   - `PlayerLogger.kt` suggests join/leave tracking to support these player coordination features.

7. **Biome registry handling**
   - `modules/BiomeRegistryFix.kt` and `commands/ReregisterBiomes.kt` address a key Terra dev problem: adding new biomes without forcing a full server/world restart.
   - The architecture here is explicitly designed to handle biome-registry changes during pack reloads, which is why there is also a config flag for fixing biome disconnects.
   - `events/PrePlayerSendNewInstanceForPackEvent.kt` indicates player transfer/reconnect handling when the server needs to move clients to a refreshed pack instance.

8. **Instance cleanup and server health**
   - `modules/RemoveDeadInstances.kt` is responsible for cleaning up stale world instances created by previous pack loads.
   - This keeps the reload cycle from accumulating unused world state and helps the server remain stable during repeated edits.

9. **Command subsystem**
   - `commands/CommandManager.kt` is the command registry and dispatcher.
   - Each command implements `commands/ICommand.kt`, so command behavior is modular and can be enabled/disabled through config.
   - The built-in commands are:
     - `Reload` for manual pack reloads,
     - `Locate` for biome lookup in the current world,
     - `Teleport` for direct movement,
     - `ReregisterBiomes` for biome-registry refreshes.

10. **Module subsystem**
   - `modules/ModuleManager.kt` is the feature-toggle layer that starts/stops optional behaviors based on configuration.
   - The modules are deliberately separated from commands: commands are user-triggered actions, while modules are always-on or config-driven server behaviors.

11. **MOTD and server presentation**
   - `modules/Motd.kt` controls the server-list display name, which is part of the server’s external face to Minecraft clients.
   - This is a small but distinct presentation subsystem separate from pack loading and gameplay mechanics.

12. **Important architectural flow**
   - The main loop is: **boot server → load config → create world from dev pack → register commands/modules → watch for file changes → reload pack → update players/instances/biomes**.
   - The repository is organized around that lifecycle, with events used as boundaries so pack loading, player handling, and biome fixes remain loosely coupled.

Main entry points: [`src/main/kotlin/Main.kt`](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/Main.kt) (Main), [`src/main/kotlin/modules/ModuleManager.kt`](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/ModuleManager.kt) (Module Manager), [`src/main/kotlin/commands/CommandManager.kt`](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/CommandManager.kt) (Command Manager), [`src/main/kotlin/events/PackPostLoadEvent.kt`](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/events/PackPostLoadEvent.kt) (Pack Post Load)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>bootstrap entrypoint<br/>[Main.kt]"]
  node_config["Config<br/>[Config.kt]"]
end

subgraph group_pack["Pack Reload"]
  node_worldcreator["World Creator<br/>world bootstrap<br/>[WorldCreator.kt]"]
  node_updatepack["Update Pack<br/>reload pipeline<br/>[UpdateDevPack.kt]"]
  node_packevent(("Pack Post Load<br/>reload event"))
  node_watchfolders["Watch Folders<br/>fs watcher<br/>[WatchFolders.kt]"]
end

subgraph group_access["Player Sync"]
  node_preinstanceevent(("Pre Send Event<br/>instance event"))
  node_syncpositions["Sync Positions<br/>[SyncPositions.kt]"]
  node_playertarget["Cycle Target"]
  node_playerlogger["Player Logger<br/>session log<br/>[PlayerLogger.kt]"]
end

subgraph group_features["Features"]
  node_modulemanager["Module Manager<br/>feature toggle<br/>[ModuleManager.kt]"]
  node_biomefix["Biome Fix"]
  node_removedead["Remove Dead<br/>cleanup module"]
  node_motd["MOTD<br/>presentation module<br/>[Motd.kt]"]
end

subgraph group_commands["Commands"]
  node_commandmanager["Command Manager<br/>dispatcher<br/>[CommandManager.kt]"]
  node_icommand["ICommand<br/>command contract<br/>[ICommand.kt]"]
  node_reloadcmd["Reload<br/>command<br/>[Reload.kt]"]
  node_locatecmd["Locate<br/>command<br/>[Locate.kt]"]
  node_teleportcmd["Teleport<br/>command<br/>[Teleport.kt]"]
  node_reregistercmd["Reregister Biomes<br/>command"]
end

node_main -->|"loads"| node_config
node_main -->|"creates world"| node_worldcreator
node_main -->|"starts modules"| node_modulemanager
node_main -->|"registers commands"| node_commandmanager
node_main -->|"enables watch"| node_watchfolders
node_main -->|"configures"| node_motd
node_watchfolders -->|"triggers"| node_updatepack
node_updatepack -->|"emits"| node_packevent
node_packevent -->|"refreshes world"| node_worldcreator
node_packevent -->|"prepares transfer"| node_preinstanceevent
node_preinstanceevent -->|"aligns players"| node_syncpositions
node_preinstanceevent -->|"tracks players"| node_playerlogger
node_modulemanager -->|"activates"| node_biomefix
node_modulemanager -->|"activates"| node_syncpositions
node_modulemanager -->|"activates"| node_playertarget
node_modulemanager -->|"activates"| node_removedead
node_modulemanager -->|"activates"| node_motd
node_commandmanager -->|"implements"| node_icommand
node_commandmanager -->|"registers"| node_reloadcmd
node_commandmanager -->|"registers"| node_locatecmd
node_commandmanager -->|"registers"| node_teleportcmd
node_commandmanager -->|"registers"| node_reregistercmd
node_reloadcmd -->|"calls"| node_updatepack
node_reregistercmd -->|"uses"| node_biomefix

click node_main "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/Main.kt"
click node_config "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/Config.kt"
click node_worldcreator "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/WorldCreator.kt"
click node_updatepack "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/UpdateDevPack.kt"
click node_packevent "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/events/PackPostLoadEvent.kt"
click node_preinstanceevent "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/events/PrePlayerSendNewInstanceForPackEvent.kt"
click node_watchfolders "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/WatchFolders.kt"
click node_modulemanager "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/ModuleManager.kt"
click node_commandmanager "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/CommandManager.kt"
click node_icommand "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/ICommand.kt"
click node_reloadcmd "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/Reload.kt"
click node_locatecmd "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/Locate.kt"
click node_teleportcmd "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/Teleport.kt"
click node_reregistercmd "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/ReregisterBiomes.kt"
click node_biomefix "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/BiomeRegistryFix.kt"
click node_syncpositions "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/SyncPositions.kt"
click node_playertarget "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/PlayerCycleTarget.kt"
click node_playerlogger "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/PlayerLogger.kt"
click node_removedead "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/RemoveDeadInstances.kt"
click node_motd "https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/Motd.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_config toneBlue
class node_worldcreator,node_updatepack,node_packevent,node_watchfolders toneAmber
class node_preinstanceevent,node_syncpositions,node_playertarget,node_playerlogger toneMint
class node_modulemanager,node_biomefix,node_removedead,node_motd toneRose
class node_commandmanager,node_icommand,node_reloadcmd,node_locatecmd,node_teleportcmd,node_reregistercmd toneIndigo
```

## Components

### Runtime

Server bootstrap and core lifecycle

- [Main](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/Main.kt): bootstrap entrypoint · Starts the JVM server and wires core subsystems. · `src/main/kotlin/Main.kt`
- [Config](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/Config.kt): server config · Persistent settings for bind, port, pack path, seed, MOTD, and feature flags. · `src/main/kotlin/Config.kt`

### Pack Reload

Dev pack loading, world creation, and reload events

- [World Creator](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/WorldCreator.kt): world bootstrap · Creates or initializes the Minecraft world from the Terra dev pack. · `src/main/kotlin/WorldCreator.kt`
- [Update Pack](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/UpdateDevPack.kt): reload pipeline · Central reload path that swaps updated pack content into the running server. · `src/main/kotlin/UpdateDevPack.kt`
- [Pack Post Load](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/events/PackPostLoadEvent.kt): reload event · Signals that a pack has finished loading so downstream systems can react. · `src/main/kotlin/events/PackPostLoadEvent.kt`
- [Watch Folders](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/WatchFolders.kt): fs watcher · Monitors the dev pack directory and triggers reloads on file changes. · `src/main/kotlin/modules/WatchFolders.kt`

### Player Sync

Player coordination and instance transitions

- [Pre Send Event](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/events/PrePlayerSendNewInstanceForPackEvent.kt): instance event · Raised before moving a player into a refreshed instance for the updated pack. · `src/main/kotlin/events/PrePlayerSendNewInstanceForPackEvent.kt`
- [Sync Positions](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/SyncPositions.kt): module · Keeps multiple players aligned for side-by-side comparison. · `src/main/kotlin/modules/SyncPositions.kt`
- [Cycle Target](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/PlayerCycleTarget.kt): module · Tracks the reference player used when cycling views. · `src/main/kotlin/modules/PlayerCycleTarget.kt`
- [Player Logger](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/PlayerLogger.kt): session log · Tracks player join and leave activity for coordination flows. · `src/main/kotlin/PlayerLogger.kt`

### Features

Optional modules and service behaviors

- [Module Manager](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/ModuleManager.kt): feature toggle · Starts and stops config-driven runtime modules. · `src/main/kotlin/modules/ModuleManager.kt`
- [Biome Fix](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/BiomeRegistryFix.kt): module · Handles biome registry changes without requiring a full restart. · `src/main/kotlin/modules/BiomeRegistryFix.kt`
- [Remove Dead](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/RemoveDeadInstances.kt): cleanup module · Deletes stale world instances left behind by previous reloads. · `src/main/kotlin/modules/RemoveDeadInstances.kt`
- [MOTD](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/modules/Motd.kt): presentation module · Controls the server-list display text seen by clients. · `src/main/kotlin/modules/Motd.kt`

### Commands

User-triggered actions and command dispatch

- [Command Manager](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/CommandManager.kt): dispatcher · Registers and dispatches built-in commands. · `src/main/kotlin/commands/CommandManager.kt`
- [ICommand](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/ICommand.kt): command contract · Shared interface implemented by all commands. · `src/main/kotlin/commands/ICommand.kt`
- [Reload](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/Reload.kt): command · Manual trigger for pack reloads. · `src/main/kotlin/commands/Reload.kt`
- [Locate](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/Locate.kt): command · Finds a biome or target in the current world. · `src/main/kotlin/commands/Locate.kt`
- [Teleport](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/Teleport.kt): command · Moves a player directly to a chosen location. · `src/main/kotlin/commands/Teleport.kt`
- [Reregister Biomes](https://github.com/sybsuper/terradevserver/blob/main/src/main/kotlin/commands/ReregisterBiomes.kt): command · Refreshes biome registration during pack reloads. · `src/main/kotlin/commands/ReregisterBiomes.kt`

## Connections

- Main → Config: loads · Boot reads persisted server settings before enabling subsystems.
- Main → World Creator: creates world · Startup initializes the world from the dev pack.
- Main → Module Manager: starts modules · Main activates optional behaviors from configuration.
- Main → Command Manager: registers commands · Main wires the command subsystem during boot.
- Main → Watch Folders: enables watch · Boot turns on filesystem watching for dev-pack changes.
- Main → MOTD: configures · Main applies server presentation settings.
- Watch Folders → Update Pack: triggers · File edits initiate the reload pipeline.
- Update Pack → Pack Post Load: emits · Pack reload completion is published as an event.
- Pack Post Load → World Creator: refreshes world · Downstream consumers may recreate or update world state.
- Pack Post Load → Pre Send Event: prepares transfer · Reload completion can lead into player migration flows.
- Pre Send Event → Sync Positions: aligns players · Player transfer workflows preserve comparative positioning.
- Pre Send Event → Player Logger: tracks players · Player movement and reconnects are logged.
- Module Manager → Biome Fix: activates · Feature toggles enable biome-registry repair behavior.
- Module Manager → Sync Positions: activates · Feature toggles enable multi-client alignment.
- Module Manager → Cycle Target: activates · Feature toggles enable reference-player cycling.
- Module Manager → Remove Dead: activates · Feature toggles enable stale-instance cleanup.
- Module Manager → MOTD: activates · Feature toggles can include server presentation behavior.
- Command Manager → ICommand: implements · Commands are registered through a shared interface contract.
- Command Manager → Reload: registers · Manual reload command is exposed to operators.
- Command Manager → Locate: registers · Biome lookup command is exposed to operators.
- Command Manager → Teleport: registers · Teleport command is exposed to operators.
- Command Manager → Reregister Biomes: registers · Biome registry refresh command is exposed to operators.
- Reload → Update Pack: calls · Manual reload invokes the same pack update pipeline.
- Reregister Biomes → Biome Fix: uses · Command path re-registers biome state during reloads.