Guide API

Learn how to use existing Guide domains, and register your own, for use in your own Screens.

INFO

For instructions on modifying rules for existing Guide domains, see the resource pack page

How does this API work?

The Guide API has a few distinct concepts:

• Guide Domain: Holds a list of valid facts in the domain, for example, controlify:in_game is a domain which holds facts such as controlify:on_ground.
• Guide Context: Holds data which facts use to determine if they are true or false.
• Guide Instance: Applies to a specific domain, holds current state of the facts applied to a context and the rules which pass.

Registering facts to a GuideDomain

You may want to add additional facts relating to your mod to an existing GuideDomain, such as controlify:in_game, which you would then use in an embedded resource pack to add additional rules.

You may want to create and render your own GuideDomain, and you need to register your own set of facts.

@Override
public void onControlifyPreInit(PreInitContext ctx) {
    ctx.guides().inGame().registerFact(
            Identifier.fromNamespaceAndPath("my_mod", "holding_wand"),
            ctx -> ctx.player().isItemInMainHandModdedWand()
    );
}

Now resource packs can use your additional rule. Refer to the resource pack page to create rules using resource packs.

If your mod is not loaded or does not register a referenced fact for whatever reason, the state of the fact will be false, and a warning will be issued on resource reload that an unknown fact was referenced.

Rendering a Guide

To render a Guide, you must create a new GuideInstance, update its facts, and then finally render it.

Because the only time you have API-safe access to existing Guide Domains is during pre-init, you must capture a reference to it to use it later.

private GuideDomain<InGameCtx> inGameGuideDomain;

@Override
public void onControlifyPreInit(PreInitContext ctx) {
    this.inGameGuideDomain = ctx.guides().inGame();
}

Once you have a reference to a domain, you can create an instance from it.

GuideInstance<InGameCtx> guideInstance = guideDomain.createInstance();

Ruleset and fact resolution is completely independent of rendering, you may update the guide once every tick, while you render it every frame.

Every fact in a GuideDomain requires a specific context type (FactCtx), you must construct this type to be able to update an instance.

void tick() {
    guideInstance.update(new InGameCtx(...), font);
}

Then, you can render it. You can either use the extractRenderState method, or you can get a Renderable which you can then add to a Screen.

class MyScreen extends Screen {
    @Override
    protected void init() {
        boolean bottomAligned = true; // if false, top aligned
        boolean textContrast = false; // adds a translucent background behind text
        this.addRenderableOnly(this.guideInstance.renderable(bottomAligned, textContrast));
    }
}

Registering your own domain

It is very simple to register your own domain. Once registered, Controlify handles resource reloading for you.

Before registering a new domain, you need to decide whether it will use an existing fact context (either InGameCtx or ContainerCtx), or your own. This is the data you give to the guide instance each update, which the facts use to resolve their state. Here is an example fact context.

public record ModdedCtx(
        ModClient modClient
) implements FactCtx {}

Each fact you register would then be able to reference modClient and therefore the rest of your mod's state.

@Override
public void onControlifyPreInit(PreInitContext ctx) {
    GuideDomain<ModdedCtx> domain = ctx.guides().registerCustomDomain(Identifier.fromNamespaceAndPath("my_mod", "mod_context"));
    domain.registerFact(...);
}