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.ja.md | 286 ++++++++++++++++++++++++++++++++ 1 file changed, 286 insertions(+) create mode 100644 Minecraft.Server/docs/DEVELOPMENT.ja.md (limited to 'Minecraft.Server/docs/DEVELOPMENT.ja.md') diff --git a/Minecraft.Server/docs/DEVELOPMENT.ja.md b/Minecraft.Server/docs/DEVELOPMENT.ja.md new file mode 100644 index 00000000..70d05aaa --- /dev/null +++ b/Minecraft.Server/docs/DEVELOPMENT.ja.md @@ -0,0 +1,286 @@ +# Minecraft.Server 開発ガイド (日本語) + +この文書は、`Minecraft.Server` に新しく入る開発者が、安全に機能追加や改修を行うための実践的な地図として使うことを想定しています + +## 1. このサーバーが担うこと + +`Minecraft.Server` は、このコードベースにおける専用サーバー実行ファイルのエントリーポイントです + +主な責務: +- 相対パスのファイル I/O を行う前に、カレントディレクトリを実行ファイルのあるフォルダへ切り替える +- `server.properties` を読み込み、正規化し、不足や不正値を補完する +- 専用サーバー向けランタイム、接続ログ、アクセス制御を初期化する +- 対象ワールドをロードまたは新規作成し、実際のセーブ先と `level-id` を整合させる +- 専用サーバーのメインループを回す (network tick, XUI actions, autosave, CLI input) +- `banned-players.json` や `banned-ips.json` など運用向けファイルを維持する +- 新規ワールドの初回保存を実行し、その後安全にシャットダウンする + +## 2. 重要ファイル + +### 起動とランタイム +- `Windows64/ServerMain.cpp` + - `PrintUsage()` と `ParseCommandLine()` + - `SetExeWorkingDirectory()` + - 起動/終了フロー + - 新規ワールド初回保存の経路 + - メインループ、オートセーブ、CLI ポーリング + +### ワールド選択とセーブ読込 +- `WorldManager.h` +- `WorldManager.cpp` + - `level-id` 優先、その後 world 名フォールバックでセーブ探索 + - storage title と save ID を常にセットで適用 + - 非同期 storage/server action 完了待ちの helper を提供 + +### サーバー設定 +- `ServerProperties.h` +- `ServerProperties.cpp` + - 既定値と正規化レンジ + - `server.properties` の読込/補修/書込 + - `ServerPropertiesConfig` の提供 + - `SaveServerPropertiesConfig()` は `level-name` / `level-id` / `white-list` を書き換える + +### アクセス制御と BAN / Whitelist 永続化 +- `Access/Access.h` +- `Access/Access.cpp` + - プロセス全体で使うアクセス制御 facade + - コンソールコマンドとログイン判定から参照される公開スナップショット管理 +- `Access/BanManager.h` +- `Access/BanManager.cpp` + - `banned-players.json` と `banned-ips.json` の読込/書込 + - 識別子の正規化と、期限切れエントリを除いた snapshot 出力 +- `Access/WhitelistManager.h` +- `Access/WhitelistManager.cpp` + - `whitelist.json` の読込/書込 + - ログイン判定と CLI で使う XUID whitelist の正規化管理 + +### ログと接続監査 +- `ServerLogger.h` +- `ServerLogger.cpp` + - ログレベル解釈 + - 色付き/タイムスタンプ付きコンソールログ + - `startup`, `world-io`, `console`, `access`, `network`, `shutdown` などのカテゴリ +- `ServerLogManager.h` +- `ServerLogManager.cpp` + - TCP 接続 accept/reject ログ + - ログイン/切断の監査ログ + - `ban-ip ` が使う remote IP キャッシュ + +### コンソールコマンドシステム +- `Console/ServerCli.cpp` (facade) +- `Console/ServerCliInput.cpp` (linenoise 入力スレッド + completion bridge) +- `Console/ServerCliParser.cpp` (トークン分解、クォート、補完コンテキスト) +- `Console/ServerCliEngine.cpp` (実行ディスパッチ、補完、共通ヘルパー) +- `Console/ServerCliRegistry.cpp` (登録と名前解決) +- `Console/commands/*` (各コマンド実装) + +## 3. 起動フロー全体 + +`Windows64/ServerMain.cpp` の主な流れ: +1. `SetExeWorkingDirectory()` でカレントディレクトリを実行ファイルのフォルダへ切り替える +2. `LoadServerPropertiesConfig()` で `server.properties` を読み込み、正規化する +3. `DedicatedServerConfig` へ反映したあと、CLI 引数で上書きする (`-port`, `-ip`/`-bind`, `-name`, `-maxplayers`, `-seed`, `-loglevel`, `-help`/`--help`/`-h`) +4. プロセス状態、`ServerLogManager`、`Access::Initialize(".")` を初期化する +5. window/device/profile/network/thread-local 系を初期化する +6. `ServerPropertiesConfig` をゲームホスト設定へ反映する +7. `BootstrapWorldForServer(...)` でワールドを決定する +8. 読み込まれたセーブ ID が正規化後に変わった場合は、`SaveServerPropertiesConfig()` で書き戻す +9. `RunNetworkGameThreadProc` でホストゲームスレッドを起動する +10. 新規ワールドが作成された場合は、専用サーバー側で明示的に初回保存を要求する +11. メインループに入る: + - `TickCoreSystems()` + - `HandleXuiActions()` + - `serverCli.Poll()` + - オートセーブスケジュール +12. 終了時: + - CLI 入力を停止 + - save-on-exit を要求してサーバー停止 + - ネットワーク停止完了を待機 + - ログ/アクセス制御/ネットワーク/デバイスを終了 + +## 4. 現在の運用インターフェース + +### 4.1 起動引数 +- `-port <1-65535>` +- `-ip ` または `-bind ` +- `-name ` (実行時上限 16 文字) +- `-maxplayers <1-8>` +- `-seed ` +- `-loglevel ` +- `-help`, `--help`, `-h` + +補足: +- CLI による上書きは、その起動中のプロセスにだけ効きます +- 現在サーバーが書き戻す値は `level-name` と `level-id` だけで、ワールド解決時に識別情報が変わった場合に限られます + +### 4.2 組み込みコンソールコマンド +- `help` / `?` +- `stop` +- `list` +- `ban [reason ...]` + - 現状では対象プレイヤーがオンラインである必要があります +- `ban-ip [reason ...]` + - リテラル IPv4/IPv6 か、オンラインプレイヤーの現在 IP を対象にできます +- `pardon ` +- `pardon-ip
` + - リテラルアドレスのみ受け付けます +- `banlist` +- `tp ` / `teleport` +- `gamemode [player]` / `gm` + +CLI 挙動の補足: +- `cmd` と `/cmd` の両方を受け付けます +- `ServerCliParser` により引用符付き引数を扱えます +- 補完は各コマンドの `Complete(...)` で実装します + +### 4.3 実行ファイル横に書かれるファイル +- `server.properties` +- `banned-players.json` +- `banned-ips.json` + +これは `SetExeWorkingDirectory()` による挙動ですつまり、これらのファイルはシェル上の起動場所ではなく `Minecraft.Server.exe` 基準で解決されます + +## 5. よくある開発作業 + +### 5.1 CLI コマンドを追加する + +`/kick` や `/time` のようなコマンド追加時の基本手順: + +1. `Console/commands/` にファイルを追加 + - `CliCommandYourCommand.h` + - `CliCommandYourCommand.cpp` +2. `IServerCliCommand` を実装 + - `Name()`, `Usage()`, `Description()`, `Execute(...)` + - 必要なら `Aliases()` と `Complete(...)` +3. `ServerCliEngine::RegisterDefaultCommands()` に登録する +4. ビルド定義に追加する + - `CMakeLists.txt` (`MINECRAFT_SERVER_SOURCES`) + - `Minecraft.Server/Minecraft.Server.vcxproj` (`` / ``) +5. 手動確認 + - `help` に表示される + - 実行結果が期待通り + - 補完が `cmd` と `/cmd` の両方で動く + - 引用符付き引数が期待通り処理される + +参考実装: +- `CliCommandHelp.cpp` (単純コマンド) +- `CliCommandTp.cpp` (複数引数 + 補完 + 実行時チェック) +- `CliCommandGamemode.cpp` (引数解釈 + エイリアス) +- `CliCommandBanIp.cpp` (接続メタデータを使うアクセス制御系コマンド) + +### 5.2 `server.properties` キーを追加/変更する + +1. `ServerProperties.h` の `ServerPropertiesConfig` にフィールドを追加/更新する +2. `ServerProperties.cpp` の `kServerPropertyDefaults` に既定値を追加する +3. `LoadServerPropertiesConfig()` で読み込みと正規化を実装する + - bool/int/string/int64/log level/level type 用の既存 helper を使う +4. 書き戻し対象にしたいなら `SaveServerPropertiesConfig()` を更新する + - ただし現状この関数は、意図的にワールド識別情報だけを永続化します +5. 実行時反映箇所を更新する: + - `ApplyServerPropertiesToDedicatedConfig(...)` + - `ServerMain.cpp` の `app.SetGameHostOption(...)` + - CLI 上書きも持たせるなら `PrintUsage()` / `ParseCommandLine()` +6. 手動確認: + - 欠損キーの自動補完 + - 不正値の正規化 + - clamp 範囲が妥当か + - 実行時挙動に反映されるか + +> 覚えておくと良い正規化ポイント +- `level-id` は安全な save ID に正規化され、長さ制限も掛かる +- `server-name` は実行時 16 文字まで +- `max-players` は `1..8` に clamp される(あとで増やす必要あり) +- `autosave-interval` は `5..3600` に clamp される +- `level-type` は `default` または `flat` に正規化される + +### 5.3 BAN / アクセス制御挙動を変更する + +主な実装は `Access/Access.cpp`, `Access/BanManager.cpp`, `ServerLogManager.cpp` にあります + +変更時の注意: +- `BanManager` は storage/caching に責務を寄せ、 live-network policy を持ち込みすぎない +- `Access.cpp` の clone-and-publish スナップショット方式を保ち、読取側がディスク I/O で止まらないようにする +- `ban-ip ` は `ServerLogManager::TryGetConnectionRemoteIp(...)` に依存することを忘れない +- `SnapshotBannedPlayers()` / `SnapshotBannedIps()` には期限切れエントリを混ぜない +- 確認項目: + - 欠損時に空の BAN ファイルが初回起動で生成される + - `ban`, `ban-ip`, `pardon`, `pardon-ip`, `banlist` が動く + - オンライン対象の BAN が即時切断まで到達する + - 将来 reload 経路を増やしても手動編集が安全に再読込できる + +### 5.4 ワールドロード/新規作成ロジックを変更する + +主な実装は `WorldManager.cpp` にあります + +現在の探索ポリシー: +1. `level-id` (`UTF8SaveFilename`) 完全一致を優先 +2. 失敗時に world 名一致へフォールバック + +変更時の注意: +- `ApplyWorldStorageTarget(...)` で title と save ID を常にセットで扱う +- 待機ループで `tickProc` を回し続ける + - これを止めると非同期進行が止まり、タイムアウトしやすくなる +- タイムアウトや失敗ログは具体的に残す +- 確認項目 + - 既存ワールドを正しく再利用できるか + - 意図しない新規セーブ先が増えていないか + - 終了時保存が成功するか + - 新規ワールド時の明示的初回保存が `ServerMain.cpp` から維持されているか + +### 5.5 ログを追加する + +`ServerLogger` の API を利用: +- `LogDebug`, `LogInfo`, `LogWarn`, `LogError` +- フォーマット付きは `LogDebugf`, `LogInfof` など + +transport/login/disconnect ライフサイクルに属するイベントなら `ServerLogManager` 側を使います + +推奨カテゴリ: +- `startup`: 起動ライフサイクル +- `shutdown`: 停止ライフサイクル +- `world-io`: ワールド/保存処理 +- `console`: CLI コマンド処理 +- `access`: BAN/アクセス制御状態 +- `network`: 接続/ログイン監査 + +## 6. ビルドと実行 + +リポジトリルートで実行: + +```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 -name DedicatedServer +``` + +補足: +- プロセスは起動時にカレントディレクトリを実行ファイルの場所へ切り替えます +- `server.properties`, `banned-players.json`, `banned-ips.json` はそのため実行ファイル横に読み書きされます +- Visual Studio ワークフローはルートの `COMPILE.md` を参照してください + +## 7. 変更前チェックリスト + +- `server.properties` が欠損または疎でもクラッシュせず起動できる +- 欠損したアクセス制御ファイルがクリーンブート時に再生成される +- 既存ワールドが期待した `level-id` でロードされる +- 新規ワールド作成時の明示的初回保存が維持される +- CLI 入力と補完が引き続き応答する +- `banlist` 出力が BAN 追加/解除後も破綻しない +- 非同期待機ループから `TickCoreSystems()` など busy-wait 防止用ティックを消していない +- 新規追加したソースが CMake と `.vcxproj` の両方に入っている + +## 8. クイックトラブルシュート + +- コマンドが認識されない: + - `RegisterDefaultCommands()` とビルド定義を確認する +- `server.properties` や BAN ファイルの読込先が想定と違う: + - `SetExeWorkingDirectory()` により実行ファイルのフォルダへ移動していることを確認する +- オートセーブ/終了時保存がタイムアウトする: + - 待機ループ内で `TickCoreSystems()` と `HandleXuiActions()` を回しているか確認する +- 再起動時に同じワールドを使わない: + - `level-id` の正規化と `WorldManager.cpp` の一致判定を確認する +- `ban-ip ` で IP を解決できない: + - 対象プレイヤーがオンラインで、`ServerLogManager` に接続 IP がキャッシュされているか確認する +- 設定変更が効かない: + - 値が `ServerPropertiesConfig` にロードされ、必要なら `DedicatedServerConfig` にコピーされ、その後 `ServerMain.cpp` で反映されているか確認する -- cgit v1.2.3