Compatibility

To be brief, some mods are moved along with vanilla elements. Those that are registered by Raised (either by the mod or automatically via the (Neo)Forge registry) will have a layer entry registered with Raised, and need to be individually configured. For deeper insight, continue reading below...

Raised's API allows a mod to register a overlay layer with it so the user can control its movement across the screen. This layer may be individually controlled or synced to the movement of another layer.

Several vanilla layers are registered that you may be familiar with. An additional minecraft:other layer catches some edge cases that are injected int he the head and tail of the main render method across all versions.

On Fabric, all vanilla layers are encapsulated in translations via mixins. Since most mods on Fabric tend to mixin to these points that correspond to their own overlay, these mod overlays are usually translated along with the vanilla HUD.

On (Neo)Forge, Raised works in several ways. Most vanilla layers are translated through the respective (Neo)Forge GUI render event (RenderGameOverlayEvent/RenderGuiOverlayEvent/RenderGuiLayerEvent). As such, any mods that render their overlays on these events will also get translated with them. Raised adds listeners that push and translate on highest priority on the Pre event and pops on the lowest priorty on the Post event (or the Pre event if it is cancelled).

Mods that register their overlays to (Neo)Forge's registry (OverlayRegistry/RegisterGuiOverlaysEvent/RegisterGuiLayersEvent) are automatically registered to Raised's layer registry. These are then translated on the GUI layer event, except, as being registered layers, they have their own entries for the user to control.

Please note that Forge has gutted its overlay events and registry since 1.20.5.

Through Raised's API, a mod may get the x-axis and y-axis offsets for any layer using getX(name) and getY(name). These return the calculated offsets from the layer's configuration (the displacement is multiplied by the direction to either make it negative, zero, or positive). If the layer is configured to be synced to another layer that is found in the config, the synced layer's displacement is used in the calculation instead.

While you may simply use a vanilla layer to control your own overlay's movement, it is recommended to register your layer via register(name). This allows a user to individually control your overlay's movement. The register method is limited to creating a default configuration in the API for now, but you may create a layer configuration at your own risk (this is liable to change for possibly replacing the simple layer sync with a group system).

You may optionally add a texture to identify your layer in the config screen. This is found under raised:textures/gui/layer/<namespace>/<path>.png. The namespace and path correspond to the ResourceLocation name of your layer.

The best way to add support is to create a compatibility class to that you call when registering a layer and translating your overlay with. Conditionally call the methods using your mod loader's way of checking for a certain mod.

Depending on your mod loader, register your layer in your initialization.

if (FabricLoader.isModLoaded("raised")) {
   Compatibility.register();
}

if (ModList.get().isLoaded("raised")) {
   Compatibility.register();
}

In your compatibility class, you can register your layer with either a string or ResourceLocation.

public void register() {
   RaisedApi.register("my_mod:my_layer");
   RaisedApi.register(ResourceLocation.fromNamespaceAndPath("my_mod", "my_other_layer"));
}

The simplest way to integrate Raised into your rendering is to wrap your render method in a push, translate, and a pop. Call the compatibility class's methods from the aforementioned conditional.

public void render(GuiGraphics guiGraphics) {
   guiGraphics.pose().pushMatrix();
   if (FabricLoader.isModLoaded("raised")) {
      Compatibility.translate(guiGraphics);
   }
   ...
   guiGraphics.pose().popMatrix();
}

In your compatibility class.

public void translate(GuiGraphics guiGraphics) {
   guiGraphics.pose().translate(RaisedApi.getX("my_mod:my_layer"), RaisedApi.getY("my_mod:my_layer"));
}

It may be advisable to also wrap things in some null checks, although (I hope that) this format should last a good long time.