esp32-minecraft

name	esp32-minecraft
description	ESP32 Minecraft 服务器开发技能。提供在 ESP32 上运行 Minecraft Java 服务器的完整参考，包括配置、编译、调试、网络优化等。TRIGGER when: 用户开发 ESP32 Minecraft 服务器、配置 globals.h、调试网络问题、优化性能、或需要了解嵌入式 Minecraft 服务器时触发。SKIP: 非 ESP32 平台的 Minecraft 服务器开发。

ESP32 Minecraft 服务器开发技能

本技能提供在 ESP32 上运行 Minecraft Java 服务器的完整参考，基于 ESP32-MC 和 bareiron 项目。

触发条件

当用户执行以下操作时触发此技能：

• 开发 ESP32 Minecraft 服务器
• 配置 globals.h 文件
• 调试网络连接问题
• 优化服务器性能
• 了解嵌入式 Minecraft 服务器架构

跳过条件

以下情况不触发此技能：

• 非 ESP32 平台的 Minecraft 服务器
• 完整原版 Minecraft 服务器开发

---

项目概述

ESP32-MC

• 目标平台: Arduino ESP32S3
• 协议版本: 26.1.2 / 775
• 核心语言: C
• 网络层: Arduino WiFiServer/WiFiClient 兼容层

bareiron

• 目标平台: ESP32 (ESP-IDF) / PC x86_64
• 协议版本: 1.21.8 / 772
• 核心语言: C
• 优先级: 内存使用 > 性能 > 功能

---

核心配置 (globals.h)

基础配置

// TCP 端口（Minecraft 默认 25565）
#define PORT 25565

// 最大玩家数（内存槽位，非并发数）
#define MAX_PLAYERS 16

// 最大 Mob 数
#define MAX_MOBS (MAX_PLAYERS)

// 游戏模式: 0 生存, 1 创造, 2 冒险, 3 旁观
#define GAMEMODE 0

// 最大视距（区块数）
#define VIEW_DISTANCE 2

性能配置

// Tick 间隔（微秒），默认 1 秒
#define TIME_BETWEEN_TICKS 1000000

// 每秒 Tick 数（自动计算）
#define TICKS_PER_SECOND ((float)1000000 / TIME_BETWEEN_TICKS)

// 区块大小（建议 2 的幂）
#define CHUNK_SIZE 8

// 记住最近访问的区块数（避免重复发送）
#define VISITED_HISTORY 4

// 最大方块修改数（决定内存占用）
#define MAX_BLOCK_CHANGES 20000

网络配置

// 网络超时时间（微秒）
#define NETWORK_TIMEOUT_TIME 15000000

// 接收缓冲区大小
#define MAX_RECV_BUF_LEN 256

// 广播所有移动更新（低 Tickrate 更流畅）
#define BROADCAST_ALL_MOVEMENT

// 根据玩家数缩放移动更新频率
#define SCALE_MOVEMENT_UPDATES_TO_PLAYER_COUNT

功能开关

// 流体流动（计算密集）
#define DO_FLUID_FLOW

// 箱子支持（每个箱子占 15 个 block change 槽）
#define ALLOW_CHESTS

// 飞行模式
// #define ENABLE_PLAYER_FLIGHT

// 拾取动画
#define ENABLE_PICKUP_ANIMATION

// 仙人掌伤害
#define ENABLE_CACTUS_DAMAGE

// 服务器品牌（F3 调试信息）
#define SEND_BRAND

存储配置

// 同步世界数据到磁盘/Flash
// ESP 平台默认关闭（Flash 写入慢且不稳定）
#ifndef ESP_PLATFORM
  #define SYNC_WORLD_TO_DISK
#endif

// 磁盘同步间隔（微秒）
#define DISK_SYNC_INTERVAL 15000000

// 方块修改按间隔同步（而非即时）
// #define DISK_SYNC_BLOCKS_ON_INTERVAL

调试选项

// 记录未知包 ID
// #define DEV_LOG_UNKNOWN_PACKETS

// 断开时打印网络诊断
#define DEV_LOG_NETWORK_DIAGNOSTICS

// 记录包长度不一致
#define DEV_LOG_LENGTH_DISCREPANCY

// 记录区块生成日志
// #define DEV_LOG_CHUNK_GENERATION

// 最小 Play 包引导（排查掉线）
#define DEV_MINIMAL_PLAY_BOOTSTRAP

// 启用 0xBEEF/0xFEED 世界数据导出导入（无鉴权）
// #define DEV_ENABLE_BEEF_DUMPS

---

世界生成配置

