| name | bareiron-minecraft |
| description | bareiron 嵌入式 Minecraft 服务器开发技能。提供在内存受限嵌入式系统上运行 Minecraft 服务器的完整参考，包括编译、配置、优化、调试等。TRIGGER when: 用户开发 bareiron 服务器、编译嵌入式 Minecraft、配置内存优化、或需要了解 bareiron 架构时触发。SKIP: 非 bareiron 项目的 Minecraft 服务器开发。 |
bareiron 嵌入式 Minecraft 服务器开发技能
本技能提供 bareiron 项目的完整开发参考，一个面向内存受限嵌入式系统的极简 Minecraft 服务器。
触发条件
当用户执行以下操作时触发此技能：
- 开发 bareiron 服务器
- 编译嵌入式 Minecraft 服务器
- 配置内存优化
- 调试 bareiron 服务器问题
跳过条件
以下情况不触发此技能：
- 非 bareiron 项目的 Minecraft 服务器
- 完整原版 Minecraft 服务器开发
项目概述
- 目标: 在极弱设备上运行 Minecraft 服务器
- 优先级: 内存使用 > 性能 > 功能
- Minecraft 版本: 1.21.8
- 协议版本: 772
- 支持平台: ESP32 (ESP-IDF) / PC x86_64
快速开始
PC 平台
下载 最新构建 并运行。
文件是 Cosmopolitan polyglot，可在 Windows、Linux 和 Mac 上运行。
嵌入式平台
参见 编译 部分。
编译
准备注册表数据
编译前需要从 vanilla Minecraft 服务器导出注册表数据：
Linux 自动方式:
./extract_registries.sh
手动方式:
- 创建
notchian 文件夹
- 放入 Minecraft 服务器 JAR
- 按照 数据生成器指南 导出注册表
- 运行
build_registries.js
PC 编译
Linux:
./build.sh
Windows (MSYS2 MINGW64):
pacman -Sy mingw-w64-x86_64-gcc
./build.sh
Windows (32 位):
pacman -Sy mingw-w64-cross-gcc
./build.sh --9x
ESP32 编译
- 设置 PlatformIO 项目（选择 ESP-IDF 框架，不要用 Arduino）
- 克隆 bareiron 仓库
- 配置 WiFi 凭据（
include/globals.h）
- 考虑提高时钟频率和启用编译器优化
配置
主要配置文件
include/globals.h: 用户友好的配置选项src/globals.c: 其他细节（MOTD、时间等）
WiFi 配置 (ESP32)
#define WIFI_SSID "your-ssid"
#define WIFI_PASS "your-password"
性能配置
#define TIME_BETWEEN_TICKS 1000000
#define VIEW_DISTANCE 2
#define MAX_PLAYERS 16
#define MAX_BLOCK_CHANGES 20000
网络优化
#define BROADCAST_ALL_MOVEMENT
#define SCALE_MOVEMENT_UPDATES_TO_PLAYER_COUNT
提示: 如果位置广播导致网络拥塞，尝试注释掉这两个选项。
稳定性配置
区块生成优化
#define VISITED_HISTORY 4
非易失性存储 (ESP32)
LittleFS
- 在 PlatformIO 中设置 LittleFS
- 取消注释
globals.h 中的 SYNC_WORLD_TO_DISK
- 考虑启用
DISK_SYNC_BLOCKS_ON_INTERVAL
SD 卡
需要自行实现文件系统设置例程。内置序列化器使用 POSIX 文件系统调用。
TCP 导出导入
启用 DEV_ENABLE_BEEF_DUMPS:
- 发送
0xBEEF 导出世界数据
- 发送
0xFEED 后跟数据上传世界数据
警告: 无鉴权，任何人可上传任意世界数据。
文件结构
| 文件 | 功能 |
|---|
include/globals.h | 配置文件 |
src/globals.c | 全局变量和 MOTD |
build.sh | 构建脚本 |
build_registries.js | 注册表构建工具 |
extract_registries.sh | 注册表导出脚本 |
.github/ | GitHub 配置 |
开发指南
代码风格
- 遵循现有代码风格
- 确保修改与周围代码一致
- 不一致的风格会被要求修改
测试
- 创建 PR 前测试代码
- 无论修改多么"简单"都要测试
- 这是对维护者和审查者的基本尊重
贡献
- 创建 issue 并与维护者讨论后再提交 PR
- 即使是小修改也要先讨论
- 开发工具和编译改进不受欢迎，除非你已经足够熟悉代码库
参考资源
已知限制
- 仅支持 vanilla 客户端（不支持 Fabric 等）
- 不保证与原版 Minecraft 完全兼容
- 不支持高并发
- 功能优先级低于内存和性能
