Skip to content

Developing with libhud

Jump to bottom
Cheos edited this page Apr 12, 2023 · 2 revisions

Build setup

To build against libhud, you first have to include a maven repository containing the mod to your build.gradle:

repositories {
	exclusiveContent {
		forRepository { maven { url 'https://api.modrinth.com/maven' }} // modrinth
		filter { includeGroup 'maven.modrinth' }
	}
}

Then, add the compile-time dependency to your dependency-block as follows:

modCompileOnly 'maven.modrinth:libhud:<version>'

where <version> equals an appropriate version string or id found here.

Alternatively, if you want to test with libhud in your development environment, you can instead add it as an implementation dependency:

modImplementation 'maven.modrinth:libhud:<version>'

where <version> equals an appropriate version string or id found here.

libhud does not use any 3rd-party libraries, so you won't have to worry about excluding them from your build setup.

Using the API

There's generally two ways to use the libhud API, both of which can be used together if desired: the libhud entrypoint and the static API.

libhud entrypoint

First, you will have to add an entrypoint class to your fabric.mod.json:

"entrypoints": {
  "libhud": [ "com.package.modid.LibhudCompat" ]
}

Of course, you also have to add the referenced class:

package com.package.modid;

import dev.cheos.libhud.api.LibhudApi;

public class LibhudCompat implements LibhudApi {

}

The LibhudApi interface defines the following event handler methods which can be overridden as desired:

  • void on(Event event)
  • void onRegisterComponents(RegisterComponentsEvent event)
  • void onRender(RenderEvent event)
  • void onRenderComponent(RenderComponentEvent event)

These handler methods will automatically be called whenever a matching event (as described by the method parameter) is fired on an event bus internal to libhud.
Events generally follow a hierarchical structure, and thus every event must extend Event.class.
So, the handler

  • #on(Event) gets called on every event fired,
  • #onRender(RenderEvent) gets called for every render event (include RenderComponentEvents),
  • #onRenderComponent(RenderComponentEvent) gets called only for rendering hud components,
  • and #onRegisterComponents(RegisterComponentsEvent) gets called when libhud is ready for hud components to be registered.

Static API

Alternatively to registering an entrypoint, static methods provided by libhud can be used as well:

  • dev.cheos.libhud.Libhud defines methods for manually registering event listeners to the internal event bus.
  • dev.cheos.libhud.ComponentRegistry.INSTANCE defines methods identical to the ones in RegisterComponentsEvent and can be used at all times.

It is generally recommended to register event listeners in your mod constructor, or either of the fabric preLaunch or main entrypoints.
However, hud components should be registered in the fabric client entrypoint, when receiving a RegisterComponentsEvent or any time later.

Events in Detail

All events contain an attribute phase (#getPhase()) which denotes the general type of event fired:

  • Event.EventPhase.NONE -> standalone event, generally NOT cancellable
  • Event.EventPhase.PRE -> event fired at the start of an action, usually cancellable
  • Event.EventPhase.POST -> event fired at the end of an action, generally NOT cancellable additionally, all events denote whether they are cancellable (#isCancellable()), and if they are cancellable it is possible to #cancel() them, thus preventing their action from happening. Cancelled events also are not broadcast to (most) further event listeners.

RenderEvent

The RenderEvent contains attributes specific to render calls, specifically the poseStack (#getPoseStack()), partialTicks (#getPartialTicks()) and window (#getWindow()) instances.

RenderComponentEvent

The RenderComponentEvent, extending RenderEvent, provides all rendering-specific attributes, alongside a componentId (#getComponentId()) and a component (#getComponent()) instance.

RegisterComponentsEvent

The RegisterComponentsEvent provides methods to easily register hud components to libhud.

Hud components

Hud components are any classes implementing dev.cheos.libhud.api.Component (including anonymous classes and lambdas). They are registered in combination with an id ('name'). Alternatively, they can be wrapped into a NamedComponent by using either of the Component#named(ResourceLocation, Component) or Component#named(String, Component) methods.

Examples

A sample implementation of the API can be found in one of my other mods, Armorpoints++:

Clone this wiki locally