MinecraftConsoles (遗留主机版) 技能

技能来自 ara.so — Daily 2026 Skills 系列。

这个项目是什么

MinecraftConsoles 是 Minecraft 遗留主机版 v1.6.0560.0 (TU19) 的 C++ 重新实现/延续，目标是现代 Windows（以及通过 Wine 非官方支持 macOS/Linux）。目标包括：

• 为模组、反向移植和 LCE 开发提供多平台基础
• 提供支持键盘/鼠标和控制器的优质桌面体验
• 局域网多人游戏和专用服务器软件
• 分屏多人游戏支持

仓库： smartcmd/MinecraftConsoles
主要语言： C++
构建系统： Visual Studio 2022 解决方案 (.sln) + CMake 支持

快速开始

先决条件

• Windows（主要支持的平台）
• Visual Studio 2022 包含 C++ 桌面开发工作负载
• Git

克隆仓库

git clone https://github.com/smartcmd/MinecraftConsoles.git
cd MinecraftConsoles

使用 Visual Studio 构建

1. 在 Visual Studio 2022 中打开 MinecraftConsoles.sln
2. 将启动项目设置为 Minecraft.Client
3. 将配置设置为 Debug（或 Release），平台设置为 Windows64
4. 按 F5 或 Ctrl+F5 构建并运行

使用 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

有关其他特定平台的说明，请参阅仓库中的 COMPILE.md。

运行客户端

每日构建（无需编译）

从 Nightly Release 下载 .zip，解压，然后运行 Minecraft.Client.exe。

设置用户名

在与可执行文件相同的目录中创建 username.txt：

Steve

或使用启动参数：

Minecraft.Client.exe -name Steve
Minecraft.Client.exe -name Steve -fullscreen

客户端启动参数

键盘与鼠标控制

局域网多人游戏

局域网多人游戏在 Windows 构建上自动工作：

• 主持世界会自动在本地网络上广播
• 其他玩家通过加入游戏菜单发现会话
• TCP 端口：25565（游戏连接）
• UDP 端口：25566（局域网发现）
• 使用添加服务器按钮连接到已知 IP
• 用户名更改是安全的 — 保留 uid.dat 以在重命名时保留您的数据
• 分屏玩家可以加入局域网/多人游戏会话

专用服务器

下载每日构建服务器

Nightly Dedicated Server

直接运行 (Windows)

Minecraft.Server.exe -name MyServer -port 25565 -ip 0.0.0.0 -maxplayers 8 -loglevel info
Minecraft.Server.exe -seed 123456789

服务器 CLI 参数

server.properties 配置

位于与 Minecraft.Server.exe 相同的目录中。如果缺失，将使用默认值自动生成。

server-name=DedicatedServer
server-port=25565
server-ip=0.0.0.0
max-players=8
level-name=world
level-id=world
level-seed=
world-size=classic
log-level=info
white-list=false
lan-advertise=false
autosave-interval=60

关键属性说明：

Docker 中的专用服务器 (Linux/Wine)

推荐：从 GHCR 拉取（无需本地构建）

# 启动（自动拉取最新镜像）
./start-dedicated-server.sh

# 不拉取镜像启动
./start-dedicated-server.sh --no-pull

# 等效的手动命令
docker compose -f docker-compose.dedicated-server.ghcr.yml up -d

本地构建模式（可选）

需要本地编译的 Minecraft.Server.exe：

docker compose -f docker-compose.dedicated-server.yml up -d --build

Docker 持久卷

Docker 环境变量

项目结构（关键区域）

MinecraftConsoles/
├── MinecraftConsoles.sln       # Visual Studio 解决方案
├── CMakeLists.txt              # CMake 构建定义
├── COMPILE.md                  # 详细的编译说明
├── CONTRIBUTING.md             # 贡献者指南和项目目标
├── docker-compose.dedicated-server.ghcr.yml  # Docker (GHCR 镜像)
├── docker-compose.dedicated-server.yml       # Docker (本地构建)
├── start-dedicated-server.sh   # 快速启动脚本
├── server-data/
│   ├── server.properties       # 服务器配置（自动生成）
│   └── GameHDD/                # 世界保存数据
└── .github/
    └── banner.png

此代码库中的常见 C++ 模式

添加新的按键绑定（键盘输入）

