minecraftconsoles-lce

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MinecraftConsoles (Legacy Console Edition) Skill

MinecraftConsoles(Legacy主机版)技能

Skill by ara.so — Daily 2026 Skills collection.
ara.so提供的技能——属于2026每日技能合集。

What This Project Is

项目介绍

MinecraftConsoles is a C++ reimplementation/continuation of Minecraft Legacy Console Edition v1.6.0560.0 (TU19), targeting modern Windows (and unofficially macOS/Linux via Wine). Goals include:
  • Multi-platform base for modding, backports, and LCE development
  • Quality desktop experience with keyboard/mouse and controller support
  • LAN multiplayer and dedicated server software
  • Splitscreen multiplayer support
Repository:
smartcmd/MinecraftConsoles

Primary language: C++
Build system: Visual Studio 2022 solution (
.sln
) + CMake support

MinecraftConsoles是**Minecraft Legacy Console Edition v1.6.0560.0(TU19)**的C++重实现/续作,目标平台为现代Windows(非官方支持通过Wine在macOS/Linux运行)。项目目标包括:
  • 为模组开发、版本回退和LCE开发提供多平台基础
  • 支持键盘/鼠标和控制器的优质桌面体验
  • 局域网多人游戏和专用服务器软件
  • 分屏多人游戏支持
代码仓库:
smartcmd/MinecraftConsoles

主要开发语言: C++
构建系统: Visual Studio 2022解决方案(
.sln
)+ CMake支持

Quick Start

快速开始

Prerequisites

前置要求

  • Windows(主要支持平台)
  • 安装带C++桌面开发 workload的Visual Studio 2022
  • Git

Clone

克隆仓库

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

Build with Visual Studio

使用Visual Studio构建

  1. Open
    MinecraftConsoles.sln
    in Visual Studio 2022
  2. Set Startup Project to
    Minecraft.Client
  3. Set configuration to Debug (or Release), platform to Windows64
  4. Press F5 or Ctrl+F5 to build and run
  1. 在Visual Studio 2022中打开
    MinecraftConsoles.sln
  2. 启动项目设置为
    Minecraft.Client
  3. 将配置设置为Debug(或Release),平台设置为Windows64
  4. F5Ctrl+F5构建并运行

Build with CMake (Windows x64)

使用CMake构建(Windows x64)

powershell
undefined
powershell
undefined

Configure

配置

cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake -S . -B build -G "Visual Studio 17 2022" -A x64

Build the client

构建客户端

cmake --build build --config Debug --target MinecraftClient
cmake --build build --config Debug --target MinecraftClient

Build the dedicated server

构建专用服务器

cmake --build build --config Debug --target MinecraftServer

See `COMPILE.md` in the repo for additional platform-specific notes.

---
cmake --build build --config Debug --target MinecraftServer

如需更多平台相关说明,请查看仓库中的`COMPILE.md`文件。

---

Running the Client

运行客户端

Nightly Build (No Compile Needed)

夜间构建版本(无需编译)

Download the
.zip
from the Nightly Release, extract, and run
Minecraft.Client.exe
.
Nightly Release下载
.zip
文件,解压后运行
Minecraft.Client.exe

Setting Your Username

设置用户名

Create
username.txt
in the same directory as the executable:
Steve
Or use a launch argument:
powershell
Minecraft.Client.exe -name Steve
Minecraft.Client.exe -name Steve -fullscreen
在可执行文件的同一目录下创建
username.txt
文件:
Steve
或使用启动参数:
powershell
Minecraft.Client.exe -name Steve
Minecraft.Client.exe -name Steve -fullscreen

Client Launch Arguments

客户端启动参数

ArgumentDescription
-name <username>
Override in-game username
-fullscreen
Launch in fullscreen mode

参数描述
-name <username>
覆盖游戏内用户名
-fullscreen
全屏启动

Keyboard & Mouse Controls

键盘和鼠标控制

