bareiron-minecraft

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

手动方式:

1. 创建 notchian 文件夹
2. 放入 Minecraft 服务器 JAR
3. 按照 数据生成器指南 导出注册表
4. 运行 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 编译

1. 设置 PlatformIO 项目（选择 ESP-IDF 框架，不要用 Arduino）
2. 克隆 bareiron 仓库
3. 配置 WiFi 凭据（include/globals.h）
4. 考虑提高时钟频率和启用编译器优化

---

配置

主要配置文件

• include/globals.h: 用户友好的配置选项
• src/globals.c: 其他细节（MOTD、时间等）

WiFi 配置 (ESP32)

#define WIFI_SSID "your-ssid"
#define WIFI_PASS "your-password"

性能配置

// Tick 间隔（微秒）
#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 ALLOW_CHESTS

// 禁用流体流动（可能不稳定）
// #define DO_FLUID_FLOW

区块生成优化

// 增加访问历史（减少重复生成）
#define VISITED_HISTORY 4  // 增加到 64 只需额外 240 字节/玩家

---

非易失性存储 (ESP32)

LittleFS

1. 在 PlatformIO 中设置 LittleFS
2. 取消注释 globals.h 中的 SYNC_WORLD_TO_DISK
3. 考虑启用 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
• 即使是小修改也要先讨论
• 开发工具和编译改进不受欢迎，除非你已经足够熟悉代码库

---

参考资源

• bareiron 仓库
• Minecraft 协议文档
• ESP32-MC - 参考实现

---

已知限制

• 仅支持 vanilla 客户端（不支持 Fabric 等）
• 不保证与原版 Minecraft 完全兼容
• 不支持高并发
• 功能优先级低于内存和性能