Unruled API

Unruled API

允许创建新的游戏规则形式，超越原版受限的整数和布尔值。

该模组使开发者能够轻松创建新的浮点、长整型、双精度、字符串、文本、枚举驱动、 实体选择器乃至注册表条目游戏规则，使用各自的构建器， 所有这些均可通过 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 的方法或直接创建构建器结果相同，参数也相同。
                // 但请注意，在某些情况下，强烈建议使用特定的构建器，例如字符串
                // 规则、枚举和动态注册表条目规则，因为它们对值的处理和
                // 命令处理更为精细。
                .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);
    }

命令改进

在 Minecraft 原版中使用游戏规则的体验较为不佳。 浏览一长串名称，试图记住所需规则的名称， 甚至更糟，寻找一个假设存在的规则，都可能相当令人烦恼。

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

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

例如，/gamerule CHAT 将仅提示您 聊天 类别中的规则（依据世界创建菜单中的列表）。

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

/gamerule [<类别名称或完整 ID>] <游戏规则名称或 ID> [<值>]

游戏规则覆盖

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

该命令有多种用途：

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

游戏规则覆盖存储在维度的数据文件夹中，文件名为 gamerules.dat。 在服务器离线或世界未运行时删除该文件，将简单地移除该维度的所有覆盖。

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

/gamerule-override in <维度 ID> set [<类别名称或完整 ID>] <游戏规则名称或 ID> <值>

可配置的默认值

该功能对于整合包作者尤其重要，允许设置自定义值作为世界创建时的默认游戏规则值。

要设置它们，您只需创建一个 config/default_gamerules.json 文件，并为每个要设置默认值的游戏规则 添加一个键值对，以字符串形式设置所需的新值。（由于 mojang 代码在 JSON 解析方面的限制， 仅接受字符串值，其他任何类型都将被忽略）

示例：

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

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

自定义游戏规则类别

自 1.21.11 起，游戏规则类别已成为注册表。以下内容仅适用于早于此版本的游戏版本

开发者可以轻松注册新的自定义游戏规则类别，这些类别将直接添加到类别枚举中！ 但您需要在游戏加载过程的早期完成此操作，即在游戏规则类加载之前。

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

您只需将 CategoryProvider 实现添加到 UnruledEarlyUtils.CATEGORY_PROVIDERS 集合中。

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 等）到您自己的模组中。感谢您的理解。