Unruled API

Unruled API

Позволяет создавать новые виды игровых правил, выходящие за рамки ограниченных ванильных целых чисел и булевых значений.

Этот мод позволяет разработчикам легко создавать новые игровые правила с плавающей точкой, long, double, строковые, текстовые, на основе enum, селекторы сущностей и даже правила с записями реестра, используя соответствующие билдеры, доступные через статические методы класса com.nerjal.unruled_api.UnruledApi.

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

Кроме того, этот мод добавляет переопределения игровых правил для каждого измерения! Они применяются в своём строгом измерении (при условии, что запрашиваются правильно). Подробнее об этом см. в разделе переопределения игровых правил.

Регистрация игровых правил

Пример:

import com.nerjal.unruled_api.UnruledApi;

public class MyClass {
    private static final int STRING_RULE_MAX_LENGTH = 24;

    public void gamerulesRegistration() {
        var myFloatingRule = UnruledApi.floatRuleBuilder(category, 1.5) // принимает категорию и начальное значение в качестве аргументов
                // категория определяет, где на экране создания мира оно будет размещено
                .register("mymod:my_gamerule"); // регистрация игрового правила всегда принимает ID игрового правила
                // ID также определяет переведённое название игрового правила
        var myStringRule = new StringRule.Builder(category, "initial value", STRING_RULE_MAX_LENGTH)
                // использование методов UnruledApi или прямое создание билдера даёт одинаковый результат, и аргументы одни и те же.
                // однако учтите, что в некоторых случаях настоятельно рекомендуется использовать указанные билдеры, например для строковых
                // правил, enum и правил с динамическими записями реестра, так как у них более специфичная обработка значений и
                // обработка команд.
                .register("mymod:my_other_gamerule");
    }

}

Кроме того, для вашего удобства были добавлены методы быстрого создания и регистрации

import com.nerjal.unruled_api.UnruledApi;

    public static void quickGamerulesRegistration() {
        var myLongRule = UnruledApi.registerLong(Identifier.of("mymod:my_long_rule"), category, 25L);
        // Методы быстрой регистрации всегда следуют одному порядку параметров: имя, категория, начальное значение, аргументы, специфичные для типа игрового правила
        // За исключением правил enum, для которых класс enum идёт перед начальным значением
        var myEnumRule = UnruledApi.registerEnumRule(Identifier.of("mymod:my_enum_rule"), category, MyEnum.FIRST, MyEnum.class);
    }
    
    enum MyEnum {
        FIRST,
        SECOND,
        THIRD
    }

Для единообразия также были созданы методы, позволяющие быстро регистрировать игровые правила ванильного типа.

import com.nerjal.unruled_api.UnruledApi;

    public static void registerBasicRules() {
        UnruledApi.registerInteger("my_int_rule", category, 5);
        UnruledApi.registerBoolean("my_bool_rule", category, false);
    }

Вы также можете получать их значения с помощью методов того же класса
Это устарело с релиза 2.0 (для Minecraft 1.21.11 и новее). Пожалуйста, используйте методы игровых правил напрямую, как теперь подразумевается кодом игры.

    public long getMyLongGamerules(ServerWorld dimension) { // ServerWorld — это класс маппингов Yarn. В Mojmap может быть Level или ServerLevel
        return UnruledApi.getLong(dimension.getGameRules(), myLongGamerule);
    }
    
    public Block getMyBlockRule(ServerWorld dimension) {
        // запрос правила с записью реестра возвращает само значение записи реестра, так как оно может быть установлено только если существует в реестре
        return UnruledApi.getRegistryEntry(dimension.getGameRules(), myBlockRegistryEntryRule);
    }

### Command Tweaks

Средний опыт использования игровых правил в ванильном Minecraft довольно печален.
Перебирать длинный список названий, пытаясь вспомнить нужное правило,
или, что ещё хуже, искать гипотетическое, может быть весьма раздражающе.

Поэтому Unruled API стремится хоть немного облегчить эту ношу, позволяя
вам перемещаться по тому же списку *по категориям*!

Теперь вы можете добавить название категории или полный ID (оба в верхнем регистре) в команду, и следующий
список будет содержать только правила из соответствующей категории.

Например, `/gamerule CHAT ` заставит игру предлагать вам только правила из
категории *chat*, согласно списку в меню создания мира.

