SerialCraft es un mod experimental y educativo que rompe la cuarta pared: permite comunicación bidireccional en tiempo real entre un Arduino (o cualquier dispositivo serial) y Minecraft, escrito en Java sobre Fabric.
No es solo una demostración técnica. Está diseñado para encajar de forma natural en una partida Survival, convirtiendo la electrónica externa en una parte funcional de tu progresión.
El cerebro de la operación. En SerialCraft la conexión no aparece por arte de magia: hay que construirla.
- Integración en Survival: la Laptop es un bloque crafteable. Tienes que reunir los recursos, así que encaja en el equilibrio de una partida de supervivencia.
- La interfaz: al hacer clic derecho se abre una interfaz con cuatro pestañas — Inicio, Placas, Eventos y Visualizar — más la bienvenida de conexión y la consola de Inicio. El escaneo de puertos es automático: no necesitas saber qué es un puerto COM.
Controla tu mundo con componentes reales.
- Conecta botones, sensores o interruptores físicos a tu placa.
- El mod lee esas señales y las traduce en redstone dentro del juego.
- Ejemplo: un potenciómetro real regula la intensidad de una línea de redstone; un interruptor de tu escritorio abre la puerta de hierro de tu base.
Y en el sentido contrario, ya funcionando:
- Un Bloque IO en modo salida detecta la redstone que recibe y la envía a tu placa.
- Ejemplo: la potencia de un comparador regula el brillo de un LED por PWM; una palanca en el juego enciende un zumbador en tu mesa.
- USB Serial: cable directo, la opción más simple y de menor latencia.
- Wi-Fi (TCP): sin cables, con emparejamiento por token y opción de recordar la placa mediante desafío y respuesta HMAC. Ideal para ESP32 y para placas con Linux embebido como el Arduino Uno Q.
- Identificación de placas: reconoce descriptores USB y anuncios del firmware; un adaptador genérico no se confunde con un modelo confirmado.
- Eventos: envía vida, hambre, hora del mundo y sucesos del juego a tu placa mediante canales
mc_*. - Visualizar: observa mensajes RX/TX en una línea de tiempo, compara sensores con su conversión a redstone y prueba un actuador con el generador de ondas en un canal dedicado.
- La Laptop mantiene el mundo en marcha mientras usas su interfaz, incluso en un jugador.
Inglés, español de España, México y Argentina (con voseo), y chino simplificado. Gracias a @SK-Xiaohan por la traducción y el nombre chino 串连世界, aportados en el PR #4. El juego utiliza la localización elegida por el jugador.
El cerebro de la operación: gestiona la conexión con tu dispositivo del mundo real.
- Uso: clic derecho para abrir la interfaz. En la bienvenida, conecta tu placa por USB (115200 baudios por defecto), o inicia el servidor Wi-Fi y copia la IP, el puerto y el token que aparecen en pantalla. Si el servidor no puede iniciarse, verás el error y podrás volver a intentarlo.
- Ajustes USB: desde Inicio, elige los baudios y pulsa Aplicar y reconectar. Deben coincidir con
Serial.begin(...)o su equivalente en el firmware de la placa para que los datos se entiendan.
El puente real: es lo que traduce entre la redstone y tu placa.
- Terminales en el mundo: clic derecho alterna entrada verde/desactivado; Shift + clic derecho alterna salida roja/desactivado. Hay cinco terminales, incluido el inferior, que se selecciona desde arriba cerca del borde sur de la placa.
- Configuración: clic derecho sobre la base para definir el Canal (por ejemplo
led_verdeosensor_a), la dirección Minecraft → Hardware o Hardware → Minecraft, y la señal analógica o digital. El canal debe coincidir con el sketch;mc_está reservado. - Diagnóstico: consulta RX, TX, lecturas, salida y conexión. El editor ofrece ayuda con ? y confirma el guardado con el servidor.
- Compuertas lógicas: OR combina por máximo, AND por mínimo y XOR por paridad. Guía del Módulo de E/S.
Este proyecto nació de un viaje personal: unir el juego que definió mi infancia con mi pasión por la electrónica.
Al desarrollar SerialCraft el objetivo fue demostrar que la lógica de la programación es sorprendentemente parecida al diseño de circuitos físicos:
- Código como cableado: la lógica condicional (
if/else) escrita en Java se comporta igual que un interruptor o una compuerta lógica en una protoboard. Los Bloques IO llevan compuertas OR, AND y XOR reales. - Datos como corriente: el flujo de información por el puerto serie imita el flujo de la corriente; si la lógica no está "cerrada", la señal no llega a su destino.
Este mod es un tributo a esa conexión: usar código para cerrar el circuito entre el mundo de bloques y el mundo físico.
- Minecraft: 26.2
- Java: 25 o superior
- Loader: Fabric 0.19.3 o superior
- Dependencia: Fabric API para Minecraft 26.2
- Hardware: Arduino Uno R3, Uno Q, ESP32, o cualquier microcontrolador con comunicación serial o TCP.
- Instala el mod y la Fabric API en tu carpeta
mods. En multijugador, actualiza SerialCraft en cliente y servidor juntos. - Conecta tu placa por USB (o ponla en la misma red Wi-Fi que tu PC).
- Entra a tu mundo y craftea la Laptop y el Bloque Conector con las recetas incluidas.
- Coloca el Conector y haz clic derecho, o abre la Laptop. Selecciona tu puerto USB o la tarjeta Wi-Fi en la bienvenida de conexión.
- Coloca un Módulo de E/S, define su Canal y dirección, y configura los terminales sobre el bloque: entrada verde para leer redstone, salida roja para emitirla.
- Carga el sketch en tu placa. Hay ejemplos listos para probar para Uno R3, ESP32 y Uno Q.
IDENTIFICADOR:VALOR\n → pot_val:200
Valores de 0 a 255 en ambos sentidos. El mod se encarga de convertir a la escala 0-15 de la redstone. Los detalles están en la referencia de protocolo.
Merece la pena decirlo antes de que lo descubras montando algo grande:
- Multijugador: funciona en un jugador, en LAN y en servidor dedicado. Cada jugador controla sus propias placas desde su propio PC, porque el puerto serie vive en el cliente. No existe un modo en el que el servidor sea dueño del hardware, y no es un olvido: es una decisión de arquitectura.
- Escala: hay una prueba funcional con 64 módulos. La capacidad sostenible requiere medir MSPT y tráfico; la lista tiene scroll y los presupuestos de comunicación se comparten por jugador. Ver la matriz de verificación.
- Señales: las colas son acotadas. TX indica una escritura al transporte, no una confirmación de que el actuador físico ejecutó la orden; no se garantizan todos los pulsos bajo sobrecarga.
- Seguridad: el canal Wi-Fi va en texto claro. El token evita el acceso casual dentro de tu red, pero no es cifrado. Sirve para una red doméstica o de aula; no redirijas el puerto en tu router.
- Guía de instalación y uso
- Referencia de protocolo
- Ejemplos y rutina de prueba
- Notas de versión en GitHub Releases
Al integrar una versión nueva en main, GitHub Actions valida los idiomas, compila, ejecuta las pruebas unitarias y los GameTests, comprueba el JAR y publica GitHub Releases. 0.5.0-beta se publica como Pre-release, no como versión estable. El JAR conserva Minecraft 26.2, Fabric Loader 0.19.3 y Java 25.
Para preparar una versión, actualiza mod_version en gradle.properties y añade changelogs/<mod_version>.es.md y changelogs/<mod_version>.en.md. Las notas oficiales de GitHub se publican en inglés; ambas versiones se conservan en el repositorio. La misma versión se inserta automáticamente en fabric.mod.json al compilar.
Modrinth requiere una acción explícita: ejecuta manualmente Build and test en main y activa publish_modrinth para publicar allí y sincronizar MODRINTH.md. Los pushes normales no publican en Modrinth. Esa opción requiere MODRINTH_TOKEN con Read versions y Create versions, y Write projects (PROJECT_WRITE) para la descripción.
Una versión publicada se conserva sin duplicarla. Para reintentar una publicación parcial, usa Re-run failed jobs en la ejecución original, conservando el mismo JAR. El publicador rechaza un archivo diferente si ya hay un asset en el borrador o un tag que apunta a otro commit.
- Abre el repositorio y selecciona el tag
v0.5.0-betapara reproducir esta Beta, otestpara continuar el desarrollo. - Usa JDK 25 como SDK del proyecto y como Gradle JVM. Importa
build.gradleusando el wrapper incluido, Gradle 9.7.1. - Ejecuta
builddesde el panel de Gradle (Windows:.\gradlew.bat build). El JAR queda enbuild/libs/serialcraft-0.5.0-beta.jar. - Ejecuta la tarea
runClient. En el juego, selecciona 简体中文（中国大陆） para comprobar chino simplificado. - Revisa Welcome, Home, las cuatro pestañas, las ayudas y ambas secciones del editor IO a varias escalas de GUI. Comprueba USB y Wi-Fi con tu placa; esas pruebas físicas y visuales no las sustituye la CI.
Para las comprobaciones adicionales: python scripts/validate_locales.py, python -m unittest discover -s scripts -p 'test_*.py' y, después de compilar, python scripts/publish_release.py --check.
SerialCraft lo desarrolla Leonardo Aliaga (@aliaga1924) como proyecto de aprendizaje, explorando la intersección entre el modding en Java, el hardware físico y las telecomunicaciones.
En el desarrollo se usan herramientas de IA de forma estratégica. El proyecto no depende de ellas para existir: primero se establece la arquitectura y la lógica del sistema mediante razonamiento propio y el estudio de la API de Fabric; después la IA ayuda a ejecutar y refinar esas ideas más rápido.
¿Encontraste un error? Repórtalo.
Proyecto de código abierto. Siéntete libre de estudiar el código para aprender cómo Java maneja la comunicación serial, modificarlo o incluirlo en tus modpacks.