What are guides?

Guides are a feature of Controlify that shows hints to the player about what buttons to press to perform certain actions.

Since version 2.3.0, guides are data-driven, meaning you can override the default guides with your own.

Concepts

There are three main concepts you need to understand to create your own guides.

1. Fact
   • A fact is a piece of information about the current game state.
   • For example, the fact controlify:on_ground is true when the player is on the ground.
2. Rule
   • A rule contains a list of permitting facts, and a list of forbidding facts.
   • If all permitting facts are true and no forbidding facts are true, the rule is applied if its binding is bound.
   • For example, a rule for controlify:jump requires the fact controlify:on_ground, then show some text and the button glyph for the jump binding.
3. Domain
   • A domain contains all loaded facts and rules for a specific type of guide.
   • controlify:in_game is a domain that has in-game specific facts, and rules to show when the player is in-game.
   • controlify:container is a domain that has facts and rules for when the player is in a container GUI, like the inventory or a chest.
   • For example, you wouldn't have a rule for controlify:on_ground in the controlify:container domain, since it's irrelevant in a container GUI.

Creating custom rules

Controlify only allows resource packs to add and override rules, not facts or domains.

If Controlify does not have a fact for your specific use case, you must create a mod that adds the fact to Controlify, or submit a feature request to get it added to Controlify itself.

{
    "override": false,
    "rules": [
        {
            "for": "controlify:jump",
            "where": "left",
            "when": ["controlify:on_ground"],
            "forbid": [],
            "then": "Jump"
        }
    ]
}

This example shows a rule that applies when the player is on the ground, and the controlify:jump binding is bound. When the rule applies, it shows the text "Jump" and the glyph for the controlify:jump binding.

As well as literal text such as "Jump", Controlify supports the Minecraft text component format which allows you to use translations and styling. For example, you can use "then": {"translate": "mypack.jump"} to use a translation key sourced from your pack's language files.

A rule can be displayed either on the left or right side of the screen, this is defined by the "where" field.

Because "override": false, this resource pack will not override the default rules, but instead add an additional rule. If you want to override the default rules, or any resource pack below yours, set "override": true.

Stacking rules

You can stack multiple rules for the same binding, the first rule that succeeds will be applied, the rest will be ignored. However, if the rules have different locations (e.g. left and right), they will both be applied.

{
    "override": false,
    "rules": [
        {
            "for": "controlify:jump",
            "where": "left",
            "when": ["controlify:in_water"],
            "forbid": [],
            "then": "Swim Up"
        },
        {
            "for": "controlify:jump",
            "where": "left",
            "when": ["controlify:on_ground"],
            "forbid": [],
            "then": "Jump"
        }
    ]
}

In this snippet, the first rule will apply when the player is in water, and the second rule will apply when the player is on the ground.

Even when the player is in water and touching the ground, only the first rule will apply, because it is the first rule that matches its conditions.

Facts

Controlify has a set of built-in facts that you can use in your rules.

Below is a list of the built-in facts for each domain.

Common facts

These facts are available in all domains.

controlify:in_game

controlify:container