From 891052e208f45c072cdecd68c136df77ea1a9abc Mon Sep 17 00:00:00 2001
From: kuwacom <kuwa.com3@gmail.com>
Date: Sat, 7 Mar 2026 20:18:35 +0900
Subject: [PATCH] add: create `Minecraft.Server` developer guide in English and
 Japanese

---
 Minecraft.Server/docs/DEVELOPMENT.en.md | 176 +++++++++++++++++++++++
 Minecraft.Server/docs/DEVELOPMENT.ja.md | 177 ++++++++++++++++++++++++
 2 files changed, 353 insertions(+)
 create mode 100644 Minecraft.Server/docs/DEVELOPMENT.en.md
 create mode 100644 Minecraft.Server/docs/DEVELOPMENT.ja.md

diff --git a/Minecraft.Server/docs/DEVELOPMENT.en.md b/Minecraft.Server/docs/DEVELOPMENT.en.md
new file mode 100644
index 000000000..26ad0a86c
--- /dev/null
+++ b/Minecraft.Server/docs/DEVELOPMENT.en.md
@@ -0,0 +1,176 @@
+# 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:
+- Read and normalize `server.properties`
+- Initialize Windows/network/runtime systems
+- Load or create the target world
+- Run the dedicated main loop (network tick, XUI actions, autosave, CLI command processing)
+- Perform safe save and shutdown
+
+## 2. Important Files
+
+### Startup and Runtime
+- `Windows64/ServerMain.cpp`
+  - Process entry (`main`)
+  - CLI argument parsing
+  - Runtime setup and shutdown flow
+  - Main loop + autosave scheduler
+
+### 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
+  - Parse/normalize/write `server.properties`
+  - Exposes `ServerPropertiesConfig`
+
+### Logging
+- `ServerLogger.h`
+- `ServerLogger.cpp`
+  - Log level parsing
+  - Colored/timestamped console logs
+  - Standard categories (`startup`, `world-io`, `console`, etc.)
+
+### 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. Load `server.properties` via `LoadServerPropertiesConfig()`
+2. Apply CLI argument overrides (`-port`, `-bind`, `-name`, `-seed`, `-loglevel`)
+3. Initialize runtime systems (window/device/profile/network/thread storage)
+4. Set host/game options from `ServerPropertiesConfig`
+5. Bootstrap world with `BootstrapWorldForServer(...)`
+6. Start hosted game thread (`RunNetworkGameThreadProc`)
+7. Enter main loop:
+   - `TickCoreSystems()`
+   - `HandleXuiActions()`
+   - `serverCli.Poll()`
+   - autosave scheduling
+8. On shutdown:
+   - wait for action idle
+   - request final save
+   - halt server and terminate network/device subsystems
+
+## 4. Common Development Tasks
+
+### 4.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 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 behavior is correct for both `cmd` and `/cmd`
+
+Implementation references:
+- `CliCommandHelp.cpp` for simple no-arg command
+- `CliCommandTp.cpp` for multi-arg + completion + runtime checks
+- `CliCommandGamemode.cpp` for argument parsing and mode validation
+
+### 4.2 Add or Change a `server.properties` Key
+
+1. Add/update field in `ServerPropertiesConfig` (`ServerProperties.h`)
+2. Add default value to `kServerPropertyDefaults` (`ServerProperties.cpp`)
+3. Load and normalize value in `LoadServerPropertiesConfig()`
+   - Use existing read helpers for bool/int/string/int64/log level
+4. If this value should be persisted on save, update `SaveServerPropertiesConfig()`
+5. Apply to runtime where needed:
+   - `ApplyServerPropertiesToDedicatedConfig(...)`
+   - host options in `ServerMain.cpp` (`app.SetGameHostOption(...)`)
+6. Manual verify:
+   - file regeneration when key is missing
+   - invalid values are normalized
+   - runtime behavior reflects the new value
+
+### 4.3 Change World Load/Create Behavior
+
+Primary code is in `WorldManager.cpp`.
+
+Current matching policy:
+1. Match by `level-id` (`UTF8SaveFilename`) first
+2. Fallback 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
+
+### 4.4 Add Logging for New Feature Work
+
+Use `ServerLogger` helpers:
+- `LogDebug`, `LogInfo`, `LogWarn`, `LogError`
+- or formatted variants `LogInfof`, etc.
+
+Recommended categories:
+- `startup` for init/shutdown lifecycle
+- `world-io` for save/world operations
+- `console` for CLI command handling
+
+## 5. 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 -name DedicatedServer
+```
+
+Notes:
+- Launch from output directory so relative assets/files resolve correctly
+- `server.properties` is loaded from current working directory
+- For Visual Studio workflow, see root `COMPILE.md`
+
+## 6. Safety Checklist Before Commit
+
+- The server starts without crash on a clean `server.properties`
+- Existing world loads by expected `level-id`
+- New world creation path still performs initial save
+- CLI still accepts input and completion is responsive
+- No busy wait path removed from async wait loops
+- Both CMake and `.vcxproj` include newly added source files
+
+## 7. Quick Troubleshooting
+
+- Unknown command not found:
+  - check `RegisterDefaultCommands()` and build-file entries
+- 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`
+- Settings not applied:
+  - confirm value is loaded into `ServerPropertiesConfig` and then applied in `ServerMain.cpp`
diff --git a/Minecraft.Server/docs/DEVELOPMENT.ja.md b/Minecraft.Server/docs/DEVELOPMENT.ja.md
new file mode 100644
index 000000000..c20f53f5e
--- /dev/null
+++ b/Minecraft.Server/docs/DEVELOPMENT.ja.md
@@ -0,0 +1,177 @@
+# Minecraft.Server 開発ガイド (日本語)
+
+このドキュメントは、`Minecraft.Server` の内部構成を知らない人でも、機能追加や修正を安全に進められるようにまとめた実践ガイドです。
+
+## 1. Minecraft.Server の役割
+
+`Minecraft.Server` は本リポジトリの Dedicated Server 実行エントリです。
+
+主な責務:
+- `server.properties` の読み込みと正規化
+- Windows/Network/Runtime の初期化
+- ワールドのロードまたは新規作成
+- メインループ実行 (ネットワーク進行、XUIアクション、オートセーブ、CLI処理)
+- 安全な保存とシャットダウン
+
+## 2. 重要ファイル
+
+### 起動と実行ループ
+- `Windows64/ServerMain.cpp`
+  - エントリポイント `main`
+  - 引数パース
+  - 初期化から終了までの実行フロー
+  - メインループとオートセーブ
+
+### ワールド選択とセーブ読み込み
+- `WorldManager.h`
+- `WorldManager.cpp`
+  - `level-id` 優先でセーブ探索
+  - 見つからない場合は world 名でフォールバック
+  - 非同期完了待機ヘルパー
+
+### サーバー設定
+- `ServerProperties.h`
+- `ServerProperties.cpp`
+  - 既定値定義
+  - `server.properties` のパース/正規化/保存
+  - `ServerPropertiesConfig` の提供
+
+### ログ出力
+- `ServerLogger.h`
+- `ServerLogger.cpp`
+  - ログレベル解釈
+  - タイムスタンプ付き色付きログ
+  - カテゴリ別ログ (`startup`, `world-io`, `console`)
+
+### コンソールコマンド
+- `Console/ServerCli.cpp` (ファサード)
+- `Console/ServerCliInput.cpp` (linenoise 入力スレッド)
+- `Console/ServerCliParser.cpp` (トークン分解、クォート、補完コンテキスト)
+- `Console/ServerCliEngine.cpp` (実行ディスパッチ、補完、共通ヘルパー)
+- `Console/ServerCliRegistry.cpp` (登録と名前解決)
+- `Console/commands/*` (各コマンド実装)
+
+## 3. 起動フロー全体
+
+`Windows64/ServerMain.cpp` の流れ:
+1. `LoadServerPropertiesConfig()` で設定読込
+2. CLI 引数で上書き (`-port`, `-bind`, `-name`, `-seed`, `-loglevel`)
+3. 各サブシステム初期化 (window/device/profile/network/thread storage)
+4. `ServerPropertiesConfig` をゲームホスト設定へ反映
+5. `BootstrapWorldForServer(...)` でワールド決定
+6. `RunNetworkGameThreadProc` でサーバーゲーム開始
+7. メインループ:
+   - `TickCoreSystems()`
+   - `HandleXuiActions()`
+   - `serverCli.Poll()`
+   - オートセーブスケジュール
+8. 終了時:
+   - Action Idle 待機
+   - 最終保存要求
+   - サーバー停止と各サブシステム終了
+
+## 4. よくある開発作業
+
+### 4.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` (`<ClCompile>`, `<ClInclude>`)
+5. 手動確認
+   - `help` に表示される
+   - 実行が期待通り
+   - 補完が `cmd` と `/cmd` の両方で動く
+
+参考実装:
+- `CliCommandHelp.cpp` (単純コマンド)
+- `CliCommandTp.cpp` (複数引数 + 補完 + 実行時チェック)
+- `CliCommandGamemode.cpp` (引数解釈 + モード検証)
+
+### 4.2 `server.properties` キーを追加/変更する
+
+1. `ServerProperties.h` の `ServerPropertiesConfig` にフィールド追加
+2. `ServerProperties.cpp` の `kServerPropertyDefaults` に既定値追加
+3. `LoadServerPropertiesConfig()` で読み込みと正規化を実装
+   - 既存の read helper を利用 (bool/int/string/int64/log level)
+4. 保存時に維持したい値なら `SaveServerPropertiesConfig()` も更新
+5. 実行時反映箇所を更新
+   - `ApplyServerPropertiesToDedicatedConfig(...)`
+   - `ServerMain.cpp` の `app.SetGameHostOption(...)` など
+6. 手動確認
+   - キー欠損時の自動補完
+   - 不正値の正規化
+   - 実行時挙動への反映
+
+### 4.3 ワールドロード/新規作成ロジックを変更する
+
+主な実装は `WorldManager.cpp` にあります。
+
+現在の探索ポリシー:
+1. `level-id` (`UTF8SaveFilename`) 完全一致を優先
+2. 失敗時に world 名一致へフォールバック
+
+変更時の注意:
+- `ApplyWorldStorageTarget(...)` で title と save ID を常にセットで扱う
+- 待機ループで `tickProc` を回し続ける
+  - これを止めると非同期進行が止まり、タイムアウトしやすくなる
+- タイムアウトや失敗ログは具体的に残す
+- 確認項目
+  - 既存ワールドを正しく再利用できるか
+  - 意図しない新規セーブ先が増えていないか
+  - 終了時保存が成功するか
+
+### 4.4 ログを追加する
+
+`ServerLogger` の API を利用:
+- `LogDebug`, `LogInfo`, `LogWarn`, `LogError`
+- フォーマット付きは `LogInfof` など
+
+カテゴリ指針:
+- `startup`: 起動/終了手順
+- `world-io`: ワールドと保存処理
+- `console`: CLI 入出力とコマンド処理
+
+## 5. ビルドと実行
+
+リポジトリルートで実行:
+
+```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` はカレントディレクトリから読み込まれる
+- Visual Studio の運用はルートの `COMPILE.md` を参照
+
+## 6. 変更前チェックリスト
+
+- `server.properties` が空または欠損でも起動できる
+- 既存ワールドが期待した `level-id` でロードされる
+- 新規ワールド作成時の初回保存が実行される
+- CLI 入力と補完が正常に動く
+- 非同期待機ループから `TickCoreSystems()` などを消していない
+- 新規追加したソースが CMake と `.vcxproj` の両方に入っている
+
+## 7. トラブルシュート
+
+- コマンドが認識されない:
+  - `RegisterDefaultCommands()` とビルド定義を確認
+- オートセーブ/終了時保存がタイムアウトする:
+  - 待機中に `TickCoreSystems()` と `HandleXuiActions()` を回しているか確認
+- 再起動時に同じワールドを使わない:
+  - `level-id` の正規化と `WorldManager.cpp` の一致判定を確認
+- 設定変更が効かない:
+  - `ServerPropertiesConfig` へのロードと `ServerMain.cpp` の反映経路を確認