🔌 SerialCraft: the bridge between worlds

Bring your real-world hardware into your Survival world.

• Documentation Here

SerialCraft is an experimental, educational mod that breaks the fourth wall: real-time bidirectional communication between an Arduino (or any serial device) and Minecraft, written in Java on Fabric.

It is not just a tech demo. It is designed to fit naturally into a Survival playthrough, turning external electronics into a functional part of your progression.

🛠️ Main features

💻 The Laptop

The brain of the operation. In SerialCraft the connection doesn't appear by magic — you have to build it.

• Survival integration: the Laptop is a craftable block. You gather the resources for it, so it fits the balance of a survival world.
• The interface: right-click opens a four-page UI — Home, Connection, Boards and Console. Port scanning is automatic: you don't need to know what a COM port is.

⚡ Physical ➔ digital (input)

Control your world with real components.

• Wire physical buttons, sensors or switches to your board.
• The mod reads those signals and turns them into in-game redstone.
• Example: a real potentiometer sets the strength of a redstone line; a switch on your desk opens the iron door of your base.

🔄 Digital ➔ physical (output)

And the other direction, already working:

• An IO Block in output mode reads the redstone it receives and sends it to your board.
• Example: a comparator's power level sets an LED's brightness over PWM; an in-game lever fires a buzzer on your desk.

📶 USB or Wi-Fi

• USB Serial: direct cable, the simplest and lowest-latency option.
• Wi-Fi (TCP): cable-free, with token pairing. Ideal for the ESP32 and for boards with embedded Linux such as the Arduino Uno Q.

🌍 Five locales

English and Spanish, with real localisations for Spain, Mexico, Peru and Argentina (with voseo). The mod detects your region automatically.

📦 Blocks and recipes

1. The Laptop (Connector Block)

The brain of the operation: it handles the link to your real-world device.

• Usage: right-click to open the interface. Pick your port and baud rate (must match your sketch; 115200 by default), or start the Wi-Fi server and copy the IP, port and token shown on screen.
• Settings: the read speed is adjustable for boards that send a lot of traffic.

Crafting recipe

2. The IO Block (Arduino IO)

The actual bridge: this is what translates between redstone and your board.

• Pin system:
  • Right-click a side connector: sets it to IN (green). Reads redstone.
  • Shift + right-click a side connector: sets it to OUT (red). Emits redstone.
  • Configuration: right-click the block to set the Target Data (e.g. led_verde or sensor_a), the mode (input or output) and the signal type (analog or digital).
  • Logic gates: every block carries internal OR, AND and XOR gates that decide when it counts as active if several sides are powered.

Crafting recipe

🧠 The concept: logic and circuits

This project started as a personal journey: joining the game that defined my childhood with my passion for electronics.

The goal while building SerialCraft was to show that programming logic is strikingly close to physical circuit design:

• Code as wiring: conditional logic (if/else) written in Java behaves exactly like a switch or a logic gate on a breadboard. IO Blocks carry real OR, AND and XOR gates.
• Data as current: information flowing through the serial port mirrors current flowing through a circuit; if the logic isn't "closed", the signal never reaches its destination.

This mod is a tribute to that connection: using code to close the circuit between the block world and the physical one.

⚙️ Installation and use

Requirements

• Minecraft: 1.21.11
• Loader: Fabric
• Dependency: Fabric API
• Hardware: Arduino Uno R3, Uno Q, ESP32, or any microcontroller with serial or TCP communication.

Getting started

1. Install the mod and Fabric API into your mods folder.
2. Plug your board in over USB (or put it on the same Wi-Fi network as your PC).
3. Load your world and craft the Laptop (recipe visible with REI/JEI).
4. Place it, right-click, and pick your port under the Connection tab.
5. Place an IO Block, give it an identifier in Target Data, and choose its mode: input or output.
6. Flash the sketch to your board. There are ready-to-run examples for the Uno R3, ESP32 and Uno Q.

The protocol in one line

IDENTIFIER:VALUE\n        →  pot_val:200

Values run 0 to 255 in both directions. The mod handles conversion to redstone's 0-15 scale. Details in the protocol reference.

🧩 Scope and limits

Worth stating up front rather than letting you discover it mid-build:

• Multiplayer: works in singleplayer, on LAN and on a dedicated server. Each player drives their own boards from their own PC, because the serial port lives on the client. There is no mode where the server owns the hardware — that is an architectural decision, not an oversight.
• Scale: 10 to 50 boards per player is reasonable. The practical ceiling is the UI, not the server: the board list still has no scrolling.
• Security: the Wi-Fi channel is plaintext. The token prevents casual access within your network, but it is not encryption. Fine for a home or classroom network; do not forward the port on your router.

📚 Documentation

• Installation and usage guide
• Protocol reference
• Examples and test routine
• Prompts for generating wiring diagrams
• What's new in v0.4.3

🤝 About the project

SerialCraft is developed by Leonardo Aliaga (@aliaga1924) as a learning project, exploring the intersection of Java modding, physical hardware and telecommunications.

AI tools are used strategically during development. The project does not depend on them to exist: the architecture and system logic come first, through personal reasoning and study of the Fabric API; AI then helps execute and refine those ideas faster.

Found a bug? Report it.

📜 License

Open source. Feel free to study the code to learn how Java handles serial communication, modify it, or include it in your modpacks.