Unruled API

Unruled API

允许创建超越原版限制性整数和布尔值的新型游戏规则。

本模组使开发者能够轻松创建新的浮点数、长整数、双精度数、字符串、文本、枚举驱动、实体选择器甚至注册表条目的游戏规则，使用各自的构建器，所有方法均通过 com.nerjal.unruled_api.UnruledApi 类的静态方法提供。

它还提供了在注册新游戏规则时添加值验证器的方法，从而可以限制游戏规则的有效值范围。例如，可用于仅允许整数游戏规则接受奇数值。

此外，本模组还添加了按维度覆盖游戏规则的功能！这些覆盖将应用于其指定的维度（前提是查询正确）。

有关详细信息，请参阅[游戏规则覆盖](#gamerules-overrides)。

游戏规则注册

示例：

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方法或直接创建构建器效果相同，参数也相同。
                // 但请注意，在某些情况下，强烈建议使用指定的构建器，例如字符串规则、枚举和动态注册表条目规则，因为它们对其值和命令处理有更具体的处理。
                .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);
        // 快速注册方法始终遵循相同的参数顺序：名称、类别、初始值、游戏规则类型特定参数
        // 枚举规则除外，其枚举类位于初始值之前
        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);
    }

命令调整

在《我的世界》原版中使用游戏规则的体验相当糟糕。

浏览一长串名称，试图记住你需要的那个，甚至更糟的是，搜索一个假设存在的规则，可能非常烦人。

因此，Unruled API旨在稍微减轻这种负担，允许你按类别浏览同一列表！

因此，你现在可以在命令中添加类别名称或完整ID（均为大写），随后的列表将仅包含相应类别中的规则。

例如，/gamerule CHAT 然后你的游戏将只建议你聊天类别中的规则，根据世界创建菜单的列表。

这也适用于所有模组添加的游戏规则和类别，以及来自任何模组的所有模组游戏规则类型。

/gamerule []  []

游戏规则覆盖

游戏规则覆盖按维度设置。它们允许玩家通过 gamerule-override 命令在所需维度中将特定规则设置为特定值。

此命令有多种用途：

• 单独使用 gamerule-override 且不带参数可获取当前维度中现有覆盖的列表。
• gamerule-override 可获取指定维度中现有覆盖的列表。
• gamerule-override get 可查询当前维度中指定游戏规则的潜在覆盖。
• gamerule-override set 可在当前维度中为指定游戏规则设置覆盖到给定值。
• gamerule-override unset 可移除当前维度中为指定游戏规则设置的覆盖。
• gamerule-override in get 可查询给定维度中特定游戏规则的潜在覆盖。
• gamerule-override in set 可在提供的维度中为指定游戏规则设置覆盖到给定值。
• gamerule-override in unset 可移除提供的维度中为指定游戏规则设置的覆盖。

游戏规则覆盖存储在维度的数据文件夹中，作为 gamerules.dat 文件。

在服务器离线/世界未运行时删除该文件将直接移除该维度的所有覆盖。

此外，为方便起见，所有情况下的 get、set 和 unset 也支持按类别过滤，以便于使用。

因此，你可以如下使用命令：

/gamerule-override in  set []  

可配置的默认值

此功能尤其与整合包创作者相关，它允许设置自定义值，作为世界创建时使用的默认游戏规则值。

要设置它们，你只需要创建一个 config/default_gamerules.json 文件，并为每个你想添加默认值的游戏规则，设置一个键值对，其中包含所需的新值，设置为字符串。（由于Mojang代码中易于JSON解析的限制，只接受字符串值，其他任何内容都将被忽略）

示例：

{
  "doDaylightCycle": "false",
  "mobGriefing": "false"
}

显然，这同样适用于模组添加的游戏规则和游戏规则类型！

自定义游戏规则类别

自1.21.11起，游戏规则类别现在是一个注册表。以下内容仅与此版本之前的游戏版本相关

开发者可以轻松注册新的自定义游戏规则类别，这些类别将直接添加到类别枚举中！

但是，你需要在游戏加载过程的早期完成此操作，即在游戏规则类加载之前。

在Fabric上，可以通过 preLaunch 入口点完成；在(Neo)Forge上，可以在初始化你的 @Mod 类时完成；在任何启动器上，可以通过你的mixin配置插件完成。

你只需要向 UnruledEarlyUtils.CATEGORY_PROVIDERS 集合添加一个 CategoryProvider 实现。

CategoryProvider 接口是一个类似字符串供应商的类，允许在创建匹配类别时可选地实现类别消费者。提供的字符串将设置为类别名称，但不允许重复条目（即，如果两个模组想要添加相同的类别，只会创建一个，但两个提供者都会收到它）

如何在你的项目中使用

你可以使用Modrinth maven在你的项目中实现此模组。请务必阅读官方文档。

添加Modrinth maven仓库

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

导入模组

loom示例：

dependencies {
    // 使用modApi允许你的项目依赖者也默认导入依赖项
    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等）在你自己的模组中。感谢你的理解。