Dedicated Server Software - Minecraft.Server.exe (#498)

* add: Dedicated Server implementation

- Introduced `ServerMain.cpp` for the dedicated server logic, handling command-line arguments, server initialization, and network management.
- Created `postbuild_server.ps1` script for post-build tasks, including copying necessary resources and DLLs for the dedicated server.
- Added `CopyServerAssets.cmake` to manage the copying of server assets during the build process, ensuring required files are available for the dedicated server.
- Defined project filters in `Minecraft.Server.vcxproj.filters` for better organization of server-related files.

* add: refactor world loader & add server properties

- Introduced ServerLogger for logging startup steps and world I/O operations.
- Implemented ServerProperties for loading and saving server configuration from `server.properties`.
- Added WorldManager to handle world loading and creation based on server properties.
- Updated ServerMain to integrate server properties loading and world management.
- Enhanced project files to include new source and header files for the server components.

* update: implement enhanced logging functionality with configurable log levels

* update: update keyboard and mouse input initialization 1dc8a005ed111463c22c17b487e5ec8a3e2d30f3

* fix: change virtual screen resolution to 1920x1080(HD)

Since 31881af56936aeef38ff322b975fd0 , `skinHud.swf` for 720 is not included in `MediaWindows64.arc`,
the app crashes unless the virtual screen is set to HD.

* fix: dedicated server build settings for miniaudio migration and missing sources

- remove stale Windows64 Miles (mss64) link/copy references from server build
- add Common/Filesystem/Filesystem.cpp to Minecraft.Server.vcxproj
- add Windows64/PostProcesser.cpp to Minecraft.Server.vcxproj
- fix unresolved externals (PostProcesser::*, FileExists) in dedicated server build

* update: changed the virtual screen to 720p

Since the crash caused by the 720p `skinHud.swf` not being included in `MediaWindows64.arc` has been resolved, switching back to 720p to reduce resource usage.

* add: add Docker support for Dedicated Server

add with entrypoint and build scripts

* fix: add initial save for newly created worlds in dedicated server

on the server side, I fixed the behavior introduced after commit aadb511, where newly created worlds are intentionally not saved to disk immediately.

* update: add basically all configuration options that are implemented in the classes to `server.properties`

* update: add LAN advertising configuration for server.properties

LAN-Discovery, which isn’t needed in server mode and could potentially be a security risk, has also been disabled(only server mode).

* add: add implementing interactive command line using linenoise

- Integrated linenoise library for line editing and completion in the server console.
- Updated ServerLogger to handle external writes safely during logging.
- Modified ServerMain to initialize and manage the ServerCli for command input.
- The implementation is separate from everything else, so it doesn't affect anything else.
- The command input section and execution section are separated into threads.

* update: enhance command line completion with predictive hints

Like most command line tools, it highlights predictions in gray.

* add: implement `StringUtils` for string manipulation and refactor usages

Unified the scattered utility functions.

* fix: send DisconnectPacket on shutdown and fix Win64 recv-thread teardown race

Before this change, server/host shutdown closed sockets directly in
ServerConnection::stop(), which bypassed the normal disconnect flow.
As a result, clients could be dropped without receiving a proper
DisconnectPacket during stop/kill/world-close paths.

Also, WinsockNetLayer::Shutdown() could destroy synchronization objects
while host-side recv threads were still exiting, causing a crash in
RecvThreadProc (access violation on world close in host mode).

* fix: return client to menus when Win64 host connection drops

- Add client-side host disconnect handling in CPlatformNetworkManagerStub::DoWork() for _WINDOWS64.
- When in QNET_STATE_GAME_PLAY as a non-host and WinsockNetLayer::IsConnected() becomes false, trigger g_NetworkManager.HandleDisconnect(false) to enter the normal disconnect/UI flow.
- Use m_bLeaveGameOnTick as a one-shot guard to prevent repeated disconnect handling while the link remains down.
- Reset m_bLeaveGameOnTick on LeaveGame(), HostGame(), and JoinGame() to avoid stale state across sessions.

* update: converted Japanese comments to English

* add: create `Minecraft.Server` developer guide in English and Japanese

* update: add note about issue

* add: add `nlohmann/json` json lib

* add: add FileUtils

Moved file operations to `utils`.

* add: Dedicated Server BAN access manager with persistent player and IP bans

- add Access frontend that publishes thread-safe ban manager snapshots for dedicated server use
- add BanManager storage for banned-players.json and banned-ips.json with load/save/update flows
- add persistent player and IP ban checks during dedicated server connection handling
- add UTF-8 BOM-safe JSON parsing and shared file helpers backed by nlohmann/json
- add Unicode-safe ban file read/write and safer atomic replacement behavior on Windows
- add active-ban snapshot APIs and expiry-aware filtering for expires metadata
- add RAII-based dedicated access shutdown handling during server startup and teardown

* update: changed file read/write operations to use `FileUtils`.

- As a side effect, saving has become faster!

* fix: Re-added the source that had somehow disappeared.

* add: significantly improved the dedicated server logging system

- add ServerLogManager to Minecraft.Server as the single entry point for dedicated-server log output
- forward CMinecraftApp logger output to the server logger when running with g_Win64DedicatedServer
- add named network logs for incoming, accepted, rejected, and disconnected connections
- cache connection metadata by smallId so player name and remote IP remain available for disconnect logs
- keep Minecraft.Client changes minimal by using lightweight hook points and handling log orchestration on the server side

* fix: added the updated library source

* add: add `ban` and `pardon` commands for Player and IP

* fix: fix stop command shutdown process

add dedicated server shutdown request handling

* fix: fixed the save logic during server shutdown

Removed redundant repeated saves and eliminated the risks of async writes.

* update: added new sever files to Docker entrypoint

* fix: replace shutdown flag with atomic variable for thread safety

* update: update Dedicated Server developer guide

English is machine translated.
Please forgive me.

* update: check for the existence of `GameHDD` and create

* add: add Whitelist to Dedicated Server

* refactor: clean up and refactor the code

- unify duplicated implementations that were copied repeatedly
- update outdated patterns to more modern ones

* fix: include UI header (new update fix)

* fix: fix the detection range for excessive logging

`getHighestNonEmptyY()` returning `-1` occurs normally when the chunk is entirely air.
The caller (`Minecraft.World/LevelChunk.cpp:2400`) normalizes `-1` to `0`.

* update: add world size config to dedicated server properties

* update: update README add explanation of  `server.properties` & launch arguments

* update: add nightly release workflow for dedicated server and client builds to Actions

* fix: update name for workflow

* add random seed generation

* add: add Docker nightly workflow for Dedicated Server publish to GitHub Container Registry

* fix: ghost player when clients disconnect out of order

#4

* fix: fix 7zip option

* fix: fix Docker workflow for Dedicated Server artifact handling

* add: add no build Dedicated Server startup scripts and Docker Compose

* update: add README for Docker Dedicated Server setup with no local build

* refactor: refactor command path structure

As the number of commands has increased and become harder to navigate, each command has been organized into separate folders.

* update: support stream(file stdin) input mode for server CLI

Support for the stream (file stdin) required when attaching a tty to a Docker container on Linux.

* add: add new CLI Console Commands for Dedicated Server

Most of these commands are executed using the command dispatcher implemented on the `Minecraft.World` side. When registering them with the dispatcher, the sender uses a permission-enabled configuration that treats the CLI as a player.

- default game.
- enchant
- experience.
- give
- kill(currently, getting a permission error for some reason)
- time
- weather.
- update tp & gamemode command

* fix: change player map icon to random select

* update: increase the player limit

* add: restore the basic anti-cheat implementation and add spawn protection

Added the following anti-cheat measures and add spawn protection to `server.properties`.
- instant break
- speed
- reach

* fix: fix Docker image tag

---------

Co-authored-by: sylvessa <225480449+sylvessa@users.noreply.github.com>

1 files changed, 284 insertions, 0 deletions

diff --git a/Minecraft.Server/docs/DEVELOPMENT.en.md b/Minecraft.Server/docs/DEVELOPMENT.en.md
new file mode 100644
index 00000000..5348f020
--- /dev/null
+++ b/Minecraft.Server/docs/DEVELOPMENT.en.md
@@ -0,0 +1,284 @@
+# Minecraft.Server Developer Guide (English)
+
+This document is for contributors who are new to `Minecraft.Server` and need a practical map for adding or modifying features safely.
+
+## 1. What This Server Does
+
+`Minecraft.Server` is the dedicated-server executable entry for this codebase.
+
+Core responsibilities:
+- Switch the process working directory to the executable folder before relative file I/O
+- Load, normalize, and repair `server.properties`
+- Initialize dedicated runtime systems, connection logging, and access control
+- Load or create the target world and keep `level-id` aligned with the actual save destination
+- Run the dedicated main loop (network tick, XUI actions, autosave, CLI input)
+- Maintain operator-facing access files such as `banned-players.json` and `banned-ips.json`
+- Perform an initial save for newly created worlds and then shut down safely
+
+## 2. Important Files
+
+### Startup and Runtime
+- `Windows64/ServerMain.cpp`
+  - `PrintUsage()` and `ParseCommandLine()`
+  - `SetExeWorkingDirectory()`
+  - Runtime setup and shutdown flow
+  - Initial save path for newly created worlds
+  - Main loop, autosave scheduler, and CLI polling
+
+### World Selection and Save Load
+- `WorldManager.h`
+- `WorldManager.cpp`
+  - Finds matching save by `level-id` first, then world-name fallback
+  - Applies storage title + save ID consistently
+  - Wait helpers for async storage/server action completion
+
+### Server Properties
+- `ServerProperties.h`
+- `ServerProperties.cpp`
+  - Default values and normalization ranges
+  - Parse/repair/write `server.properties`
+  - Exposes `ServerPropertiesConfig`
+  - `SaveServerPropertiesConfig()` rewrites `level-name`, `level-id`, and `white-list`
+
+### Access Control, Ban, and Whitelist Storage
+- `Access/Access.h`
+- `Access/Access.cpp`
+  - Process-wide access-control facade
+  - Published snapshot model used by console commands and login checks
+- `Access/BanManager.h`
+- `Access/BanManager.cpp`
+  - Reads/writes `banned-players.json` and `banned-ips.json`
+  - Normalizes identifiers and filters expired entries from snapshots
+- `Access/WhitelistManager.h`
+- `Access/WhitelistManager.cpp`
+  - Reads/writes `whitelist.json`
+  - Normalizes XUID-based whitelist entries used by login validation and CLI commands
+
+### Logging and Connection Audit
+- `ServerLogger.h`
+- `ServerLogger.cpp`
+  - Log level parsing
+  - Colored/timestamped console logs
+  - General categories such as `startup`, `world-io`, `console`, `access`, `network`, and `shutdown`
+- `ServerLogManager.h`
+- `ServerLogManager.cpp`
+  - Accepted/rejected TCP connection logs
+  - Login/disconnect audit logs
+  - Remote-IP cache used by `ban-ip <player>`
+
+### Console Command System
+- `Console/ServerCli.cpp` (facade)
+- `Console/ServerCliInput.cpp` (linenoise input thread + completion bridge)
+- `Console/ServerCliParser.cpp` (tokenization, quoted args, completion context)
+- `Console/ServerCliEngine.cpp` (dispatch, completion, helpers)
+- `Console/ServerCliRegistry.cpp` (command registration + lookup)
+- `Console/commands/*` (individual commands)
+
+## 3. End-to-End Startup Flow
+
+Main flow in `Windows64/ServerMain.cpp`:
+1. `SetExeWorkingDirectory()` switches the current directory to the executable folder.
+2. Load and normalize `server.properties` via `LoadServerPropertiesConfig()`.
+3. Copy config into `DedicatedServerConfig`, then apply CLI overrides (`-port`, `-ip`/`-bind`, `-name`, `-maxplayers`, `-seed`, `-loglevel`, `-help`/`--help`/`-h`).
+4. Initialize process state, `ServerLogManager`, and `Access::Initialize(".")`.
+5. Initialize window/device/profile/network/thread-local systems.
+6. Set host/game options from `ServerPropertiesConfig`.
+7. Bootstrap world with `BootstrapWorldForServer(...)`.
+8. If world bootstrap resolves a different normalized save ID, persist it with `SaveServerPropertiesConfig()`.
+9. Start hosted game thread (`RunNetworkGameThreadProc`).
+10. If a brand-new world was created, explicitly request one initial save.
+11. Enter the main loop:
+   - `TickCoreSystems()`
+   - `HandleXuiActions()`
+   - `serverCli.Poll()`
+   - autosave scheduling
+12. On shutdown:
+   - stop CLI input
+   - request save-on-exit / halt server
+   - wait for network shutdown completion
+   - terminate log, access, network, and device systems
+
+## 4. Current Operator Surface
+
+### 4.1 Launch Arguments
+- `-port <1-65535>`
+- `-ip <addr>` or `-bind <addr>`
+- `-name <name>` (runtime max 16 chars)
+- `-maxplayers <1-8>`
+- `-seed <int64>`
+- `-loglevel <debug|info|warn|error>`
+- `-help`, `--help`, `-h`
+
+Notes:
+- CLI overrides affect only the current process.
+- The only values currently written back by the server are `level-name` and `level-id`, and that happens when world bootstrap resolves identity changes.
+
+### 4.2 Built-in Console Commands
+- `help` / `?`
+- `stop`
+- `list`
+- `ban <player> [reason ...]`
+  - currently requires the target player to be online
+- `ban-ip <address|player> [reason ...]`
+  - accepts a literal IPv4/IPv6 address or an online player's current remote IP
+- `pardon <player>`
+- `pardon-ip <address>`
+  - only accepts a literal address
+- `banlist`
+- `tp <player> <target>` / `teleport`
+- `gamemode <survival|creative|0|1> [player]` / `gm`
+
+CLI behavior notes:
+- Command parsing accepts both `cmd` and `/cmd`.
+- Quoted arguments are supported by `ServerCliParser`.
+- Completion is implemented per command via `Complete(...)`.
+
+### 4.3 Files Written Next to the Executable
+- `server.properties`
+- `banned-players.json`
+- `banned-ips.json`
+
+This follows from `SetExeWorkingDirectory()`, so these files are resolved relative to `Minecraft.Server.exe`, not the shell directory you launched from.
+
+## 5. Common Development Tasks
+
+### 5.1 Add a New CLI Command
+
+Use this pattern when adding commands like `/kick`, `/time`, etc.
+
+1. Add files under `Console/commands/`
+   - `CliCommandYourCommand.h`
+   - `CliCommandYourCommand.cpp`
+2. Implement `IServerCliCommand`
+   - `Name()`, `Usage()`, `Description()`, `Execute(...)`
+   - optional: `Aliases()` and `Complete(...)`
+3. Register the command in `ServerCliEngine::RegisterDefaultCommands()`.
+4. Add source/header to build definitions:
+   - `CMakeLists.txt` (`MINECRAFT_SERVER_SOURCES`)
+   - `Minecraft.Server/Minecraft.Server.vcxproj` (`<ClCompile>` / `<ClInclude>`)
+5. Manual verify:
+   - command appears in `help`
+   - command executes correctly
+   - completion works for both `cmd` and `/cmd`
+   - quoted arguments behave as expected
+
+Implementation references:
+- `CliCommandHelp.cpp` for a simple no-arg command
+- `CliCommandTp.cpp` for multi-arg + completion + runtime checks
+- `CliCommandGamemode.cpp` for argument parsing and aliases
+- `CliCommandBanIp.cpp` for access-backed behavior with connection metadata
+
+### 5.2 Add or Change a `server.properties` Key
+
+1. Add/update the field in `ServerPropertiesConfig` (`ServerProperties.h`).
+2. Add a default entry to `kServerPropertyDefaults` (`ServerProperties.cpp`).
+3. Load and normalize the value in `LoadServerPropertiesConfig()`.
+   - Use existing helpers for bool/int/string/int64/log level/level type.
+4. If this value should be written back, update `SaveServerPropertiesConfig()`.
+   - Note: today that function intentionally only persists world identity.
+5. Apply it to runtime where needed:
+   - `ApplyServerPropertiesToDedicatedConfig(...)`
+   - host options in `ServerMain.cpp` (`app.SetGameHostOption(...)`)
+   - `PrintUsage()` / `ParseCommandLine()` if the key also gets a CLI override
+6. Manual verify:
+   - missing key regeneration
+   - invalid value normalization
+   - clamped ranges still make sense
+   - runtime behavior reflects the new value
+
+Normalization details worth remembering:
+- `level-id` is normalized to a safe save ID and length-limited.
+- `server-name` is capped to 16 runtime chars.
+- `max-players` is clamped to `1..8`.
+- `autosave-interval` is clamped to `5..3600`.
+- `level-type` normalizes to `default` or `flat`.
+
+### 5.3 Change Ban / Access Behavior
+
+Primary code lives in `Access/Access.cpp`, `Access/BanManager.cpp`, and `ServerLogManager.cpp`.
+
+When changing this area:
+- Keep `BanManager` responsible for storage/caching, not live-network policy.
+- Keep the clone-and-publish snapshot pattern in `Access.cpp` so readers never block on disk I/O.
+- Remember that `ban-ip <player>` depends on `ServerLogManager::TryGetConnectionRemoteIp(...)`.
+- Keep expired entries out of `SnapshotBannedPlayers()` / `SnapshotBannedIps()` output.
+- Verify:
+  - clean boot creates empty ban files when missing
+  - `ban`, `ban-ip`, `pardon`, `pardon-ip`, and `banlist` still work
+  - online bans disconnect live targets immediately
+  - manual edits still reload safely if you later add or extend reload paths
+
+### 5.4 Change World Load/Create Behavior
+
+Primary code is in `WorldManager.cpp`.
+
+Current matching policy:
+1. Match by `level-id` (`UTF8SaveFilename`) first.
+2. Fall back to world-name match on title/file name.
+
+When changing this logic:
+- Keep `ApplyWorldStorageTarget(...)` usage consistent (title + save ID together).
+- Preserve periodic ticking in wait loops (`tickProc`) to avoid async deadlocks.
+- Keep timeout/error logs specific enough for diagnosis.
+- Verify:
+  - existing world is reused correctly
+  - no accidental new save directory creation
+  - shutdown save still succeeds
+  - newly created worlds still get the explicit initial save from `ServerMain.cpp`
+
+### 5.5 Add Logging for New Feature Work
+
+Use `ServerLogger` helpers:
+- `LogDebug`, `LogInfo`, `LogWarn`, `LogError`
+- formatted variants `LogDebugf`, `LogInfof`, etc.
+
+Use `ServerLogManager` when the event is specifically part of the transport/login/disconnect lifecycle.
+
+Recommended categories:
+- `startup` for init/shutdown lifecycle
+- `world-io` for save/world operations
+- `console` for CLI command handling
+- `access` for ban/access control state
+- `network` for connection/login audit
+
+## 6. Build and Run
+
+From repository root:
+
+```powershell
+cmake -S . -B build -G "Visual Studio 17 2022" -A x64
+cmake --build build --config Debug --target MinecraftServer
+cd .\build\Debug
+.\Minecraft.Server.exe -port 25565 -bind 0.0.0.0 -maxplayers 8 -name DedicatedServer
+```
+
+Notes:
+- The process switches its working directory to the executable directory at startup.
+- `server.properties`, `banned-players.json`, and `banned-ips.json` are therefore read/written next to the executable.
+- For Visual Studio workflow, see root `COMPILE.md`.
+
+## 7. Safety Checklist Before Commit
+
+- the server starts without crash when `server.properties` is missing or sparse
+- missing access files are recreated on a clean boot
+- existing world loads by expected `level-id`
+- new world creation still performs the explicit initial save
+- CLI input and completion remain responsive
+- `banlist` output stays sane after adding/removing bans
+- no busy-wait path removed from async wait loops
+- both CMake and `.vcxproj` include newly added source files
+
+## 8. Quick Troubleshooting
+
+- Unknown command:
+  - check `RegisterDefaultCommands()` and build-file entries
+- `server.properties` or ban files seem to load from the wrong folder:
+  - remember `SetExeWorkingDirectory()` moves the working directory to the executable folder
+- Autosave or shutdown save timing out:
+  - confirm wait loops still call `TickCoreSystems()` and `HandleXuiActions()` where required
+- World not reused on restart:
+  - inspect `level-id` normalization and matching logic in `WorldManager.cpp`
+- `ban-ip <player>` cannot resolve an address:
+  - confirm the player is currently online and `ServerLogManager` has a cached remote IP for that connection
+- Settings not applied:
+  - confirm the value is loaded into `ServerPropertiesConfig`, optionally copied into `DedicatedServerConfig`, and then applied in `ServerMain.cpp`