oωo (owo-lib)

oωo is a general utility, GUI, and config library for Fabric modding designed to reduce code verbosity. Key features include:

• owo-ui: A declarative UI library for building dynamic screens.
• owo-config: A customizable configuration system built on owo-ui that supports server-client synchronization.
• Registration System: A generic, automatic system for handling registries.
• Item Group Extensions: Allows for sub-tabs, custom buttons, and textures within mod item groups.
• Networking Layer: Features automatic serialization and handshaking for client compatibility.
• Particle Helpers: Client-side tools for composing multi-particle effects.
• Rich Text Translations: Enables using Minecraft's text component format directly in language files.

To use oωo in your Fabric mod, add the Wisp Forest Maven repository and include the owo-lib dependency. If you plan to use the configuration system (owo-config), you must also include the annotationProcessor.

Optionally, you can include owo-sentinel. This allows your mod to run without requiring users to manually install oωo; instead, sentinel will warn them and provide an option to download it automatically.

// Groovy DSL
repositories {
    maven { url 'https://maven.wispforest.io' }
}

dependencies {
    modImplementation "io.wispforest:owo-lib:${project.owo_version}"
    // only if you plan to use owo-config
    annotationProcessor "io.wispforest:owo-lib:${project.owo_version}"
    
    // include this if you don't want force your users to install owo
    include "io.wispforest:owo-sentinel:${project.owo_version}"
}

For projects using the Kotlin DSL, add the Wisp Forest Maven repository and the owo-lib dependency. Include the annotationProcessor if using owo-config, and owo-sentinel if you want to provide an automatic download option for users instead of forcing a hard dependency.

// Kotlin DSL
repositories {
    maven("https://maven.wispforest.io")
}
    
dependencies {
    modImplementation("io.wispforest:owo-lib:${properties["owo_version"]}")
    // only if you plan to use owo-config
    annotationProcessor("io.wispforest:owo-lib:${properties["owo_version"]}")
    
    // include this if you don't want force your users to install owo
    include("io.wispforest:owo-sentinel:${properties["owo_version"]}")
}

In the Braid framework, LayerContextScope acts as an ambient provider for UI layer information. It is used to propagate the current Screen context down the widget tree. You can access this context within a BuildContext using the static helper methods provided by LayerContext.

Note that attempting to access the context via of(context) (internally used by the helpers) when no LayerContextScope is present in the ancestor tree will throw an IllegalStateException.

The Navigator widget manages a stack of routes within the Braid UI framework. It uses a SharedState containing a NavigationState to track which widgets are currently active.

When a Navigator is built, it renders a Stack of the currently displayed routes. Routes can be added as standard pages or as overlays. Overlays are treated differently in the stack: the Navigator calculates the displayedRoutes by looking at the top of the stack and including all consecutive overlay routes until it hits a non-overlay route.

// Initialize a Navigator with an initial starting widget
Navigator navigator = new Navigator(new MyInitialWidget());

Assigning a Key to a Widget allows the Braid framework to identify the widget across different render cycles.

When the framework performs an update, it calls Widget.canUpdate(oldWidget, newWidget). An update is considered valid if:

1. oldWidget.getClass() == newWidget.getClass()
2. Objects.equals(oldWidget.key, newWidget.key)

If the keys match and the classes match, the framework can reuse the existing widget instance instead of destroying and recreating it.

// Assigning a key to a widget
myWidget.key(someKeyInstance);

// Retrieving the key
Key currentKey = myWidget.key();

Use LayerContext.findWidget(BuildContext context, Predicate<AbstractWidget> predicate) to search for a specific Minecraft AbstractWidget within the current contextScreen. The method traverses the children of the screen (including those within Layout objects) and returns the first widget that satisfies the provided predicate.

// Example: Find a widget by its class type
AbstractWidget myWidget = LayerContext.findWidget(context, widget -> widget instanceof MyCustomWidget);

If you provided a token when calling BraidToast.show(), you can dismiss that specific toast before its timeout expires by calling BraidToast.hideWithToken(token). This searches the current Minecraft ToastManager for a BraidToast instance associated with that token and sets its visibility to HIDE.

// To hide the toast created with 'myToken'
BraidToast.hideWithToken(myToken);