ActionKey/Button
Move
W
A
S
D
Jump / Fly Up
Space
Sneak / Fly Down
Shift
(hold)
Sprint
Ctrl
(hold) or double-tap
W
Inventory
E
Chat
T
Drop Item
Q
Crafting
C
(tabs:
Q
/
E
)
Attack / DestroyLeft Click
Use / PlaceRight Click
Select hotbar slot
1
9
or Mouse Wheel
Pause
Esc
Fullscreen
F11
Toggle HUD
F1
Toggle Debug Info
F3
Debug Overlay
F4
Toggle Debug Console
F6
Toggle FPS/TPS view
F5
Player list / Host Options
Tab
Accept tutorial hint
Enter
Decline tutorial hint
B

操作按键/按钮
移动
W
A
S
D
跳跃 / 向上飞行
Space
潜行 / 向下飞行按住
Shift
sprint按住
Ctrl
或双击
W
打开背包
E
打开聊天框
T
丢弃物品
Q
打开合成界面
C
(切换标签:
Q
/
E
攻击 / 破坏方块鼠标左键
使用 / 放置方块鼠标右键
选择快捷栏物品
1
9
或鼠标滚轮
暂停游戏
Esc
切换全屏
F11
隐藏/显示HUD
F1
切换调试信息
F3
调试 overlay
F4
切换调试控制台
F6
切换FPS/TPS显示
F5
玩家列表 / 主机选项
Tab
接受教程提示
Enter
拒绝教程提示
B

LAN Multiplayer

局域网多人游戏

LAN multiplayer works automatically on the Windows build:
  • Hosting a world auto-advertises it on the local network
  • Other players discover sessions via Join Game menu
  • TCP port: 25565 (game connections)
  • UDP port: 25566 (LAN discovery)
  • Use the Add Server button to connect to known IPs
  • Username changes are safe — keep
    uid.dat
    to preserve your data across renames
  • Splitscreen players can join LAN/multiplayer sessions

Windows版本的局域网多人游戏可自动运行:
  • 托管世界会自动在本地网络中广播
  • 其他玩家可通过加入游戏菜单发现会话
  • TCP端口:25565(游戏连接)
  • UDP端口:25566(局域网发现)
  • 使用添加服务器按钮连接已知IP
  • 用户名修改是安全的——保留
    uid.dat
    可在重命名时保留你的数据
  • 分屏玩家可加入局域网/多人游戏会话

Dedicated Server

专用服务器

Download Nightly Server Build

下载夜间服务器构建版本

Run Directly (Windows)

直接运行(Windows)

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

Server CLI Arguments

服务器CLI参数

ArgumentDescription
-port <1-65535>
Override
server-port
-ip <addr>
Override
server-ip
(bind address)
-bind <addr>
Alias of
-ip
-name <name>
Override
server-name
(max 16 chars)
-maxplayers <1-8>
Override
max-players
-seed <int64>
Override
level-seed
-loglevel <level>
debug
,
info
,
warn
,
error
-help
/
--help
/
-h
Print usage and exit
参数描述
-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
打印使用说明并退出

server.properties
Configuration

server.properties
配置

Located in the same directory as
Minecraft.Server.exe
. Auto-generated with defaults if missing.
properties
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
Key property notes:
KeyValuesDefaultNotes
server-port
1–65535
25565
TCP listen port
server-ip
string
0.0.0.0
Bind address
server-name
string
DedicatedServer
Max 16 chars
max-players
1–8
8
Player slots
level-seed
int64 or emptyemptyEmpty = random
world-size
classic|small|medium|large
classic
New world size
log-level
debug|info|warn|error
info
Verbosity
autosave-interval
5–3600
60
Seconds between autosaves
white-list
true/false
false
Enable whitelist
lan-advertise
true/false
false
LAN advertisement

位于
Minecraft.Server.exe
的同一目录下。如果缺失会自动生成默认配置。
properties
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
关键配置说明:
配置项可选值默认值说明
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
true/false
false
启用白名单
lan-advertise
true/false
false
局域网广播

Dedicated Server in Docker (Linux/Wine)

Docker部署专用服务器(Linux/Wine)

Recommended: Pull from GHCR (No Local Build)

推荐:从GHCR拉取镜像(无需本地构建)

bash
undefined
bash
undefined

Start (pulls latest image automatically)

启动(自动拉取最新镜像)

./start-dedicated-server.sh
./start-dedicated-server.sh

Start without pulling

启动时不拉取镜像

./start-dedicated-server.sh --no-pull
./start-dedicated-server.sh --no-pull

Equivalent manual command

等效手动命令

docker compose -f docker-compose.dedicated-server.ghcr.yml up -d
undefined
docker compose -f docker-compose.dedicated-server.ghcr.yml up -d
undefined

Local Build Mode (Optional)

本地构建模式(可选)

Requires a locally compiled
Minecraft.Server.exe
:
bash
docker compose -f docker-compose.dedicated-server.yml up -d --build
需要本地编译好的
Minecraft.Server.exe
bash
docker compose -f docker-compose.dedicated-server.yml up -d --build

Docker Persistent Volumes

Docker持久化卷

Host PathContainer PathPurpose
./server-data/server.properties
/srv/mc/server.properties
Server config
./server-data/GameHDD
/srv/mc/Windows64/GameHDD
World save data
主机路径容器路径用途
./server-data/server.properties
/srv/mc/server.properties
服务器配置
./server-data/GameHDD
/srv/mc/Windows64/GameHDD
世界存档数据

Docker Environment Variables

Docker环境变量

VariableDefaultDescription
XVFB_DISPLAY
:99
Virtual display number
XVFB_SCREEN
64x64x16
Virtual screen size (tiny, Wine needs it)

变量默认值描述
XVFB_DISPLAY
:99
虚拟显示器编号
XVFB_SCREEN
64x64x16
虚拟屏幕尺寸(很小,Wine需要它)

Project Structure (Key Areas)

项目结构(关键区域)

MinecraftConsoles/
├── MinecraftConsoles.sln       # Visual Studio solution
├── CMakeLists.txt              # CMake build definition
├── COMPILE.md                  # Detailed compile instructions
├── CONTRIBUTING.md             # Contributor guide and project goals
├── docker-compose.dedicated-server.ghcr.yml  # Docker (GHCR image)
├── docker-compose.dedicated-server.yml       # Docker (local build)
├── start-dedicated-server.sh   # Quick-start script
├── server-data/
│   ├── server.properties       # Server config (auto-generated)
│   └── GameHDD/                # World save data
└── .github/
    └── banner.png

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

Common C++ Patterns in This Codebase

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

Adding a New Key Binding (Keyboard Input)

添加新的按键绑定(键盘输入)

The project added keyboard/mouse support on top of the original controller-only code. When extending input:
cpp
// Typical pattern for checking key state in the input handler
// Find the keyboard input processing file and add your key check:

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

// Example: adding a new toggle key
if (isKeyPressed(VK_F7)) {
    // toggle your feature
    myFeatureEnabled = !myFeatureEnabled;
}
该项目在原有的仅支持控制器的代码基础上添加了键盘/鼠标支持。扩展输入功能时遵循以下模式:
cpp
// 输入处理程序中检查按键状态的典型模式
// 找到键盘输入处理文件并添加你的按键检查:

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

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

Registering a Launch Argument

注册启动参数

Follow the existing
-name
/
-fullscreen
pattern:
cpp
// In the argument parsing section (typically in main or 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;
    }
    // Add your argument:
    else if (arg == "-myoption" && i + 1 < argc) {
        myOption = argv[++i];
    }
}
遵循现有的
-name
/
-fullscreen
模式:
cpp
// 在参数解析部分(通常在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];
    }
}

