Resource Conditions 26.1.2

A guide to allowing your mod's data to load conditionally.

When designing integrations with other mods, a common need is a way to define when your mod's resources should be loaded. For this reason, Fabric API offers Resource Conditions.

By default, this API can be used with recipes, advancements, loot tables, predicates, and item modifiers.

Resource conditions can either be added via data generation or when writing JSON by hand. For more information about how to add resource conditions via data generation, see the Data Generation docs.

Load conditions are added to the root of a JSON file.

A recipe with a condition that makes it only load when a tag is populated.

{
  "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"
  }
}

Built-in Conditions

Fabric API provides nine built-in conditions for your mod to use.

Operators

These are the standard boolean operators.

True

Always succeeds:

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

Not

Inverts the load condition specified in value. For example, the following will fail:

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

Or

Succeeds if at least one of the conditions in values succeeds. For example, the following will succeed:

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

And

Succeeds if every condition in values succeeds. For example, the following will fail:

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

All Mods Loaded

Succeeds if all mods in values are loaded. For example, the following succeeds only if both example-mod and another-mod are loaded:

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

Any Mods Loaded

Succeeds if at least one of the mods in values is loaded. For example, the following will succeed if either example-mod, or another-mod, or both, are loaded:

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

Tags Populated

Succeeds if the specified registry contains all tags in values. For example, the following will succeed if the example-mod:smelly_items item tag is loaded:

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

Features Enabled

Succeeds if all feature flags in features are enabled. For example, the following will succeed if both minecraft:vanilla and minecraft:redstone_experiments are enabled:

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

Registry Contains

Succeeds if the registry contains all of the identifiers in values. For example, the following will succeed if minecraft:cobblestone exists in the registry:

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

Custom Conditions

PREREQUISITES

You must first understand how to create a codec before setting a custom resource condition.

Fabric API also provides the flexibility of creating your own resource conditions.

To demonstrate this, we'll create a condition that checks the current date. This could be used for special behavior on holidays like Halloween or April Fools.

Preparing Your Condition

For simplicity, we'll be creating a helper method that instantiates your resource condition from a name and a MapCodec. You should put this method in a class called ModResourceConditions (or whatever you want to name it).

TIP

Fabric does the same with its built-in conditions; you can refer to the DefaultResourceConditionTypes class to see this in action.

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);
	}
}

Creating Your Condition

A resource condition consists of three parts:

• A constructor that accepts values.
• A MapCodec to serialize those values.
• A test method that uses the values to determine whether the condition should pass.

We'll create a new class for the resource condition, named DateMatchesResourceCondition. First, create a new record that accepts an int for the month, and an int for the day:

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

Next, add a MapCodec that reflects what the constructor accepts:

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);

What is validate?

This codec uses the .validate method to ensure the provided date can exist, using the logic in a helper method also called 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);
}

This is only relevant in this exact example.

Next, we'll add a test method that checks the current date. This example is based on logic from vanilla itself, in SpecialDates.

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

Registering Your Condition

Back in ModResourceConditions, we can now register our resource condition:

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

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

This condition type can then be referenced from DateMatchesResourceCondition as well:

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

Be sure to call ModResourceConditions.register in your mod's initializer:

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

Using Your Condition

Now, we have a condition that succeeds if the system date matches the date provided in the resource condition. For example, this condition will only succeed on April Fools:

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