scafall

Мод scafall для Minecraft — библиотека для разработки кроссплатформенных API

Scafall — это легковесная библиотека, предназначенная для упрощения создания кроссплатформенных API в экосистеме Minecraft. Она предоставляет простые интерфейсы-обертки (прокси) для нативных типов игры, что позволяет разработчикам модов и плагинов разделять код между платформами, не дублируя логику. Проект также включает утилиты для часто используемых задач, таких как планирование задач и специфичные функции для Kotlin, полезные для библиотек вроде Adventure. Важно понимать, что Scafall не является игровым модом и не добавляет геймплейные возможности; она служит зависимостью для других проектов, стремящихся к переносимости кода.

Принцип работы прокси-интерфейсов

Основной механизм работы Scafall строится на использовании простых интерфейсов-обертков, которые служат исключительно в качестве прокси. Библиотека избегает создания полных обертываний каждого элемента платформы, предоставляя лишь минимальный доступ к свойствам объекта. Это позволяет использовать их как эффективный мост между модулями/плагинами, внешними API и внутренней реализацией.

Процесс взаимодействия выглядит следующим образом: API, созданный разработчиком, принимает аргументы в виде обертки (например, ScafallItemStack). При вызове функции происходит распаковка (unwrap) аргумента в нативный объект Minecraft, выполнение необходимых операций с ним и последующая упаковка (wrap) результата. Другие моды или плагины, в свою очередь, упаковывают свои платформозависимые объекты и передают их в API.

Такой подход обеспечивает легковесность решения. Интерфейсы предоставляют доступ только к необходимым свойствам, что делает их идеальными для передачи данных между компонентами. Идея заключается в том, чтобы использовать их исключительно для передачи между модулями, API и реализацией, что значительно упрощает совместное использование общего кода между различными платформами. Поскольку Scafall использует Minecraft как истину в последней инстанции, прокси всегда оборачивают нативные типы игры, а типы других платформ сначала конвертируются в нативные MC-объекты.

Ограничения и управление памятью

При работе с обертками необходимо учитывать ограничения, применимые и к нативным типам. Критически важным правилом является запрет на хранение обертки в списках или картах (map). Попытка сделать это приведет к утечкам памяти, так как обертки не предназначены для долговременного хранения. Их корректное использование ограничено только ролью параметров или возвращаемых значений в вызовах API. Любое другое применение нарушает архитектурные принципы библиотеки и может привести к нестабильности работы модов.

Статус разработки и дополнительные модули

Scafall находится на стадии активной разработки (work-in-progress). Разработчики предупреждают, что нельзя ожидать безупречной работы всех функций на данный момент. Текущий API считается нестабильным и может измениться в любой момент без предварительного уведомления. Гарантии совместимости API пока не предоставляются, хотя они будут введены в будущем.

Главная цель проекта — предоставить базовый каркас (scaffolding) для помощи в процессе разработки. Дополнительные модули и библиотеки могут использовать Scafall для реализации более узкоспециализированных API и утилит. Например, проект viewportl — это фреймворк для UI на базе Compose Runtime, который использует Scafall для создания кроссплатформенных интерфейсов, обеспечивая реактивность и эффективность.