From f483074cd2ff2cc9e9c3ef1df4430d4a65d1fb2a Mon Sep 17 00:00:00 2001 From: kuwa Date: Sun, 15 Mar 2026 16:32:50 +0900 Subject: Dedicated Server Software - Minecraft.Server.exe (#498) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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> --- Minecraft.Server/docs/DEVELOPMENT.en.md | 284 ++++++++++++++++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 Minecraft.Server/docs/DEVELOPMENT.en.md (limited to 'Minecraft.Server/docs/DEVELOPMENT.en.md') 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 ` + +### 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 ` or `-bind ` +- `-name ` (runtime max 16 chars) +- `-maxplayers <1-8>` +- `-seed ` +- `-loglevel ` +- `-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 [reason ...]` + - currently requires the target player to be online +- `ban-ip [reason ...]` + - accepts a literal IPv4/IPv6 address or an online player's current remote IP +- `pardon ` +- `pardon-ip
` + - only accepts a literal address +- `banlist` +- `tp ` / `teleport` +- `gamemode [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` (`` / ``) +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 ` 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 ` 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` -- cgit v1.2.3