SerialCraft

🔌 SerialCraft：连接世界的桥梁

将现实世界的硬件带入你的生存世界。

文档 · 源代码 · 报告问题

SerialCraft 通过 USB 或 Wi-Fi 将 Arduino、ESP32 及其他开发板连接到 Minecraft。

0.5.3-beta 的新内容

• 支持 NeoForge，与 Fabric 并存，适用于 Minecraft 26.2 和 Java 25。
• 输出设置： 可独立选择连接时和正常断开时的行为：发送零或自定义值（0–255）、连接时恢复保存的值，或断开时保持最后状态。

感谢 @MeerukYang 在问题 #10中的报告和建议。简体中文翻译由 @SK-Xiaohan 提供。

主要功能

• 硬件 → Minecraft： 物理按钮、开关和传感器驱动红石。电位器可以控制信号强度；你桌上的开关可以打开基地的门。
• Minecraft → 硬件： 红石控制你的开发板。用拉杆开关 LED，或用比较器通过 PWM 调节其亮度。
• USB 和 Wi-Fi： 直接通过 USB 串口连接，或在本地网络中配对 TCP 开发板。已记住的 Wi-Fi 开发板可通过 HMAC 挑战-响应重新连接，无需重新输入令牌。
• 事件： 通过专用的 mc_* 通道将生命值、饥饿值、世界时间和游戏事件流式传输到硬件。
• 可视化器： 在时间轴上查看 RX/TX 消息，将传感器与其红石转换值进行比较，并在专用通道上用波形发生器测试执行器。
• 开发板识别： USB 描述符和固件公告可识别支持的开发板。通用 USB 适配器会显示，但不会声明未经确认的开发板型号。
• 输出行为： 从设置齿轮配置连接时和正常断开时的值。这些偏好影响 Minecraft → 硬件的 I/O 通道；遥测和波形发生器保持各自的行为。
• 配置和诊断： 配置方向、信号和 OR/AND/XOR 逻辑；查看 RX、TX、红石和连接状态。可通过 ? 获取上下文帮助。
• 五种语言环境： 英语、西班牙语（西班牙、墨西哥和阿根廷）以及简体中文。SerialCraft 会跟随你选择的游戏语言。

笔记本电脑有 Home、Boards、Events 和 Visualizer 选项卡，一个连接欢迎屏幕，Home 内的控制台，以及可从右上角齿轮访问的设置页面。打开它时，单人游戏中的世界会继续运行。

方块和配方

笔记本电脑和连接器

打开笔记本电脑或右键单击放置的连接器以访问界面。在欢迎屏幕上选择 USB 开发板，或启动 Wi-Fi 服务器以显示其本地 IP、端口和配对令牌。USB 默认使用 115200 波特率；在 Home → Apply and reconnect 下更改它以匹配你的固件。

硬件 I/O 模块

右键单击底座以设置通道、数据方向、信号类型和逻辑。通道必须与你的 sketch 匹配，例如 pot_val 或 green_led；mc_ 保留用于游戏遥测和识别。

直接在放置的方块上配置五个端子：右键单击切换绿色输入，Shift + 右键单击切换红色输出。底部端子从上方靠近板子南边缘处选择。使用绿色输入用于 Minecraft → 硬件，红色输出用于 硬件 → Minecraft。

OR 使用最大输入值，AND 使用包括零在内的最小值，XOR 在活动输入数量为奇数时传递最大值。在硬件 → Minecraft 模式下，绿色输入作为接收样本的启用条件。

安装和第一个电路

通用要求： Minecraft Java 26.2 和 Java 25 或更新版本。

构建	加载器和依赖项
Fabric	Fabric Loader 0.19.3 或更新版本，以及适用于 Minecraft 26.2 的 Fabric API。
NeoForge	适用于 Minecraft 26.2 的 NeoForge 26.2.0.93 或更新版本。不需要 Fabric API。

安装与你的加载器匹配的 JAR。多人游戏客户端和服务器必须使用兼容版本的 SerialCraft 和相同的加载器；混合加载器的多人游戏尚未验证。

1. 在 mods 中安装适用于你的加载器的 SerialCraft JAR。如果使用 Fabric，请添加 Fabric API。在多人游戏中，请同时更新客户端和服务器上的 SerialCraft。
2. 为 Arduino Uno R3、ESP32 或 Arduino Uno Q 烧录一个即用示例。
3. 将开发板插入 USB，或使其与你的 PC 处于同一本地网络。
4. 制作笔记本电脑和连接器。打开界面并通过 USB 或 Wi-Fi 欢迎卡片进行连接。
5. 放置硬件 I/O 模块。设置其通道和方向，然后在世界中配置其端子。
6. 使用诊断、Home 控制台和可视化器来跟踪信号从你的 sketch 到红石或返回开发板的过程。

硬件协议

发送以换行符结尾的通道和整数，例如：

pot_val:200

硬件 I/O 值双向均为 0–255，映射到红石的 0–15 范围。数字输出发送 0 或 255。固件的波特率必须与模组匹配；默认值为 115200。有关遥测、配对和识别，请参阅协议参考。

范围和限制

• 多人游戏： 适用于单人游戏、局域网和专用服务器。每位玩家通过自己的 PC 连接硬件；专用服务器不拥有串口连接。
• 规模： 功能测试覆盖 64 个模块。可持续容量取决于 tick 时间和流量；通信预算按玩家共享，开发板列表可滚动。
• 信号传递： 队列是有界的。TX 记录一次传输写入，而不是执行器已执行它的确认。在过载情况下不保证每个脉冲都能送达。
• Wi-Fi： TCP 未加密。配对适用于可信的家庭或教室局域网；请勿将端口暴露到互联网。

文档和支持

• 安装和使用指南
• 硬件 I/O 模块指南
• 协议参考
• 开发板示例
• 教程
• 发布说明

SerialCraft 由 Leonardo Aliaga 开发，是一个连接 Java 模组开发、电子学和电信的学习项目。它基于 MIT 许可证开源。