Это также применимо ко всем модифицированным игровым правилам и категориям, а также к модифицированным типам игровых правил
из любых модов.

/gamerule [] []

### Gamerules Overrides

Переопределения игровых правил задаются для каждого измерения. Они позволяют игрокам устанавливать конкретные правила в конкретные значения
в нужном измерении, всё через команду `gamerule-override`.

У этой команды много применений:

* `gamerule-override` сама по себе и без аргументов позволяет получить список существующих переопределений в текущем измерении.
* `gamerule-override <dimension id>` позволяет получить список существующих переопределений в указанном измерении.
* `gamerule-override get <gamerule id>` позволяет запросить возможное переопределение для указанного игрового правила в текущем измерении.
* `gamerule-override set <gamerule id> <value>` позволяет установить переопределение для указанного игрового правила в заданное значение в текущем измерении.
* `gamerule-override unset <gamerule id>` позволяет удалить установленное переопределение для указанного игрового правила в текущем измерении.
* `gamerule-override in <dimension id> get <gamerule id>` позволяет запросить возможное переопределение для конкретного игрового правила в указанном измерении.
* `gamerule-override in <dimension id> set <gamerule id> <value>` позволяет установить переопределение для указанного игрового правила в заданное значение в указанном измерении.
* `gamerule-override in <dimension id> unset <gamerule id>` позволяет удалить установленное переопределение для указанного игрового правила в указанном измерении.

Переопределения игровых правил хранятся в папке данных измерения, в файле `gamerules.dat`.
Удаление его, пока сервер выключен/мир не запущен, просто удалит все переопределения для измерения.

Кроме того, для вашего удобства `get`, `set` и `unset` во всех случаях также
поддерживают фильтрацию по категориям для более простого использования.
Таким образом, вы можете использовать команду следующим образом:

/gamerule-override in set []

### Configurable Default Values

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

Чтобы задать их, вам нужно всего лишь создать файл `config/default_gamerules.json`, и для каждого игрового правила, для которого вы хотите
добавить значение по умолчанию, задать пару ключ-значение с нужным новым значением, записанным как строка. (из-за ограничений в
коде Mojang для простого JSON-парсинга принимаются только строковые значения, всё остальное просто игнорируется)

Пример:
```json
{
  "doDaylightCycle": "false",
  "mobGriefing": "false"
}

Очевидно, это так же хорошо работает с модифицированными игровыми правилами и типами игровых правил!

Custom Gamerule Categories

Начиная с 1.21.11, категории игровых правил теперь являются реестром. Следующее относится только к версиям игры до этой

Разработчики могут легко зарегистрировать новые пользовательские категории игровых правил, которые будут добавлены прямо в перечисление категорий! Однако вам нужно сделать это рано в процессе загрузки игры, то есть до того, как загрузится класс игровых правил.

Это можно сделать на Fabric с помощью preLaunch entrypoint, на (Neo)Forge при инициализации вашего класса @Mod, или на любом лаунчере из вашего mixin config plugin.

Вам нужно всего лишь добавить реализацию CategoryProvider в набор UnruledEarlyUtils.CATEGORY_PROVIDERS.

Интерфейс CategoryProvider — это класс, похожий на поставщика String, который позволяет опционально реализовать потребителя категории при создании соответствующей категории. Предоставленная строка будет установлена как имя категории, но не позволит создавать дубликаты (то есть, если два мода захотят добавить одну и ту же категорию, будет создана только одна, но оба провайдера её получат)

Как использовать в вашем проекте

Вы можете внедрить этот мод в свой проект с помощью Modrinth maven. Не стесняйтесь прочитать официальную документацию.

Добавьте репозиторий Modrinth maven

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

Импортируйте мод

пример для loom:

dependencies {
    // using modApi allows your project's dependents to also import dependencies by default
    modApi "maven.modrinth:unruled-api:${project.unruled_version}"
}

пример для (neo)forgeGradle:

dependencies {
    implementation "maven.modrinth:unruled-api:${project.unruled_version}"
}

По причинам авторских прав мы требуем, чтобы вы не включали (JiJ, jar-in-a-jar, shadow и т. д.) этот мод в свой собственный. Спасибо за понимание.