ESP桥接

ESPBridge

有人加入了你的服务器。你的 ESP32 在你查看玩家列表之前就已经知道了。

ESPBridge 将 Minecraft 服务器上发生的两件事——玩家加入或离开，以及聊天——发送到本地网络中的一个小型 ESP32 设备上，让它显示在自己的屏幕上。无需账号，无需云服务，无需端口转发：你的服务器和 ESP32 直接通过局域网通信。

---

工作原理

1. 有人加入、离开或在聊天中发言。
2. ESPBridge 发送一段短文本——"Nik joined (3 online)"、"Nik: hey"——以小型 HTTP 请求的形式发送到你配置的地址。
3. 你的 ESP32 将其显示出来。 如何处理这段文本取决于你自己的 ESP32 固件——ESPBridge 只负责传递。

这就是全部功能。没有规则引擎，除了一个 URL 之外没有其他配置——故意只提供两个事件和一个动作，这样在添加更多功能之前可以对整个流程进行端到端验证。

发送的内容

事件	文本
玩家加入	<name> joined (<n> online)
玩家离开	<name> left (<n> online)
聊天消息	<name>: <message>

以 POST <your-url> 发送，Content-Type: application/json，请求体为 {"text": "..."}。

设置

1. 安装模组后启动一次服务器。它会生成 config/espbridge.json。
2. 将 esp32Url 设置为你的设备端点，例如 http://192.168.1.50/event。
3. /espbridge reload。
4. /espbridge test hello world 用于检查连接，无需等待真实的加入或聊天消息。

命令

/espbridge status · /espbridge reload · /espbridge test <text> —— 均为管理员等级 2。

为运行中的服务器而设计

• 绝不阻塞服务器线程。 HTTP 调用异步执行。
• 请求会被丢弃，而不是排队或重试，如果你的设备不可达——迟到的消息比从未到达的消息更糟糕。
• 速率限制（默认每秒 5 个请求）保护小型 ESP32 Web 服务器，避免聊天刷屏变成请求洪流。

要求

• Minecraft 1.21.11
• Fabric Loader 及 Fabric API
• 仅服务端——无需客户端安装
• 你自己的 ESP32（或兼容微控制器）运行一个 Web 服务器，接受上述 POST 格式；ESPBridge 不包含也不指定任何特定固件

诚实的局限性

这是 0.1.0 版本，首个发布版。它已在真实的 Fabric 1.21.11 开发服务器上运行（能干净启动，命令通过 RCON 验证），其 HTTP 传递已在替代接收器上进行了端到端验证，包括速率限制。尚未验证的是实际玩家加入、离开或聊天消息触发它——那需要真实客户端连接，目前还未发生。也没有真实的 ESP32 硬件接收过任何内容。

故意只支持两个事件。 死亡、Boss 击杀、进度和物品栏事件不在本版本中。目标是先让一条从游戏事件到物理显示的干净、经过验证的路径跑通。

没有重试或离线队列。 如果你的 ESP32 关机或不可达，事件会被静默丢弃，不会缓存以备后续发送。

ESP32 端

存在一个参考接收端草图（WiFiManager 设置门户、状态页面、将 POST /event 解析到 SSD1306 OLED 上），可在 ESP32 工具链上干净编译。尚未烧录到真实硬件上运行。

未来方向

• 在真实硬件上烧录并验证参考固件
• 在加入/离开/聊天针对真实玩家连接被证明稳定后，添加更多事件