构建、运行与扩展 MinecraftConsoles（Min…

当你需要编译、运行、配置专用服务器、联机或修改 MinecraftConsoles（Minecraft Legacy Console Edition 的 C++ 重制版）时使用。

适用场景

解决思路

1. 克隆仓库：git clone https://github.com/smartcmd/MinecraftConsoles.git 并 cd MinecraftConsoles。
2. 使用 Visual Studio 2022 构建：打开 MinecraftConsoles.sln，将启动项目设为 Minecraft.Client，配置设为 Debug（或 Release），平台设为 Windows64，按 F5 或 Ctrl+F5 构建并运行。
3. 使用 CMake 构建（Windows x64）：先运行 cmake -S . -B build -G "Visual Studio 17 2022" -A x64 配置；再运行 cmake --build build --config Debug --target MinecraftClient 构建客户端；运行 cmake --build build --config Debug --target MinecraftServer 构建专用服务器。
4. 若不想编译，可下载 Nightly Release 的 .zip，解压后直接运行 Minecraft.Client.exe。
5. 设置用户名：在可执行文件同目录创建 username.txt 并写入用户名，或使用启动参数 Minecraft.Client.exe -name Steve（可加 -fullscreen 全屏）。
6. 客户端启动参数：-name <username> 覆盖游戏内用户名；-fullscreen 以全屏模式启动。
7. 键鼠操作：W/A/S/D 移动，Space 跳跃/上升，Shift 潜行/下降，Ctrl 或双击 W 疾跑，E 打开物品栏，T 聊天，Q 丢弃物品，C 打开合成（Q/E 切换标签），左键攻击/破坏，右键使用/放置，1–9 或滚轮选择快捷栏，Esc 暂停，F11 全屏，F1 切换 HUD，F3 切换调试信息，F4 调试叠加层，F6 切换调试控制台，F5 切换 FPS/TPS 视图，Tab 玩家列表/主机选项，Enter 接受教程提示，B 拒绝教程提示。
8. LAN 联机：Windows 版自动生效——主持世界会自动在局域网广播，其他玩家通过 Join Game 菜单发现会话；TCP 端口 25565（游戏连接），UDP 端口 25566（LAN 发现）；可用 Add Server 按钮连接已知 IP；保留 uid.dat 以便改名后数据仍关联；分屏玩家也可加入 LAN/多人会话。
9. 运行专用服务器：下载 Nightly Dedicated Server 构建，直接运行 Minecraft.Server.exe -name MyServer -port 25565 -ip 0.0.0.0 -maxplayers 8 -loglevel info，或 Minecraft.Server.exe -seed 123456789。
10. 服务器 CLI 参数：-port <1-65535> 覆盖 server-port；-ip <addr> 覆盖 server-ip（绑定地址）；-bind <addr> 是 -ip 的别名；-name <name> 覆盖 server-name（最多 16 字符）；-maxplayers <1-8> 覆盖 max-players；-seed <int64> 覆盖 level-seed；-loglevel <level> 可选 debug/info/warn/error；-help/--help/-h 打印用法并退出。
11. 配置 server.properties：位于 Minecraft.Server.exe 同目录，缺失时自动生成默认值；可配置 server-name、server-port、server-ip、max-players、level-name、level-id、level-seed、world-size、log-level、white-list、lan-advertise、autosave-interval。
12. 关键属性说明：server-port 取值 1–65535 默认 25565（TCP 监听端口）；server-ip 默认 0.0.0.0（绑定地址）；server-name 默认 DedicatedServer（最多 16 字符）；max-players 取值 1–8 默认 8；level-seed 为 int64 或空（空表示随机）；world-size 可选 classic|small|medium|large 默认 classic；log-level 可选 debug|info|warn|error 默认 info；autosave-interval 取值 5–3600 默认 60（秒）；white-list 默认 false；lan-advertise 默认 false。
13. 在 Docker（Linux/Wine）中运行专用服务器：推荐从 GHCR 拉取镜像，运行 ./start-dedicated-server.sh（加 --no-pull 则不拉取），等价手动命令为 docker compose -f docker-compose.dedicated-server.ghcr.yml up -d。
14. 本地构建 Docker 模式（可选）：需本地已编译 Minecraft.Server.exe，运行 docker compose -f docker-compose.dedicated-server.yml up -d --build。
15. Docker 持久化卷：./server-data/server.properties 映射到 /srv/mc/server.properties（服务器配置）；./server-data/GameHDD 映射到 /srv/mc/Windows64/GameHDD（世界存档数据）。
16. Docker 环境变量：XVFB_DISPLAY 默认 :99（虚拟显示编号）；XVFB_SCREEN 默认 64x64x16（虚拟屏幕尺寸，Wine 需要保持很小）。
17. 添加新按键绑定：在键盘输入处理文件中用 bool isKeyPressed(int virtualKey) { return (GetAsyncKeyState(virtualKey) & 0x8000) != 0; } 检查按键状态，例如 if (isKeyPressed(VK_F7)) { myFeatureEnabled = !myFeatureEnabled; }。
18. 注册启动参数：仿照 -name/-fullscreen 模式，在 main 或 init 的参数解析循环中遍历 argv，匹配参数名后读取下一个值或设置布尔标志。
19. 读取 server.properties：用 std::ifstream 逐行读取，跳过空行和以 # 开头的注释行，按 = 分割键值存入 std::map<std::string,std::string>，再用 std::stoi 等解析具体值并带默认值回退。
20. 写入/规范化 server.properties：用 std::ofstream 按 key=value 逐行写出；规范化 level-id 时从 level-name 派生，将非字母数字且非 _ 和 - 的字符替换为下划线。
21. 排查构建失败：若缺少 Windows SDK，打开 Visual Studio Installer → 修改 → 添加 Windows 10/11 SDK，并确保平台为 Windows64（非 x86）。
22. 排查 CMake 找不到 Visual Studio 生成器：确认已安装 VS 2022，再运行 cmake -S . -B build -G "Visual Studio 17 2022" -A x64（"17 2022" 即 VS 2022 的生成器名）。
23. 排查启动后无显示或立即崩溃：确保从包含全部游戏资源的目录运行，检查 GPU 驱动是否支持所需 DirectX 版本，尝试 Debug 构建获取更详细错误输出。
24. 排查 LAN 中看不到服务器：检查防火墙是否允许 TCP 25565 和 UDP 25566；专用服务器无需 lan-advertise=true（该选项用于 LAN 广播，客户端通过 Join Game 发现）；确保客户端与服务器在同一子网。
25. 排查 Docker 服务器 Wine 无法显示：确保 XVFB_DISPLAY 环境变量与 Wine 使用的显示一致；容器使用最小的 64x64x16 虚拟帧缓冲，除非有明确理由否则不要修改。
26. 排查用户名重置/UID 问题：不要删除 uid.dat，它保存唯一玩家 ID；通过 -name 或 username.txt 改名后，已有 uid.dat 仍会将世界数据关联到你的账号。
27. 在 macOS/Linux 上通过 Wine 运行：下载 Windows nightly .zip，用 wine Minecraft.Client.exe 或 CrossOver 运行；已知存在帧时间节奏稳定性问题，非官方支持。
28. 贡献代码前先阅读 CONTRIBUTING.md：遵循现有代码风格与命名约定；未经讨论不得破坏主机版构建兼容性；安全修复始终欢迎；查看 535+ 个开放 issue 寻找适合新手的任务；加入 Discord 参与贡献者讨论。

适用边界 · 注意事项

• 仅支持 Windows（VS 2022）为完全支持平台；macOS/Linux（Wine）、Android（Wine）为社区报告可用但非官方，iOS 不支持，主机版代码存在但不再积极维护。
• Docker 本地构建模式需要本地已编译好 Minecraft.Server.exe，否则应使用 GHCR 镜像模式。
• 不要删除 uid.dat，否则会丢失玩家唯一 ID 与世界数据关联。