// 初始世界种子（启动后会再 hash）
#define INITIAL_WORLD_SEED 0xA103DE6C

// 初始随机种子（掉落和 Mob 行为）
#define INITIAL_RNG_SEED 0xE2B9419

// 地形基准高度
#define TERRAIN_BASE_HEIGHT 60

// 洞穴基准深度
#define CAVE_BASE_DEPTH 24

// Biome 大小（建议 2 的幂）
#define BIOME_SIZE (CHUNK_SIZE * 8)
#define BIOME_RADIUS (BIOME_SIZE / 2)

---

编译与运行

ESP32-MC (Arduino)

1. 用 Arduino IDE 打开 code.ino
2. 选择 ESP32S3 开发板
3. 编译并烧录
4. 设备启动后连接 WiFi
5. 服务器监听端口 25565

bareiron (ESP-IDF)

1. 设置 PlatformIO 项目（选择 ESP-IDF 框架）
2. 克隆 bareiron 仓库
3. 配置 WiFi 凭据（include/globals.h）
4. 编译并烧录

bareiron (PC)

# Linux
./build.sh

# Windows (MSYS2 MINGW64)
pacman -Sy mingw-w64-x86_64-gcc
./build.sh

# 运行
./bareiron.exe

---

文件结构

ESP32-MC

文件	功能
code.ino	Arduino 入口，连 WiFi，启动主任务
main.c	主循环、连接管理、收包分发
packets.c	协议收发
procedures.c	玩家、方块、Mob、Tick 逻辑
worldgen.c	地形和区块生成
crafting.c	合成和熔炉
serialize.c	世界数据读写
globals.h	主要开关和常量

bareiron

文件	功能
src/	源代码目录
include/	头文件目录
include/globals.h	配置文件
build.sh	构建脚本
build_registries.js	注册表构建工具

---

性能优化建议

内存优化

1. 减少 MAX_PLAYERS: 每个玩家占用固定内存
2. 减少 MAX_BLOCK_CHANGES: 控制世界修改数量
3. 禁用 ALLOW_CHESTS: 箱子占用大量内存
4. 减小 VIEW_DISTANCE: 减少区块发送数量

网络优化

1. 启用 BROADCAST_ALL_MOVEMENT: 低 Tickrate 下更流畅
2. 启用 SCALE_MOVEMENT_UPDATES_TO_PLAYER_COUNT: 人多时省带宽
3. 调整 TIME_BETWEEN_TICKS: 平衡流畅度和计算量
4. 减小 MAX_RECV_BUF_LEN: 减少内存占用

稳定性优化

1. 禁用 DO_FLUID_FLOW: 流体计算可能不稳定
2. 禁用 ALLOW_CHESTS: 某些平台可能崩溃
3. 增加 VISITED_HISTORY: 减少重复区块生成
4. 禁用 DISK_SYNC_BLOCKS_ON_INTERVAL: Flash 写入慢

---

WiFi 配置

ESP32-MC

使用 wifi_config.cpp 中的配网流程：

• 串口配网
• Web 配网

bareiron

在 include/globals.h 中配置：

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

---

世界数据持久化

PC 平台

默认写入 world.bin 文件。

ESP 平台

1. 设置 LittleFS
2. 取消注释 globals.h 中的 SYNC_WORLD_TO_DISK
3. 考虑启用 DISK_SYNC_BLOCKS_ON_INTERVAL

TCP 导出导入

启用 DEV_ENABLE_BEEF_DUMPS:

• 发送 0xBEEF 导出世界数据
• 发送 0xFEED 后跟数据上传世界数据

注意: 无鉴权，仅限开发调试使用。

---

已实现功能

• 玩家登录、出生、移动、聊天
• 区块生成、基础地形、生物群系
• 方块放置、破坏、简单流体
• 背包、合成、熔炉
• 基础 Mob 刷新和行为
• 可选世界数据落盘
• 串口/Web 配网

---

已知限制

• 不是完整原版服务器
• 不兼容插件生态
• 不支持高并发
• 协议版本固定（不支持多版本）
• 仅支持 vanilla 客户端

---

调试技巧

1. 查看日志: 启用相关 DEV_LOG_* 选项
2. 网络诊断: 启用 DEV_LOG_NETWORK_DIAGNOSTICS
3. 最小引导: 启用 DEV_MINIMAL_PLAY_BOOTSTRAP 排查掉线
4. 世界导出: 使用 DEV_ENABLE_BEEF_DUMPS 导出世界数据

---

参考资源

• ESP32-MC 仓库
• bareiron 仓库
• Minecraft 协议文档