SerialCraft

🔌 SerialCraft: мост между мирами

Перенесите своё реальное железо в мир выживания.

• Документация здесь SerialCraft — экспериментальный обучающий мод, который ломает четвёртую стену: двусторонняя связь в реальном времени между Arduino (или любым последовательным устройством) и Minecraft, написанный на Java для Fabric. Это не просто техническая демка. Он создан так, чтобы естественно вписаться в прохождение выживания, превращая внешнюю электронику в функциональную часть вашего прогресса.

🛠️ Основные возможности

💻 Ноутбук

Мозг всей операции. В SerialCraft соединение не появляется по волшебству — его нужно построить.

• Интеграция в выживание: ноутбук — это крафтящийся блок. Вы собираете ресурсы для него, так что он вписывается в баланс мира выживания.
• Интерфейс: правый клик открывает интерфейс из четырёх страниц — Главная, Соединение, Платы и Консоль. Сканирование портов автоматическое: вам не нужно знать, что такое COM-порт.

⚡ Физическое ➔ цифровое (ввод)

Управляйте своим миром с помощью реальных компонентов.

• Подключите физические кнопки, датчики или переключатели к вашей плате.
• Мод считывает эти сигналы и превращает их в редстоун в игре.
• Пример: реальный потенциометр задаёт силу сигнала редстоуна; переключатель на вашем столе открывает железную дверь вашей базы.

🔄 Цифровое ➔ физическое (вывод)

И обратное направление, уже работающее:

• IO-блок в режиме вывода считывает получаемый редстоун и отправляет его на вашу плату.
• Пример: уровень сигнала компаратора задаёт яркость светодиода через PWM; рычаг в игре запускает зуммер на вашем столе.

📶 USB или Wi-Fi

• USB Serial: прямой кабель, самый простой вариант с наименьшей задержкой.
• Wi-Fi (TCP): без кабеля, со спариванием по токену. Идеально для ESP32 и плат со встроенным Linux, таких как Arduino Uno Q.

🌍 Пять локалей

Английский и испанский, с настоящими локализациями для Испании, Мексики, Перу и Аргентины (с voseo). Мод автоматически определяет ваш регион.

📦 Блоки и рецепты

1. Ноутбук (блок-коннектор)

Мозг всей операции: он управляет связью с вашим реальным устройством.

• Использование: правый клик открывает интерфейс. Выберите порт и скорость передачи (должна совпадать с вашим скетчем; по умолчанию 115200), или запустите Wi-Fi-сервер и скопируйте IP, порт и токен, показанные на экране.
• Настройки: скорость чтения регулируется для плат, которые отправляют много трафика.

Рецепт крафта

2. IO-блок (Arduino IO)

Собственно мост: именно он переводит между редстоуном и вашей платой.

• Система пинов:

  • Правый клик по боковому коннектору: устанавливает его в IN (зелёный). Считывает редстоун.
  • Shift + правый клик по боковому коннектору: устанавливает его в OUT (красный). Испускает редстоун.
• Настройка: правый клик по блоку задаёт Target Data (например, led_verde или sensor_a), режим (ввод или вывод) и тип сигнала (аналоговый или цифровой).
• Логические вентили: каждый блок несёт внутренние вентили OR, AND и XOR, которые решают, когда он считается активным, если запитанo несколько сторон.

Рецепт крафта

🧠 Концепция: логика и схемы

Этот проект начался как личное путешествие: объединить игру, определившую моё детство, с моей страстью к электронике. Целью при создании SerialCraft было показать, что логика программирования поразительно близка к проектированию физических схем:

• Код как проводка: условная логика (if/else), написанная на Java, ведёт себя точно так же, как переключатель или логический вентиль на макетной плате. IO-блоки несут настоящие вентили OR, AND и XOR.
• Данные как ток: информация, текущая через последовательный порт, отражает ток, текущий через схему; если логика не «замкнута», сигнал никогда не достигнет цели. Этот мод — дань уважения этой связи: использование кода, чтобы замкнуть цепь между миром блоков и физическим миром.

⚙️ Установка и использование

Требования

• Minecraft: 1.21.11
• Загрузчик: Fabric
• Зависимость: Fabric API
• Железо: Arduino Uno R3, Uno Q, ESP32 или любой микроконтроллер с последовательной связью или TCP.

Начало работы

1. Установите мод и Fabric API в папку mods.
2. Подключите плату по USB (или подключите её к той же Wi-Fi-сети, что и ваш ПК).
3. Загрузите мир и скрафтите ноутбук (рецепт виден с REI/JEI).
4. Поставьте его, нажмите правой кнопкой и выберите порт на вкладке «Соединение».
5. Поставьте IO-блок, задайте ему идентификатор в Target Data и выберите режим: ввод или вывод.
6. Залейте скетч на вашу плату. Есть готовые примеры для Uno R3, ESP32 и Uno Q.

Протокол в одну строку

IDENTIFIER:VALUE\n        →  pot_val:200

Значения ходят от 0 до 255 в обе стороны. Мод сам обрабатывает преобразование в шкалу редстоуна 0-15. Подробности в справочнике по протоколу.

🧩 Область применения и ограничения

Стоит сказать сразу, а не оставлять вас узнавать это посреди сборки:

• Мультиплеер: работает в одиночной игре, по LAN и на выделенном сервере. Каждый игрок управляет своими платами со своего ПК, потому что последовательный порт находится на клиенте. Режима, где железом владеет сервер, нет — это архитектурное решение, а не упущение.
• Масштаб: 10–50 плат на игрока — разумно. Практический потолок — это интерфейс, а не сервер: в списке плат до сих пор нет прокрутки.
• Безопасность: канал Wi-Fi передаётся открытым текстом. Токен защищает от случайного доступа внутри вашей сети, но это не шифрование. Подходит для домашней или классной сети; не пробрасывайте порт на роутере.

📚 Документация

• Руководство по установке и использованию
• Справочник по протоколу
• Примеры и процедура тестирования
• Промпты для генерации схем подключения
• Что нового в v0.4.3

🤝 О проекте

SerialCraft разрабатывает Leonardo Aliaga (@aliaga1924) как учебный проект, исследуя пересечение Java-моддинга, физического железа и телекоммуникаций. Инструменты ИИ используются стратегически в ходе разработки. Проект не зависит от них в своём существовании: архитектура и логика системы создаются в первую очередь через личные размышления и изучение Fabric API; затем ИИ помогает быстрее воплощать и дорабатывать эти идеи. Нашли баг? Сообщите о нём.

📜 Лицензия

Открытый исходный код. Изучайте код, чтобы понять, как Java работает с последовательной связью, изменяйте его или включайте в свои модпаки.