Burning

Burning представляет собой библиотечный мод, который создаёт унифицированный интерфейс для управления уровнем топлива в подавляющем большинстве печей и аналогичных блоков - как стандартных из ванильного Minecraft, так и добавленных сторонними модификациями.

Мод базируется на технологиях Lookup и Transaction от Fabric.

Особенности функционирования

Основу Burning составляют два ключевых элемента: интерфейс BurningStorage, отвечающий за добавление и извлечение горящего топлива, и класс Burning, представляющий само горящее топливо.

Более детальную информацию можно получить из документации или непосредственно из исходного кода.

Установка и эксплуатация (для обычных пользователей)

Процесс установки не отличается от установки других модов. После инсталляции без дополнительной настройки каждый блок, который расширяет абстрактный класс AbstractFurnaceBlockEntity (в соответствии с маппингами Mojang) - будь то стандартная Печь, Плавильная печь или Коптильня, а также любые сторонние блоки - автоматически получает BurningStorage и становится готовым к взаимодействию с другими модификациями.

Исключение блоков (для продвинутых пользователей)

В некоторых случаях может потребоваться исключить определенные блоки из расширенной функциональности, например, если они некорректно работают или по личным предпочтениям.

Для этого достаточно добавить соответствующий блок в тег #burning:blacklist блоков. Это предотвратит автоматическое создание для него BurningStorage.

Процедура требует создания датапака со следующей структурой:

<название_пака>.zip
├── data
│   └── <название_пака>
│       └── burning
│           └── tags
│               └── blocks (до версии 1.21) или block (после версии 1.21)
│                   └── blacklist.json
├── pack.mcmeta
└── pack.png (опционально)

Файл blacklist.json должен содержать перечень исключаемых блоков:

{
    "replace": false,
    "values": [
        "название_мода:название_блока_1",
        "название_мода:название_блока_2"
    ]
}

Динамические хранилища (для опытных пользователей)

Некоторые модификации добавляют блоки, которые могут использовать топливо, но по различным причинам не расширяют класс AbstractFurnaceBlockEntity, поэтому автоматически не получают BurningStorage.

Для решения этой проблемы Burning предлагает динамический реестр burning:dynamic_storage, который через датапаки и рефлексию обеспечивает необходимую функциональность.

Перед настройкой необходимо определить:

• Тип сущности блока
• Поле, аналогичное litTimeRemaining в AbstractFurnaceBlockEntity
• Поле, аналогичное litTotalTime в AbstractFurnaceBlockEntity

Датапак должен иметь следующую структуру:

<название_пака>.zip
├── data
│   └── <название_пака>
│       └── burning
│           └── dynamic_storage
│               └── <тип_сущности_блока_1>.json
│               └── <тип_сущности_блока_2>.json
├── pack.mcmeta
└── pack.png (опционально)

Каждый файл *.json настраивается следующим образом:

{
    "type": "пример_мода:пользовательский_тип_печи",
    "lit_time": "времяГорения",
    "lit_duration": "времяТоплива"
}

Интеграция для разработчиков

Настройка зависимостей

Добавьте в файл gradle.build:

repositories {
    exclusiveContent {
        forRepository {
            maven {
                name = "Modrinth"
                url = "https://api.modrinth.com/maven"
            }
        }
        filter {
            includeGroup "maven.modrinth"
        }
    }
}

dependencies {
    modImplementation "maven.modrinth:burning:<версия_burning>"
}

Основные операции

Получение хранилища горючего:

import niv.burning.api.BurningStorage;

Level мир;
BlockPos позиция;

@Nullable
BurningStorage хранилище = BurningStorage.SIDED.find(мир, позиция, null);

Третий аргумент метода find обычно игнорируется, поэтому безопасно передавать null.

Перемещение горючего между хранилищами:

import niv.burning.api.Burning;
import niv.burning.api.BurningStorage;

Level мир;
BurningStorage источник, цель;
BurningContext контекст = ...;

// Создание количества горючего для передачи
Burning горючее = Burning.COAL.withValue(800, контекст);

// Передача
Burning переданное = BurningStorage.transfer(
        источник,
        цель,
        горючее,
        контекст,
        null);

Использование в собственных блочных сущностях

Вместо реализации полей, аналогичных litTimeRemaining и litTotalTime, рекомендуется:

import niv.burning.api.BurningStorage;
import niv.burning.api.BurningStorageHelper;
import niv.burning.api.BurningStorageListener;
import niv.burning.api.base.SimpleBurningStorage;

public class MyBlockEntity extends BlockEntity implements BurningStorageListener {
    public final SimpleBurningStorage простоеХранилищеГорючего = new SimpleBurningStorage();

    public MyBlockEntity(...) {
        // ...
        this.простоеХранилищеГорючего.addListener(this);
    }

    @Override
    public void burningStorageChanged(BurningStorage хранилищеГорючего) {
        BurningStorageHelper.tryUpdateLitProperty(this, хранилищеГорючего);
        this.setChanged();
    }

    @Override
    protected void loadAdditional(ValueInput вход) {
        super.loadAdditional(вход);
        вход.read("Burning", SimpleBurningStorage.SNAPSHOT_CODEC)
            .ifPresent(this.простоеХранилищеГорючего::readSnapshot);
    }

    @Override
    protected void saveAdditional(ValueOutput выход) {
        super.saveAdditional(выход);
        выход.store("Burning", SimpleBurningStorage.SNAPSHOT_CODEC, 
                   this.простоеХранилищеГорючего.createSnapshot());
    }
}

Не забудьте зарегистрировать:

BurningStorage.SIDED.registerForBlockEntity((сущностьБлока, направление) -> 
    сущностьБлока.простоеХранилищеГорючего, ТИП_МОЕЙ_СУЩНОСТИ_БЛОКА);

Доступ к аналогам основных полей:

this.простоеХранилищеГорючего.getCurrentBurning(); // эквивалент litTimeRemaining
this.простоеХранилищеГорючего.setCurrentBurning(800);
this.простоеХранилищеГорючего.getMaxBurning(); // эквивалент litTotalTime
this.простоеХранилищеГорючего.setMaxBurning(1600);