介绍#

专为内存受限嵌入式系统打造的极简版Minecraft服务器。

本项目皆在让 ESP32 等性能受限的设备也能运行 Minecraft 服务器，项目设计依次为：内存占用、运行效率、功能完整性。因此不保证完全与原版Minecraft兼容。因为这不是项目的目标。

支持的 Minecraft 版本：1.21.8 协议版本：772

WARNING

目前仅官方原版客户端获得正式支持，使用Fabric等修改版客户端时可能出现兼容性问题。

快速开始#

对于 x86_64 架构平台，请获取最新版本的构建的二进制文件并直接运行，该文件采用 Cosmopolitan多语言格式，这意味着无论扩展名如何，它都能在Linux、MacOS、Windows平台上运行。请注意，如果你要修改服务端配置，请务必通过源代码重新编译才能实现。

编译#

在编译之前，你需要从原版的 Minecraft 服务端中导出服务器注册表数据。在Linux系统上，你可以通过执行extract_registry.sh脚本来自动完成此操作。若需手动处理，请按照此部署进行：

• 1. 在项目根目录下创建一个名为notchian的文件夹，放入 Minecraft 服务端 Jar 文件。随后按照本指南使用带 —all 标志的第二条命令导出所有注册表数据。最后使用bun、node或者deno运行build_registries.js。
• • Linux系统编译： 安装gcc后执行build.sh即可

  • Windows系统编译有多种方案： 编译原生Windows二进制文件： 安装MSYS后启动”MSYS2 MinGW64”终端，执行pacman -Sy mingw-w64-x86_64-gcc安装编译器，进入项目目录运行./build.sh

    编译32位原生程序（兼容Windows 95、98）： 安装MSYS2，启动”MSYS2 Mingw64”终端，执行pacman -Sy mingw-w64-cross-gcc，然后进入项目目录运行./build.sh —9x

    编译MSYS2链接版本： 安装MSYS2后启动”MSYS2 MSYS”终端，通过运行pacman -Sy gcc安装编译器，进入项目目录执行./build.sh

    在Windows中编译Linux版本： 安装WSL后，在子系统内安装gcc并进入项目目录执行./build.sh

    针对 ESP 变体设备的编译： 需要创建PlatformIO项目（选择ESP-IDF框架而非Arduino），并将本仓库代码克隆至该项目中，后续配置步骤请参阅配置章节，为提升性能，建议调整时钟频率并启用编译器优化。若不清楚具体操作方法，可参考网络上的教程。

配置#

配置服务端需要安装上文所述，从源代码进行编译。

最方便用户使用的配置文件选项位于 include/globals.h 文件中，其中包括用于嵌入式设置的Wi-Fi凭证。其他的一些细节，比如每日消息或者服务器启动时间，可以在 src/globals.c 文件中找到。至于其他所有配置，那就需要仔细查看代码了。

对于想在真实微控制器环境中与真实玩家场景中使用本项目的用户，以下是一些重要但容易被忽略的配置项说明：

• 玩家位置同步优化

  根据玩家数量，MCU性能和网络带宽的差异，玩家位置广播可能造成网络拥堵。若出现此情况，可尝试注释 BROADCAST_ALL_MOVEMENT 和 SCALE_MOVEMENT_UPDATES_TO_PLAYER_COUNT 宏定义。此举会将移动同步机制绑定到刻速率（tickrate）。若调整后移动流畅度不足，可调低 TIME_BETWEEN_TICKS 数值（代价是增加计算负荷）。

• 稳定性配置开关

  若遇到与箱子或水流相关的崩溃问题，可分别通过 ALLOW_CHESTS 和 DO_FLUID_FLOW 宏禁用对应功能

• 区块生成调优 若频繁的重复区块生成导致服务器卡顿，增加 VISITED_HISTORY 数值可能有所改善。此配置内存占用极低 — 例如增加至64时，每分配一名玩家仅额外占用240字节。