Reading
server.properties

读取
server.properties

cpp
#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;
}

// Usage:
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";
cpp
#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";

Writing
server.properties
(Normalize / Auto-generate)

写入
server.properties
(标准化/自动生成)

cpp
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";
    }
}

// Normalize level-id from level-name
std::string normalizeLevelId(const std::string& levelName) {
    std::string id = levelName;
    // Remove unsafe characters, lowercase, replace spaces with underscores
    for (char& c : id) {
        if (!std::isalnum(c) && c != '_' && c != '-') c = '_';
    }
    return id;
}

cpp
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;
}

Troubleshooting

故障排除

Build Fails: Missing Windows SDK

构建失败:缺少Windows SDK

  • Open Visual Studio Installer → Modify → add Windows 10/11 SDK
  • Make sure the platform is set to Windows64 (not x86)
  • 打开Visual Studio Installer → 修改 → 添加Windows 10/11 SDK
  • 确保平台设置为Windows64(而非x86)

CMake Can't Find Visual Studio Generator

CMake无法找到Visual Studio生成器

powershell
undefined
powershell
undefined

Confirm VS 2022 is installed, then:

确认已安装VS 2022,然后执行:

cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake -S . -B build -G "Visual Studio 17 2022" -A x64

"17 2022" is the generator name for VS 2022

