Условная загрузка ресурсов 26.1.2

Руководство по настройке условной загрузки данных вашего мода.

При разработке интеграций с другими модами часто возникает необходимость определить, при каких условиях должны загружаться ресурсы вашего мода. Для этих целей Fabric API предлагает механизм условной загрузки ресурсов (Resource Conditions).

По умолчанию этот API можно использовать с рецептами, достижениями, таблицами добычи, предикатами и модификаторами предметов.

Условную загрузку ресурсов можно добавлять как через генерацию данных, так и при написании JSON-файлов вручную. Дополнительную информацию о том, как добавлять условную загрузку ресурсов через datagen, см. в документации по генерации данных.

Условия загрузки добавляются в корень JSON-файла.

Рецепт с условием, благодаря которому он загружается только тогда, когда тег заполнен (не пуст).

{
  "fabric:load_conditions": [
    {
      "condition": "fabric:tags_populated",
      "registry": "minecraft:item",
      "values": [
        "minecraft:dirt"
      ]
    }
  ],
  "type": "minecraft:crafting_shapeless",
  "category": "building",
  "ingredients": [
    "#minecraft:sand"
  ],
  "result": {
    "id": "minecraft:sand"
  }
}

Встроенные условия

Fabric API предоставляет девять встроенных условий, которые вы можете использовать в своем моде. Условия могут выполняться успешно (возвращать true) или неуспешно (возвращать false).

Операторы

Это стандартные логические (булевы) операторы.

Истина (True)

Всегда возвращает true:

{
  "fabric:load_conditions": [
    {
      "condition": "fabric:true"
    }
  ]
}

Ложь (False)

Всегда возвращает false:

{
  "fabric:load_conditions": [
    {
      "condition": "fabric:false"
    }
  ]
}

Не (Not)

Инвертирует условие загрузки, указанное в value. Например, следующее условие вернёт false:

{
  "fabric:load_conditions": [
    {
      "condition": "fabric:not",
      "value": {
        "condition": "fabric:true"
      }
    }
  ]
}

Или (Or)

Выполняется успешно, если успешно выполняется хотя бы одно из условий в values. Например, следующее условие вернёт true:

{
  "fabric:load_conditions": [
    {
      "condition": "fabric:or",
      "values": [
        {
          "condition": "fabric:true"
        },
        {
          "condition": "fabric:not",
          "value": {
            "condition": "fabric:true"
          }
        }
      ]
    }
  ]
}

И (And)

Возвращает true, если выполняются абсолютно все условия в values. Например, следующее условие вернёт false:

{
  "fabric:load_conditions": [
    {
      "condition": "fabric:and",
      "values": [
        {
          "condition": "fabric:true"
        },
        {
          "condition": "fabric:not",
          "value": {
            "condition": "fabric:true"
          }
        }
      ]
    }
  ]
}

Загружены все моды

Возвращает true, если все моды в values загружены. Например, следующее условие выполнится успешно если, и example-mod, и another-mod загружены:

{
  "fabric:load_conditions": [
    {
      "condition": "fabric:all_mods_loaded",
      "values": [
        "example-mod",
        "another-mod"
      ]
    }
  ]
}

Загружен любой мод

Возвращает true, если хотя бы один из модов в values загружен. Например, следующее условие выполнится успешно, если загружен либо example-mod, либо another-mod, либо оба:

{
  "fabric:load_conditions": [
    {
      "condition": "fabric:any_mods_loaded",
      "values": [
        "example-mod",
        "another-mod"
      ]
    }
  ]
}

Теги заполнены (Tags Populated)

Возвращает true, если указанный регистр содержит все теги из values. Например, следующее условие выполнится успешно, если загружен тег предметов example-mod:smelly_items:

{
  "fabric:load_conditions": [
    {
      "condition": "fabric:tags_populated",
      "registry": "minecraft:item",
      "values": [
        "example-mod:smelly_items"
      ]
    }
  ]
}

Включённые функции (Features Enabled)

Возвращает true, если все feature-флаги в features включены. Например, следующее условие выполнится успешно, если включены и minecraft:vanilla, и minecraft:redstone_experiments:

{
  "fabric:load_conditions": [
    {
      "condition": "fabric:features_enabled",
      "features": [
        "minecraft:vanilla",
        "minecraft:minecart_improvements"
      ]
    }
  ]
}

Регистр содержит (Registry Contains)

