SerialCraft

🔌 SerialCraft: the bridge between worlds

Bring your real-world hardware into your Survival world.

Documentation · Source code · Report an issue

SerialCraft connects Arduino, ESP32 and other boards to Minecraft over USB or Wi-Fi.

What's new in 0.5.3-beta

• NeoForge support alongside Fabric, for Minecraft 26.2 and Java 25.
• Output settings: choose connection and normal-disconnection behavior independently: send zero or a custom value (0–255), restore saved values when connecting, or keep the last state when disconnecting.

Thanks to @MeerukYang for the report and suggestions in issue #10. Simplified Chinese translation by @SK-Xiaohan.

Main features

• Hardware → Minecraft: physical buttons, switches, and sensors drive redstone. A potentiometer can control signal strength; a switch on your desk can open your base's door.
• Minecraft → Hardware: redstone controls your board. Use a lever to switch an LED or a comparator to adjust its brightness through PWM.
• USB and Wi-Fi: connect directly over USB serial, or pair a TCP board on your local network. Remembered Wi-Fi boards reconnect through HMAC challenge-response without retyping the token.
• Events: stream health, hunger, world time, and game events to hardware through dedicated mc_* channels.
• Visualizer: inspect RX/TX messages on a timeline, compare a sensor with its redstone conversion, and test an actuator with the waveform generator on a dedicated channel.
• Board identification: USB descriptors and firmware announcements identify supported boards. Generic USB adapters are shown without claiming an unconfirmed board model.
• Output behavior: configure connection and normal-disconnection values from the settings gear. These preferences affect Minecraft → hardware I/O channels; telemetry and the waveform generator keep their own behavior.
• Configuration and diagnostics: configure direction, signal, and OR/AND/XOR logic; inspect RX, TX, redstone, and connection state. Contextual help is available through ?.
• Five locales: English, Spanish for Spain, Mexico and Argentina, and Simplified Chinese. SerialCraft follows your selected game language.

The Laptop has Home, Boards, Events, and Visualizer tabs, a connection welcome screen, a console within Home, and a settings page accessible from the top-right gear. Opening it keeps your world running in singleplayer.

Blocks and recipes

Laptop and Connector

Open the Laptop or right-click a placed Connector to access the interface. Choose a USB board on the welcome screen, or start the Wi-Fi server to display its local IP, port, and pairing token. USB defaults to 115200 baud; change it under Home → Apply and reconnect to match your firmware.

Hardware I/O Module

Right-click the base to set a Channel, data direction, signal type, and logic. The channel must match your sketch, such as pot_val or green_led; mc_ is reserved for game telemetry and identification.

Configure the five terminals directly on the placed block: right-click toggles a green input, and Shift + right-click toggles a red output. The bottom terminal is selected from above near the south edge of the board. Use green input for Minecraft → Hardware and red output for Hardware → Minecraft.

OR uses the maximum input, AND the minimum including zero, and XOR passes the maximum when an odd number of inputs are active. In Hardware → Minecraft mode, green inputs act as an enable condition for the received sample.

Installation and first circuit

Common requirements: Minecraft Java 26.2 and Java 25 or newer.

Build	Loader and dependencies
Fabric	Fabric Loader 0.19.3 or newer and Fabric API for Minecraft 26.2.
NeoForge	NeoForge 26.2.0.93 or newer for Minecraft 26.2. Fabric API is not required.

Install the JAR matching your loader. Multiplayer clients and the server must use compatible versions of SerialCraft and the same loader; mixed-loader multiplayer has not been validated.

1. Install the SerialCraft JAR for your loader in mods. Add Fabric API if using Fabric. In multiplayer, update SerialCraft on clients and server together.
2. Flash a ready-to-use example for an Arduino Uno R3, ESP32, or Arduino Uno Q.
3. Plug the board into USB, or keep it on the same local network as your PC.
4. Craft the Laptop and Connector. Open the interface and connect through the USB or Wi-Fi welcome card.
5. Place a Hardware I/O Module. Set its Channel and direction, then configure its terminals in the world.
6. Use Diagnostics, the Home console, and Visualizer to follow the signal from your sketch to redstone or back to the board.

Hardware protocol

Send a newline-terminated channel and integer, for example:

pot_val:200

Hardware I/O values are 0–255 in both directions, mapped to redstone's 0–15 range. Digital output sends 0 or 255. The firmware's baud rate must match the mod; the default is 115200. See the protocol reference for telemetry, pairing, and identification.

Scope and limits

• Multiplayer: works in singleplayer, LAN, and dedicated servers. Each player connects hardware through their own PC; the dedicated server does not own a serial connection.
• Scale: a functional test covers 64 modules. Sustainable capacity depends on tick time and traffic; communication budgets are shared per player and the board list scrolls.
• Signal delivery: queues are bounded. TX records a transport write, not acknowledgement that an actuator executed it. Every pulse is not guaranteed under overload.
• Wi-Fi: TCP is unencrypted. Pairing is intended for a trusted home or classroom LAN; do not expose the port to the internet.

Documentation and support

• Installation and usage guide
• Hardware I/O Module guide
• Protocol reference
• Board examples
• Tutorials
• Release notes

SerialCraft is developed by Leonardo Aliaga as a learning project connecting Java modding, electronics, and telecommunications. It is open source under the MIT license.