"17 2022"是VS 2022对应的生成器名称

undefined
undefined

Game Launches But No Display / Crashes Immediately

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

  • Ensure you're running from the directory containing all game assets
  • Check that your GPU drivers support the required DirectX version
  • Try Debug build for more verbose error output
  • 确保从包含所有游戏资源的目录运行
  • 检查你的GPU驱动是否支持所需的DirectX版本
  • 尝试Debug构建版本以获取更详细的错误输出

Server Not Visible on LAN

服务器在局域网中不可见

  • Check firewall rules allow TCP 25565 and UDP 25566
  • Verify
    lan-advertise=true
    is NOT required for dedicated servers (it's for LAN broadcast; clients discover via Join Game)
  • Ensure both client and server are on the same subnet
  • 检查防火墙规则是否允许TCP 25565UDP 25566端口
  • 确认专用服务器不需要设置
    lan-advertise=true
    (该配置用于局域网广播;客户端通过加入游戏菜单发现服务器)
  • 确保客户端和服务器在同一子网中

Docker Server: Wine Can't Display

Docker服务器:Wine无法显示

  • The
    XVFB_DISPLAY
    env var must match what Wine uses
  • The container uses a minimal
    64x64x16
    virtual framebuffer — don't change this unless you have a reason
  • XVFB_DISPLAY
    环境变量必须与Wine使用的一致
  • 容器使用最小的
    64x64x16
    虚拟帧缓冲区——除非有特殊原因,否则不要修改

Username Reset / UID Issues

用户名重置/UID问题

  • Do not delete
    uid.dat
    — it stores your unique player ID
  • If you rename yourself via
    -name
    or
    username.txt
    , your existing
    uid.dat
    keeps world data linked to your account
  • 不要删除
    uid.dat
    ——它存储你的唯一玩家ID
  • 如果你通过
    -name
    username.txt
    重命名,现有的
    uid.dat
    会保持世界数据与你的账户关联

macOS / Linux (Wine)

macOS / Linux(Wine)

  • Download the Windows nightly
    .zip
  • Run via
    wine Minecraft.Client.exe
    or CrossOver
  • Stability issues (frametime pacing) are known and community-reported; not officially supported

  • 下载Windows夜间版本的
    .zip
    文件
  • 通过
    wine Minecraft.Client.exe
    或CrossOver运行
  • 已知存在稳定性问题(帧率波动),为社区反馈支持,非官方支持

Contributing

贡献指南

Read
CONTRIBUTING.md
before submitting PRs. Key points:
  • Follow existing code style and naming conventions
  • Console build compatibility should not be broken without discussion
  • Security fixes are always welcome
  • Check open issues (535+) for good first tasks
  • Join the Discord for contributor discussion

提交PR前请阅读
CONTRIBUTING.md
。关键点:
  • 遵循现有的代码风格和命名规范
  • 未经讨论不得破坏主机版的兼容性
  • 安全修复始终受欢迎
  • 查看开放的535+个问题以寻找适合新手的任务
  • 加入Discord参与贡献者讨论

Platform Support Summary

平台支持总结

PlatformStatus
Windows (VS 2022)✅ Fully supported
macOS / Linux (Wine)⚠️ Community-reported working, unofficial
Android (Wine)⚠️ Runs with frametime issues
iOS❌ No support
Consoles⚠️ Code present, not actively maintained
平台状态
Windows(VS 2022)✅ 完全支持
macOS / Linux(Wine)⚠️ 社区反馈可运行,非官方支持
Android(Wine)⚠️ 可运行但存在帧率问题
iOS❌ 不支持
主机平台⚠️ 代码存在,但未积极维护