该项目在原始仅控制器代码的基础上添加了键盘/鼠标支持。扩展输入时：

// 在输入处理程序中检查按键状态的典型模式
// 找到键盘输入处理文件并添加按键检查：

bool isKeyPressed(int virtualKey) {
    return (GetAsyncKeyState(virtualKey) & 0x8000) != 0;
}

// 示例：添加一个新的切换键
if (isKeyPressed(VK_F7)) {
    // 切换你的功能
    myFeatureEnabled = !myFeatureEnabled;
}

注册启动参数

遵循现有的 -name / -fullscreen 模式：

// 在参数解析部分（通常在 main 或 init 中）：
for (int i = 1; i < argc; i++) {
    std::string arg = argv[i];

    if (arg == "-name" && i + 1 < argc) {
        username = argv[++i];
    }
    else if (arg == "-fullscreen") {
        launchFullscreen = true;
    }
    // 添加你的参数：
    else if (arg == "-myoption" && i + 1 < argc) {
        myOption = argv[++i];
    }
}

读取 server.properties

#include <fstream>
#include <sstream>
#include <map>
#include <string>

std::map<std::string, std::string> loadServerProperties(const std::string& path) {
    std::map<std::string, std::string> props;
    std::ifstream file(path);
    std::string line;

    while (std::getline(file, line)) {
        if (line.empty() || line[0] == '#') continue;
        auto eq = line.find('=');
        if (eq == std::string::npos) continue;
        std::string key = line.substr(0, eq);
        std::string val = line.substr(eq + 1);
        props[key] = val;
    }
    return props;
}

// 用法：
auto props = loadServerProperties("server.properties");
int port = std::stoi(props.count("server-port") ? props["server-port"] : "25565");
std::string serverName = props.count("server-name") ? props["server-name"] : "DedicatedServer";

写入 server.properties（规范化/自动生成）

void writeServerProperties(const std::string& path,
                            const std::map<std::string, std::string>& props) {
    std::ofstream file(path);
    for (auto& [key, val] : props) {
        file << key << "=" << val << "\n";
    }
}

// 从 level-name 规范化 level-id
std::string normalizeLevelId(const std::string& levelName) {
    std::string id = levelName;
    // 移除不安全字符，转换为小写，空格替换为下划线
    for (char& c : id) {
        if (!std::isalnum(c) && c != '_' && c != '-') c = '_';
    }
    return id;
}

故障排除

构建失败：缺少 Windows SDK

• 打开 Visual Studio Installer → 修改 → 添加 Windows 10/11 SDK
• 确保平台设置为 Windows64（而不是 x86）

CMake 找不到 Visual Studio 生成器

# 确认 VS 2022 已安装，然后：
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
# "17 2022" 是 VS 2022 的生成器名称

游戏启动但没有显示 / 立即崩溃

• 确保从包含所有游戏资源的目录运行
• 检查您的 GPU 驱动程序是否支持所需的 DirectX 版本
• 尝试 Debug 构建以获得更详细的错误输出

服务器在局域网上不可见

• 检查防火墙规则是否允许 TCP 25565 和 UDP 25566
• 对于专用服务器，确认 lan-advertise=true 不是必需的（它用于局域网广播；客户端通过加入游戏发现）
• 确保客户端和服务器在同一子网中

Docker 服务器：Wine 无法显示

• XVFB_DISPLAY 环境变量必须与 Wine 使用的匹配
• 容器使用最小的 64x64x16 虚拟帧缓冲区 — 除非有特殊原因，否则不要更改

用户名重置 / UID 问题

• 不要删除 uid.dat — 它存储您的唯一玩家 ID
• 如果您通过 -name 或 username.txt 重命名自己，您现有的 uid.dat 会将世界数据与您的账户关联起来

macOS / Linux (Wine)

• 下载 Windows 每日构建 .zip
• 通过 wine Minecraft.Client.exe 或 CrossOver 运行
• 稳定性问题（帧时间节奏）是已知的并由社区报告；非官方支持

贡献

在提交 PR 之前，请阅读 CONTRIBUTING.md。要点：

• 遵循现有的代码风格和命名约定
• 未经讨论，不应破坏控制台构建兼容性
• 始终欢迎安全修复
• 查看未解决的问题（535+）以找到适合初学者的任务
• 加入 Discord 进行贡献者讨论

平台支持摘要