Возвращает true, если регистр содержит все идентификаторы из values. Например, следующее условие выполнится успешно, если в регистре существует идентификатор minecraft:cobblestone:

{
  "fabric:load_conditions": [
    {
      "condition": "fabric:registry_contains",
      "registry": "minecraft:block",
      "values": [
        "minecraft:cobblestone"
      ]
    }
  ]
}

Пользовательские условия (Custom Conditions)

ПРЕДВАРИТЕЛЬНЫЕ ТРЕБОВАНИЯ

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

Fabric API также предоставляет гибкость для создания собственных условий загрузки ресурсов.

Чтобы продемонстрировать это, мы создадим условие, которое проверяет текущую дату. Его можно использовать для особого поведения в праздники, например на Хэллоуин или 1 апреля.

Подготовка вашего условия

Для простоты мы создадим вспомогательный метод, который создаёт экземпляр вашего условия по имени и MapCodec. Поместите этот метод в класс ModResourceConditions (или другим именем, которым захотите его назвать).

TIP

Fabric делает то же самое со своими встроенными условиями. Вы можете обратиться к классу DefaultResourceConditionTypes, чтобы увидеть, как это работает.

public class ModResourceConditions {
	private static <T extends ResourceCondition> ResourceConditionType<T> createResourceConditionType(String name, MapCodec<T> codec) {
		return ResourceConditionType.create(Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, name), codec);
	}
}

Создание вашего условия

Условие загрузки ресурса состоит из трёх частей:

• Конструктор, принимающий значения.
• MapCodec для сериализации этих значений.
• Метод test, использующий эти значения для определения, должно ли условие считаться успешным.

Мы создадим новый класс для условия ресурса, назвав его DateMatchesResourceCondition. Сначала создайте новую запись (record), которая принимает int для месяца и int для дня:

public record DateMatchesResourceCondition(int month, int day) implements ResourceCondition {
}

Затем добавьте MapCodec, который отражает то, что принимает конструктор:

public static final MapCodec<DateMatchesResourceCondition> CODEC = RecordCodecBuilder.<DateMatchesResourceCondition>mapCodec(instance -> instance.group(
		ExtraCodecs.POSITIVE_INT.fieldOf("month").forGetter(DateMatchesResourceCondition::month),
		ExtraCodecs.POSITIVE_INT.fieldOf("day").forGetter(DateMatchesResourceCondition::day)
).apply(instance, DateMatchesResourceCondition::new)).validate(DateMatchesResourceCondition::validate);

Что такое validate?

Этот кодек использует метод .validate, чтобы убедиться, что указанная дата может существовать, используя логику вспомогательного метода, также называемого validate:

private static DataResult<DateMatchesResourceCondition> validate(DateMatchesResourceCondition o) {
	try {
		MonthDay.of(o.month(), o.day());
	} catch (DateTimeException e) {
		return DataResult.error(e::getMessage);
	}

	return DataResult.success(o);
}

Такая валидация актуальна только для данного конкретного примера.

Далее добавим метод test, который проверяет текущую дату. Этот пример основан на логике из самой ванильной игры — класса SpecialDates.

@Override
public boolean test(RegistryOps.@Nullable RegistryInfoLookup registryInfo) {
	var monthDay = MonthDay.of(this.month, this.day);
	return SpecialDates.dayNow().equals(monthDay);
}

Регистрация вашего условия

Вернёмся в ModResourceConditions. Теперь мы можем зарегистрировать наше условие ресурса:

public static final ResourceConditionType<DateMatchesResourceCondition> DATE_MATCHES =
		createResourceConditionType("date_matches", DateMatchesResourceCondition.CODEC);

public static void register() {
	ResourceConditions.register(DATE_MATCHES);
}

Затем на этот тип условия можно будет ссылаться и из DateMatchesResourceCondition:

@Override
public ResourceConditionType<?> getType() {
	return ModResourceConditions.DATE_MATCHES;
}

Не забудьте вызвать ModResourceConditions.register() в инициализаторе вашего мода:

public class ExampleModResourceConditions implements ModInitializer {
	@Override
	public void onInitialize() {
		ModResourceConditions.register();
	}
}

Использование вашего условия

Теперь у нас есть условие, которое выполняется успешно, если системная дата совпадает с датой, указанной в условии загрузки ресурса. Например, это условие будет выполняться только 1 апреля:

{
  "fabric:load_conditions": [
    {
      "condition": "example-mod:date_matches",
      "day": 1,
      "month": 4
    }
  ]
}