sybsuper/terradevserver

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.