Using OptiGUI in a mod
These are the basics of OptiGUI, which gives you some idea on how to use it within your mods.
Depending on OptiGUI
OptiGUI doesn't have a maven repository. You can install it from Modrinth Maven or Curse Maven.
- Add OptiGUI API JAR to your
build.gradle(.kts)
as described in one of the above links (classifier:api
) - Add OptiGUI dependencies to the
modLocalRuntime
configuration inside the dependencies block - Extract the nested JARs from the OptiGUI jar's
META-INF/jars
folder to your local mods folder. You can do this manually or withbuild.gradle(.kts)
. Here's an example
Resource loading
When the game (re)loads resources, OptiGUI reads OptiGUI properties and OptiFine properties, and creates a filter chain.
For each selector in each group in each OptiFine resource, OptiGUI invokes the registered ISelector
(Java syntax) to create a filter for the given selector. A ConjunctionFilter
(Java syntax) will be created for a group containing these filters, and this filter will be added to the filter chain.
Filters added to the filter chain will be evaluated sequentially until one returns a non-null value. This will be cached until the end of the current game tick, and will be used as a the replacement texture of the GUI screen.
Adding a container
If your mod adds a new container with a GUI screen, add the GUI screen's texture to your mod's metadata.
If you use or extend a vanilla block entity or entity, OptiGUI has built-in support for that. However, you may want to create selectors for your block entity or entity subclass, which can be used by resource packs.
If you make your own block entity or entity, most OptiGUI selectors won't work. You'll need to create your own selectors, which can be used by resource packs.
The interaction
- Before an interaction, OptiGUI can be notified about an upcoming interaction using
Interaction.prepare
(Java syntax). This is called internally, when the player right clicks a block or entity. This method call returnsfalse
, and is ignored while an interaction is ongoing. - An interaction begins when the game opens a GUI screen
- An interaction ends, when the open GUI screen gets closed
- Use
IBeforeInteractionBeginCallback
(Java syntax) to get notified right before an interaction begins.
Selectors
Selectors create a filter from a string description in an OptiGUI INI file. For example, name = OptiGUI
is a selector, name
is the selector key, and OptiGUI
is the string description.
The created filters process an Interaction
(Java syntax) once every game tick, and may provide a replacement texture. This texture will be cached for subsequent GUI screen rendering calls within the game tick.
To create a selector:
- Create a public class
- Implement
ISelector
(Java syntax) (Kotlin examples) - Register it with
SelectorRegistry.register
(Java syntax)
OptiGUI custom metadata
fabric.mod.json
allows custom fields to be specified.
OptiGUI will read this metadata from each mod where present.
Container default GUI texture
Add a JSON object named optigui:container_default_gui_textures
to the custom fields to define the texture of a container's screen:
{
//...
"custom": {
"optigui:container_default_gui_textures": {
"modid:container1": "modid:path/to/textures/container1.png",
"modid:container2": "modid:path/to/textures/container2.png"
}
}
}
Container modid:container1
has the texture modid:path/to/textures/container1.png
, and modid:container2
has the texture modid:path/to/textures/container2.png
.