owo-lib

https://github.com/wisp-forest/owo-lib
Admin
A general utility, GUI, and config library for Fabric modding, aiming to reduce code verbosity and...
Tokens:904,272
Snippets:4,747
Trust Score:6.5
License:MIT
Update:1 day ago
Show doc for...
Tokens:
Raw
### Usage Example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-components.md

Example code demonstrating how to create and configure various UI components within a vertical flow layout.

```APIDOC
## Usage Example

### Description
Example code demonstrating how to create and configure various UI components within a vertical flow layout.

### Code
```java
FlowLayout root = UIContainers.verticalFlow(Sizing.content(), Sizing.content()).gap(4);

root.child(UIComponents.button(Component.literal("Click"), button -> System.out.println("clicked")));
root.child(UIComponents.checkbox(Component.literal("Enable")).checked(true));
root.child(UIComponents.slider(Sizing.fixed(200)).value(0.5)
        .onChanged().subscribe(slider -> System.out.println(slider.value())));

TextBoxComponent name = UIComponents.textBox(Sizing.fixed(200), "hello");
name.onChanged().subscribe(text -> { /* validation */ });
root.child(name);

root.child(UIComponents.item(new ItemStack(Items.DIAMOND)));
root.child(UIComponents.entity(Sizing.fixed(64), EntityType.VILLAGER, null));
```
```

--------------------------------

### Usage example of Owo.debugWarn and currentServer

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/owo.md

Shows a mod initializer using Owo.debugWarn to print a message only in dev environment and Owo.currentServer() to get the integrated server during play.

```java
public class MyMod implements ModInitializer {
    @Override
    public void onInitialize() {
        Owo.debugWarn(LOGGER, "This only prints in dev env");
        // ...
    }

    // Getting the integrated server during play
    public static MinecraftServer server() {
        return Owo.currentServer();
    }
}
```

--------------------------------

### XML UI model example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-parsing.md

Example XML model file with a vertical flow layout containing a label and a button. The root element must be <owo-ui>.

```xml
<owo-ui xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/wisp-forest/owo-lib/1.21/owo-ui.xsd">
    <components>
        <flow-layout direction="vertical">
            <children>
                <label>
                    <text>Hello from XML</text>
                </label>
                <button>
                    <text>Press</text>
                </button>
            </children>
        </flow-layout>
    </components>
</owo-ui>
```

--------------------------------

### Layer usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-hud-layers.md

Example of using Layers.add with a layer instance, accessing the adapter to set a panel surface and add a label child to the root component.

```java
Layers.add((hs, vs) -> new FlowLayout(hs, vs), layer -> {
    var adapter = layer.adapter;
    adapter.rootComponent.surface(Surface.PANEL).child(UIComponents.label(Component.literal("hi")));
}, InventoryScreen.class);
```

--------------------------------

### Observable usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/util.md

Demonstrates creating an Observable with an initial value, observing changes, and setting a new value which triggers the observer.

```java
Observable<Integer> obs = Observable.of(1);
obs.observe(v -> System.out.println("now " + v));
obs.set(2); // prints "now 2"
```

--------------------------------

### RegistryHelper usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/registration.md

Shows how to use RegistryHelper to run an action when an item is registered. The action runs immediately if the item exists, otherwise it is queued until registration.

```java
RegistryHelper<Item> itemHelper = RegistryHelper.get(BuiltInRegistries.ITEM);

// Runs immediately if "mymod:wand" exists, otherwise queues until it is registered
itemHelper.runWhenPresent(Identifier.parse("mymod:wand"), wand -> {
    // do something with the wand item
});
```

--------------------------------

### Config model example with @Config annotations

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/config.md

Example config model class annotated with @Config. The processor generates a ConfigWrapper implementation named 'MyConfig' extending ConfigWrapper<MyConfigModel>. Use it as 'new MyConfig()'. Demonstrates @RangeConstraint, @Sync, @Nest, and @PredicateConstraint annotations.

```java
@Config(name = "my-config", wrapperName = "MyConfig")
public class MyConfigModel {
    @RangeConstraint(min = 0, max = 100)
    public int volume = 50;

    @Sync(Option.SyncMode.OVERRIDE_CLIENT)
    public boolean hardcoreMode = false;

    @Nest
    public Gameplay gameplay = new Gameplay();

    @PredicateConstraint("validName")
    public String name = "default";

    public static boolean validName(String name) { return name.length() > 3; }

    public static class Gameplay {
        public boolean enableRockets = true;
    }
}
```

--------------------------------

### OwoSentinel.downloadAndInstall(Consumer<String> logger)

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/sentinel.md

Queries the Modrinth API for a version of owo-lib matching the current game version and fabric loader, downloads and installs the owo jar into the mods folder. Throws Exception on any failure.

```APIDOC
## OwoSentinel.downloadAndInstall(Consumer<String> logger)

### Description
Queries the Modrinth API (`https://api.modrinth.com/v2/project/owo-lib/version`) for a version matching the current game version + fabric loader; picks the version whose `version_number` equals the sentinel's own version; downloads and installs the owo jar into the mods folder.

### Method
downloadAndInstall(Consumer<String> logger)

### Parameters
- **logger** (Consumer<String>) - Required - Receives log messages during the download/install process.

### Return Value
void

### Exceptions
- **Exception** - Thrown on any network/IO/version-resolution failure.
```

--------------------------------

### ParticleSystem usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/particles.md

Registers a ParticleSystem with a controller and spawns it. The handler runs locally on the client or sends packets to tracking clients on the server.

```java
public static final ParticleSystemController CONTROLLER = new ParticleSystemController(Identifier.parse("mymod:particles"));
public static final ParticleSystem<Vec3> BURST = CONTROLLER.register(Vec3.class, MinecraftEndecs.VEC3,
        (level, pos, data) -> ClientParticles.spawnCenteredOnBlock(ParticleTypes.FLAME, level, BlockPos.containing(pos), 0.4));

// server or client:
BURST.spawn(level, pos);            // server → packets to tracking clients; client → handler runs locally
```

--------------------------------

### ConfigWrapper usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/config.md

Shows how to use a generated config class: load it, then observe an option by key. The option key uses dot notation for nested options. The observer prints the value when it changes.

```java
public class MyMod implements ModInitializer {
    public static final MyConfig CONFIG = new MyConfig(); // generated class

    @Override public void onInitialize() {
        CONFIG.load();
        CONFIG.optionForKey(new Option.Key("gameplay.enableRockets"))
              .observe(value -> System.out.println("rockets: " + value));
    }
}
```

--------------------------------

### SlotGenerator.begin

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/menu-screens.md

Starts slot generation with a consumer that receives each created slot, typically menu::addSlot, and sets the initial anchor position.

```APIDOC
## SlotGenerator.begin

### Description
Starts slot generation with a consumer that receives each created slot, typically `menu::addSlot`, and sets the initial anchor position.

### Method
begin

### Signature
`public static SlotGenerator begin(Consumer<Slot> slotConsumer, int anchorX, int anchorY)`

### Parameters
- **slotConsumer** (Consumer<Slot>) - Required - The consumer that receives each created slot.
- **anchorX** (int) - Required - The initial X anchor position.
- **anchorY** (int) - Required - The initial Y anchor position.

### Returns
SlotGenerator - The generator instance for chaining.
```

--------------------------------

### Hud usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-hud-layers.md

Example of adding a HUD component using the Hud.add method with an identifier and a supplier that creates a label component. The supplier is called each frame to recreate the component, so mutations are not persisted.

```java
public class MyClient implements ClientModInitializer {
    @Override public void onInitializeClient() {
        Hud.add(Identifier.parse("mymod", "speedometer"), () ->
            UIComponents.label(Component.literal("0 km/h")).color(Color.ofArgb(0xFFFFFFFF)));
    }
}
```

--------------------------------

### TextOps usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ops.md

Shows how to display colored and concatenated text messages to a player.

```java
player.displayClientMessage(TextOps.withColor("Hello", 0x00FF00), false);
player.displayClientMessage(TextOps.concat(Owo.PREFIX, TextOps.withColor("world", 0x3955e5)), false);
```

--------------------------------

### Example lang entry using InsertingTextContent

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/text.md

Shows how to use the `{index}` placeholder in a lang entry. The placeholder is replaced with the argument at the given index from the enclosing translation's argument list.

```json
"some.key": "You picked up {index} thing(s)"
```

--------------------------------

### LootOps usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ops.md

Shows how to inject an item with a count range into a loot table from a ModInitializer.

```java
// Called from ModInitializer (or any pre-world-load point):
LootOps.injectItemWithCount(Items.EMERALD, 0.3f, 1, 3,
        Identifier.parse("minecraft:chests/simple_dungeon"));
```

--------------------------------

### SlotGenerator Usage Example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/menu-screens.md

Example of using SlotGenerator to build a container menu with a custom slot factory and player inventory.

```APIDOC
## SlotGenerator Usage Example

### Description
Example of using SlotGenerator to build a container menu with a custom slot factory and player inventory.

### Code
```java
public class MyMenu extends AbstractContainerMenu {
    public MyMenu(int syncId, Inventory inventory) {
        super(MyScreenHandlerType.INSTANCE, syncId);

        SlotGenerator.begin(this::addSlot, 8, 84)
            .slotFactory((container, index, x, y) ->
                    new ValidatingSlot(container, index, x, y, stack -> stack.getItem() == Items.DIAMOND))
            .grid(this.blockInventory, 0, 3, 3)
            .slotFactory(Slot::new)                       // back to default
            .playerInventory(inventory);
    }
}
```
```

--------------------------------

### Usage example: registering items with AutoRegistryContainer

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/registration.md

Shows a complete example of a container class implementing AutoRegistryContainer<Item> and the registration call in ModInitializer#onInitialize. The container must have a zero-args constructor. The register call registers the public static final fields as items with the given namespace, producing "mymod:wand" and "mymod:stick_of_power".

```java
public final class MyItems implements AutoRegistryContainer<Item> {
    public static final Item WAND = new Item(new Item.Properties());
    public static final Item STICK_OF_POWER = new Item(new Item.Properties());

    @Override public Class<Item> getTargetFieldType() { return Item.class; }
    @Override public Registry<Item> getRegistry() { return BuiltInRegistries.ITEM; }
}

// in ModInitializer#onInitialize (after the container class is loadable):
AutoRegistryContainer.register(MyItems.class, "mymod", false);
// registers "mymod:wand" and "mymod:stick_of_power"
```

--------------------------------

### DemoScreen extending BaseOwoScreen

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-screens.md

Example of a custom screen that creates a FlowLayout adapter and builds a simple UI with a button and a label. The label is retrieved by ID and its text is set.

```java
public class DemoScreen extends BaseOwoScreen<FlowLayout> {
    public DemoScreen() { super(Component.literal("Demo")); }

    @Override protected @NotNull OwoUIAdapter<FlowLayout> createAdapter() {
        return OwoUIAdapter.create(this, (hs, vs) -> new FlowLayout(hs, vs));
    }

    @Override protected void build(FlowLayout rootComponent) {
        rootComponent
            .surface(Surface.PANEL)
            .padding(Insets.of(10))
            .child(Components.button(Component.literal("Close"), b -> this.onClose()));

        LabelComponent label = rootComponent.childById(LabelComponent.class, "title");
        label.text(Component.literal("Hello owo"));
    }
}
```

--------------------------------

### Usage example with RegistryHelper

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/registration.md

Creates a ComplexRegistryAction that runs when both minecraft:diamond and mymod:ruby are present, then registers it with RegistryHelper.get(BuiltInRegistries.ITEM).runWhenPresent().

```java
ComplexRegistryAction action = ComplexRegistryAction.Builder
        .create(() -> { /* all present */ })
        .entry(Identifier.parse("minecraft:diamond"))
        .entry(Identifier.parse("mymod:ruby"))
        .build();

RegistryHelper.get(BuiltInRegistries.ITEM).runWhenPresent(action);
```

--------------------------------

### Usage example: building a vertical flow layout

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-components.md

Shows how to create a vertical flow layout and add various UI components such as buttons, checkboxes, sliders, text boxes, item stacks, and entities.

```java
FlowLayout root = UIContainers.verticalFlow(Sizing.content(), Sizing.content()).gap(4);

root.child(UIComponents.button(Component.literal("Click"), button -> System.out.println("clicked")));
root.child(UIComponents.checkbox(Component.literal("Enable")).checked(true));
root.child(UIComponents.slider(Sizing.fixed(200)).value(0.5)
        .onChanged().subscribe(slider -> System.out.println(slider.value())));

TextBoxComponent name = UIComponents.textBox(Sizing.fixed(200), "hello");
name.onChanged().subscribe(text -> { /* validation */ });
root.child(name);

root.child(UIComponents.item(new ItemStack(Items.DIAMOND)));
root.child(UIComponents.entity(Sizing.fixed(64), EntityType.VILLAGER, null));
```

--------------------------------

### Query client values from server

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/config.md

Example of using ConfigSynchronizer.getClientOptions to retrieve a client's values for a specific config. The returned map may be null if no values are available.

```java
// Server-side query of a client's values
Map<Option.Key, ?> clientValues = ConfigSynchronizer.getClientOptions(player, "my-config");
if (clientValues != null) {
    boolean hardcore = (boolean) clientValues.get(new Option.Key("hardcoreMode"));
}
```

--------------------------------

### EventStream usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/util.md

Demonstrates creating an EventStream with a sinkFactory that broadcasts to all subscribers, subscribing a consumer, and invoking the sink. This is how owo-ui component events are wired.

```java
EventStream<Consumer<String>> stream = new EventStream<>(subs -> value -> {
    for (var sub : subs) sub.accept(value);
});
stream.source().subscribe(System.out::println);
stream.sink().accept("hello");
```

--------------------------------

### ModelScreen extends BaseUIModelScreen

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-parsing.md

Example Java class that loads a UI model from assets/mymod/models/main.xml using the identifier 'mymod:main'.

```java
// resources: assets/mymod/models/main.xml
public class ModelScreen extends BaseUIModelScreen<FlowLayout> {
    public ModelScreen() {
        super(FlowLayout.class, Identifier.parse("mymod:main"));
    }
}
```

--------------------------------

### Event subscription usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-core.md

Shows how to subscribe to mouseEnter and mouseDown events on a button component. The mouseDown handler returns true when the event is doubled to consume it and close the UI.

```java
button.mouseEnter().subscribe(() -> System.out.println("hovered"));
button.mouseDown().subscribe((click, doubled) -> {
    if (doubled) { this.onClose(); return true; }
    return false;
});
```

--------------------------------

### ClientParticles usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/particles.md

Spawns a burst of 10 particles drifting upward around a block using ClientParticles. Sets particle count and velocity, then spawns centered on a block with a deviation of 0.5.

```java
// burst of 10 particles drifting upward around a block
ClientParticles.setParticleCount(10);
ClientParticles.setVelocity(new Vec3(0, 0.2, 0));
ClientParticles.spawnCenteredOnBlock(new ItemParticleOption(ParticleTypes.ITEM, new ItemStack(Items.DIAMOND)),
        world, pos, 0.5);
```

--------------------------------

### Usage examples for AnimatableProperty.animate

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-properties.md

Shows how to animate a vertical sizing and a button positioning using AnimatableProperty.animate. The first animates verticalSizing to a fixed size of 40 over 300ms with Easing::apply; the second animates positioning to relative(50, 50) over 200ms with Easing.LINEAR.

```java
label.verticalSizing().animate(300, Easing::apply, Sizing.fixed(40));
button.positioning().animate(200, Easing.LINEAR, Positioning.relative(50, 50));
```

--------------------------------

### SyncedProperty usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/menu-screens.md

Shows how to use SyncedProperty in a menu constructor: create it with an index, Endec.INT, initial value, and the menu instance. Server-side, update the value and call markDirty() to sync; client-side, observe changes with progress.observe().

```java
// in the menu constructor:
this.progress = new SyncedProperty<>(0, Endec.INT, 0, this);
// server-side when the recipe progresses:
progress.set(progress.get() + 1);
progress.markDirty();
// client side: progress.observe(value -> { ... });
```

--------------------------------

### Subscribe to mouseDown event on a button

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-properties.md

Example of using configure() to subscribe to the mouseDown event source of a button component. The lambda receives the click event and a boolean indicating whether it was a double-click, and returns true to indicate the event was handled.

```java
Components.button(Component.literal("Press me"), button -> {})
    .<ButtonComponent>configure(button -> {
        button.mouseDown().subscribe((click, doubled) -> {
            System.out.println("clicked");
            return true;
        });
    });
```

--------------------------------

### ItemOps usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ops.md

Shows how to use ItemOps.canStack to merge a picked-up stack into the held stack or drop it, and ItemOps.decrementPlayerHandItem to decrement the player's main hand item, returning false when the hand becomes empty.

```java
if (ItemOps.canStack(heldStack, pickedUpStack)) {
    heldStack.grow(pickedUpStack.getCount());
} else {
    player.drop(pickedUpStack, false);
}

if (!ItemOps.decrementPlayerHandItem(player, InteractionHand.MAIN_HAND)) {
    // the hand is now empty
}
```

--------------------------------

### Data-driven item group JSON format

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/item-groups.md

Example JSON file loaded from data/<ns>/item_group/*.json. The target_group specifies the vanilla group to extend or wrap; extend=true extends in place, otherwise a WrapperGroup is created. Tabs and buttons are defined with tag, icon, name, texture, and button texture coordinates.

```json
{
  "target_group": "minecraft:search",   // vanilla group to extend/wrap
  "extend": false,                       // when true, the existing group is extended in place
  "tabs": [
    { "tag": "mymod:cool_items", "icon": "minecraft:diamond", "name": "tab_name", "texture": "owo:textures/gui/tabs.png" }
  ],
  "buttons": [
    { "link": "https://example.com", "name": "link_name", "texture_u": 0, "texture_v": 0,
      "texture_width": 64, "texture_height": 64, "texture": "minecraft:textures/gui/...png" }
  ]
}
```

--------------------------------

### WrappingParentUIComponent Usage Example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-containers.md

Example of using WrappingParentUIComponent subclasses (ScrollContainer and OverlayContainer) to create scrollable and overlay containers.

```APIDOC
## WrappingParentUIComponent Usage Example

### Description
Example of using WrappingParentUIComponent subclasses (ScrollContainer and OverlayContainer) to create scrollable and overlay containers.

### Usage
```java
FlowLayout root = UIContainers.verticalFlow(Sizing.content(), Sizing.content())
    .child(UIContainers.horizontalScroll(Sizing.fill(100), Sizing.fixed(80),
        UIContainers.horizontalFlow(Sizing.content(), Sizing.content())
            .children(IntStream.range(0, 50).mapToObj(i -> Components.button(Component.literal("" + i), b -> {})).toList())
            .gap(4)));

// dom-based overlay:
root.child(UIContainers.overlay(Components.label(Component.literal("modal"))).closeOnClick(true));
```
```

--------------------------------

### OwoSentinel.launch()

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/sentinel.md

Launches the sentinel process. If owo is already loaded, it does nothing. Otherwise, it shows a warning (console or GUI) and exits the game after handling.

```APIDOC
## OwoSentinel.launch()

### Description
Launches the sentinel process. If owo is already loaded, it does nothing. Otherwise, it shows a warning (console or GUI) and exits the game after handling.

### Method
launch()

### Parameters
None

### Return Value
void

### Behavior
- No-op when `owo-impl` is loaded.
- On macOS, in a headless environment, or with `owo.sentinel.forceHeadless`, runs the console variant (`SentinelConsole`).
- Otherwise opens the GUI (`SentinelWindow`).
- Both paths exit the game afterwards (`System.exit(0)`); failures log and `System.exit(1)`.
```

--------------------------------

### LinearProcess usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/misc.md

Example of using LinearProcess in a block entity. It defines a static process with a common step, event, and finish handler, then creates an executor and ticks it.

```java
public class CrusherBlockEntity extends BlockEntity {
    public static final LinearProcess<CrusherBlockEntity> PROCESS = new LinearProcess<>(100);

    static {
        PROCESS.addCommonStep(0, 100, (process, be) -> { /* animate */ });
        PROCESS.addCommonEvent(100, (process, be) -> be.crush());
        PROCESS.whenFinishedCommon((process, be) -> be.dropOutput());
    }

    private final LinearProcessExecutor<CrusherBlockEntity> process = PROCESS.createExecutor(this);

    public void tick() {
        process.tick();   // advance when running
    }
}
```

--------------------------------

### Minimal screen using OwoUIAdapter

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-core.md

Shows how to create a minimal Screen that uses OwoUIAdapter with a FlowLayout root. The adapter is created in init(), a button is added, and then inflateAndMount() is called. In render(), the adapter's render and drawTooltip methods are called after super.render().

```java
// Minimal screen (see ui-screens.md for BaseOwoScreen)
public class MyScreen extends Screen {
    private OwoUIAdapter<FlowLayout> adapter;

    protected void init() {
        this.adapter = OwoUIAdapter.create(this, (hs, vs) -> new FlowLayout(hs, vs));
        this.adapter.rootComponent.child(Components.button(Component.literal("OK"), b -> this.onClose()));
        this.adapter.inflateAndMount();
    }

    public void render(GuiGraphics graphics, int mouseX, int mouseY, float delta) {
        super.render(graphics, mouseX, mouseY, delta);
        this.adapter.render(graphics, mouseX, mouseY, delta);
        this.adapter.drawTooltip(graphics, mouseX, mouseY, delta); // via ScreenEvents.afterRender normally
    }
}
```

--------------------------------

### Layers.add usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-hud-layers.md

Example of using Layers.add to add a layer to the InventoryScreen. The root component is a FlowLayout, and the instance initializer sets a panel surface and adds a label child.

```java
Layers.add((hs, vs) -> new FlowLayout(hs, vs), layer -> {
    // layer is a Layer<InventoryScreen, FlowLayout>.Instance
    layer.adapter.rootComponent
        .surface(Surface.PANEL)
        .child(UIComponents.label(Component.literal("hi")));
}, InventoryScreen.class);
```

--------------------------------

### OwoItemGroup.initialize()

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/item-groups.md

Runs the initializer (client only), appends a placeholder tab if no tabs were added, and selects primary tabs. Must be called after all items are registered.

```APIDOC
## OwoItemGroup.initialize()

### Description
Runs the initializer (client only), appends a placeholder tab if no tabs were added, and selects primary tabs. Must be called after all items are registered.

### Method
initialize

### Parameters
None

### Returns
void

```

--------------------------------

### Create and use OwoNetChannel with message registration

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/network.md

Shows how to create a network channel, define message records, register serverbound and clientbound handlers, and send messages. Must be called on both sides. Handlers run on the game thread.

```java
public record GreetingMessage(String text) {}
public record AckMessage(boolean ok) {}

public static final OwoNetChannel CHANNEL = OwoNetChannel.create(Identifier.parse("mymod", "main"));

public static void init() {
    // MUST be called on both sides
    CHANNEL.registerServerbound(GreetingMessage.class, (message, access) -> {
        // runs on the game thread, server side
        access.player().sendSystemMessage(Component.literal("got: " + message.text()));
        CHANNEL.serverHandle(access.player()).send(new AckMessage(true));
    });

    CHANNEL.registerClientbound(AckMessage.class, (message, access) -> { ... });
}

// client → server:
CHANNEL.clientHandle().send(new GreetingMessage("hello"));
```

--------------------------------

### UIParsing.getFactory(Element element)

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-parsing.md

Gets the factory registered for the given element's tag name.

```APIDOC
## UIParsing.getFactory(Element element)

### Description
Gets the factory registered for the given element's tag name.

### Method
static Function<Element, UIComponent> getFactory(Element element)

### Parameters
- **element** (Element) - Required - The XML element to look up the factory for.

### Returns
- **Function<Element, UIComponent>** - The factory for the element's tag name.
```

--------------------------------

### ConfigWrapper.allOptions()

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/config.md

Returns an unmodifiable view of all options.

```APIDOC
## allOptions()

### Description
Returns an unmodifiable view of all options.

### Method
allOptions()

### Parameters
None

### Returns
Map<Option.Key, Option<?>> - Unmodifiable map of all options.

### Usage Example
```java
Map<Option.Key, Option<?>> options = CONFIG.allOptions();
```
```

--------------------------------

### UIModelLoader.getHotReloadPath(Identifier modelId)

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-parsing.md

Gets the current hot-reload path for a model, or null if none is set.

```APIDOC
## UIModelLoader.getHotReloadPath(Identifier modelId)

### Description
Gets the current hot-reload path for a model, or null if none is set.

### Method
static @Nullable Path getHotReloadPath(Identifier modelId)

### Parameters
- **modelId** (Identifier) - Required - The identifier of the model.

### Returns
- **Path** (nullable) - The hot-reload path, or null if not set.
```

--------------------------------

### EndecRecipeSerializer usage example

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/serialization.md

Creates a RecipeSerializer using EndecRecipeSerializer with a StructEndec derived from MyRecipe.ENDEC via CodecUtils.toStructEndec.

```java
public static final RecipeSerializer<?> MY_RECIPE_SERIALIZER =
        new EndecRecipeSerializer<>(CodecUtils.toStructEndec(MyRecipe.ENDEC));
```

--------------------------------

### Build and initialize an OwoItemGroup

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/item-groups.md

Shows how to create an OwoItemGroup with a tag-filled tab, a custom-content tab, and a link button, then initialize it in ModInitializer after item registration. The addTab(name) method derives the tab tooltip via ButtonDefinition.tooltipFor(this, "tab", name) with translation key itemGroup.<ns>.<path>.tab.<name>; contentTag == null yields an empty tab typically filled per-item via OwoItemSettingsExtension.tab(int).

```java
public static final OwoItemGroup GROUP = OwoItemGroup.builder(
        Identifier.parse("mymod", "group"), () -> Icon.of(Items.DIAMOND))
    .initializer(group -> {
        // tag-filled tab (items from the given tag id):
        group.addTab(Icon.of(Items.SWORD), "weapons", TagKey.create(Registries.ITEM, Identifier.parse("mymod:weapons")), true);
        // custom-content tab:
        group.addCustomTab(Icon.of(Items.BOW), "specials", (context, entries) -> entries.accept(MyItems.MEGA_BOW), true);
        group.addButton(ItemGroupButton.link(group, Icon.of(Items.EMERALD), "link-name", "https://example.com"));
    })
    .build();

// in ModInitializer after item registration:
GROUP.initialize();
```

--------------------------------

### SlotGenerator.grid

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/menu-screens.md

Emits a width × height grid of slots over the given container, starting at the specified index.

```APIDOC
## SlotGenerator.grid

### Description
Emits a `width × height` grid of slots over the given container, starting at the specified index. Single-slot widths advance columns first.

### Method
grid

### Signature
`public SlotGenerator grid(Container container, int startIndex, int width, int height)`

### Parameters
- **container** (Container) - Required - The container to generate slots for.
- **startIndex** (int) - Required - The starting slot index.
- **width** (int) - Required - The grid width.
- **height** (int) - Required - The grid height.

### Returns
SlotGenerator - The generator instance for chaining.
```

--------------------------------

### GridLayout

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-containers.md

A container that places children in explicit (row, column) cells, each cell getting an equal share of the space.

```APIDOC
## GridLayout

### Description
A container that places children in explicit (row, column) cells, each cell getting an equal share of the space.

### Constructor
`protected GridLayout(Sizing horizontalSizing, Sizing verticalSizing, int rows, int columns)`

### Methods

#### `public void layout(Size space)`
- **Description**: Lays out the container within the given space.

#### `public void draw(OwoUIGraphics graphics, int mouseX, int mouseY, float partialTicks, float delta)`
- **Description**: Draws the container and its children.

#### `public GridLayout child(UIComponent child, int row, int column)`
- **Description**: Adds a child component at the specified row and column.
- **Parameters**:
  - `child` (UIComponent) - The component to add.
  - `row` (int) - The row index.
  - `column` (int) - The column index.
- **Returns**: This GridLayout instance for chaining.

#### `public GridLayout removeChild(int row, int column)`
- **Description**: Removes the child at the specified row and column.
- **Parameters**:
  - `row` (int) - The row index.
  - `column` (int) - The column index.
- **Returns**: This GridLayout instance for chaining.

#### `public GridLayout removeChild(UIComponent child)`
- **Description**: Removes the given child component.
- **Parameters**:
  - `child` (UIComponent) - The component to remove.
- **Returns**: This GridLayout instance for chaining.

#### `public List<UIComponent> children()`
- **Description**: Returns the list of child components.

#### `public void parseProperties(UIModel model, Element element, Map<String, Element> children)`
- **Description**: Parses properties from a UI model.

#### `public static GridLayout parse(Element element)`
- **Description**: Parses a GridLayout from an XML element.
- **Parameters**:
  - `element` (Element) - The XML element.
- **Returns**: A new GridLayout instance.

```

--------------------------------

### OwoUIAdapter.inflateAndMount()

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-core.md

Inflates the root component with the adapter size and mounts it at the adapter origin. Must be called before rendering.

```APIDOC
## OwoUIAdapter.inflateAndMount()

### Description
Inflates the root component with the adapter size and mounts it at the adapter origin. Must be called before rendering.

### Method
inflateAndMount

### Parameters
None

### Returns
void
```

--------------------------------

### SlotGenerator.playerInventory

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/menu-screens.md

Emits the 3×9 hotbar and 9×3 inventory rows with the standard margin offset, starting below the current cursor.

```APIDOC
## SlotGenerator.playerInventory

### Description
Emits the 3×9 hotbar and 9×3 inventory rows with the standard margin offset, starting below the current cursor.

### Method
playerInventory

### Signature
`public SlotGenerator playerInventory(Inventory playerInventory)`

### Parameters
- **playerInventory** (Inventory) - Required - The player's inventory.

### Returns
SlotGenerator - The generator instance for chaining.
```

--------------------------------

### ConfigWrapper.load()

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/config.md

Reads the JSON5 file and deserializes each option. If the file is missing, it creates it via save(). Constraints are re-verified before applying.

```APIDOC
## load()

### Description
Reads the JSON5 file, deserializing each option. If the file is missing, `save()` creates it. Constraints are re-verified (`verifyConstraint`) before applying. On parse failure, warns and skips.

### Method
load()

### Returns
void

### Parameters
None

### Usage Example
```java
CONFIG.load();
```
```

--------------------------------

### Layer.instantiate

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-hud-layers.md

Creates a new instance of this layer for the given screen.

```APIDOC
## Layer.instantiate

### Description
Creates a new instance of this layer for the given screen.

### Method
instantiate

### Signature
```java
public Instance instantiate(S screen)
```

### Parameters
- **screen** (S) - Required - The screen for which to create the instance.

### Returns
- **Instance** - The new layer instance.
```

--------------------------------

### BraidComponent

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-components.md

A UI component that embeds a braid widget. It provides a constructor to wrap a braid widget and a method to get the cursor style.

```APIDOC
## BraidComponent

### Description
A UI component that embeds a braid widget. It provides a constructor to wrap a braid widget and a method to get the cursor style.

### Constructor
- `BraidComponent(Widget braidWidget)` - Creates a new BraidComponent wrapping the given braid widget.

### Methods
- `io.wispforest.owo.ui.core.CursorStyle cursorStyle()` - Returns the cursor style used by the embedded braid widget.

### Nested Classes
- `EmbedSurface` - A surface that forwards the cursor style to the braid.
- `BraidWidget` - A braid-side mirror of this component.
```

--------------------------------

### ConfigWrapper.forEachOption(Consumer<Option<?>>)

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/config.md

Iterates over all options, applying the given consumer to each.

```APIDOC
## forEachOption(Consumer<Option<?>>)

### Description
Iterates over all options, applying the given consumer to each.

### Method
forEachOption(Consumer<Option<?>>)

### Parameters
- `action` (Consumer<Option<?>>) - Required - The action to apply to each option.

### Returns
void

### Usage Example
```java
CONFIG.forEachOption(option -> System.out.println(option.key()));
```
```

--------------------------------

### OwoUIAdapter.x(), y(), width(), height()

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-core.md

Getters for the adapter's position and size.

```APIDOC
## OwoUIAdapter.x(), y(), width(), height()

### Description
Getters for the adapter's position and size.

### Method
x, y, width, height

### Parameters
None

### Returns
int - The respective coordinate or dimension.
```

--------------------------------

### AnimatableProperty.animate(int duration, Easing easing, A to)

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-properties.md

Starts an animation from the current value to the target value over the specified duration with the given easing.

```APIDOC
## AnimatableProperty.animate(int duration, Easing easing, A to)

### Description
Starts an animation toward the target value `to` over the given duration using the specified easing function.

### Method
Instance method

### Signature
`public Animation<A> animate(int duration, Easing easing, A to)`

### Parameters
- **duration** (int) - Required - The animation duration in milliseconds.
- **easing** (Easing) - Required - The easing function to apply.
- **to** (A) - Required - The target value.

### Returns
- **Animation<A>** - The created Animation object.

```

--------------------------------

### Open a native window with BraidWindow.open

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/braid.md

Opens a native window titled "My Window" with dimensions 400x300 and an empty widget as its content. The result is stored in a BraidWindow.OpenResult variable.

```java
// Or open a native window with a braid app:
BraidWindow.OpenResult result = BraidWindow.open("My Window", 400, 300, EmptyWidget.INSTANCE);
```

--------------------------------

### ConfigScreenProviders.forEach

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/config.md

Iterates over all registered config screen providers.

```APIDOC
## ConfigScreenProviders.forEach

### Description
Iterates over all registered config screen providers.

### Method
forEach

### Signature
`public static void forEach(BiConsumer<String, Function<Screen, ? extends Screen>> action)`

### Parameters
- **action** (BiConsumer<String, Function<Screen, ? extends Screen>>) - Required - The action to perform for each registered provider.

### Returns
- void
```

--------------------------------

### OwoItemGroup.Builder.build

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/item-groups.md

Builds the OwoItemGroup instance.

```APIDOC
## OwoItemGroup.Builder.build

### Description
Builds the OwoItemGroup instance.

### Method
build

### Returns
- **OwoItemGroup** - The built item group.

### Example
```java
OwoItemGroup group = OwoItemGroup.builder(...).build();
```
```

--------------------------------

### BaseOwoScreen<R extends ParentUIComponent>

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-screens.md

Abstract base class for owo-ui screens. Subclasses must implement createAdapter() and build(R rootComponent) to define the UI hierarchy. Handles screen lifecycle, input forwarding, and error reporting.

```APIDOC
## BaseOwoScreen<R extends ParentUIComponent>

### Description
Abstract base class for owo-ui screens. Subclasses must implement `createAdapter()` and `build(R rootComponent)` to define the UI hierarchy. Handles screen lifecycle, input forwarding, and error reporting.

### Import Path
`io.wispforest.owo.ui.base.BaseOwoScreen`

### Class Signature
```java
public abstract class BaseOwoScreen<R extends ParentUIComponent> extends Screen implements DisposableScreen
```

### Constructors
- `protected BaseOwoScreen(Component title)` - Creates a screen with the given title.
- `protected BaseOwoScreen()` - Creates a screen with no title.

### Methods
- `protected abstract @NotNull OwoUIAdapter<R> createAdapter()` - Creates the UI adapter for this screen. Usually one line: `return OwoUIAdapter.create(this, (hs, vs) -> new FlowLayout(hs, vs));`
- `protected abstract void build(R rootComponent)` - Builds the component hierarchy on the root component.
- `protected void drawComponentTooltip(GuiGraphics drawContext, int mouseX, int mouseY, float tickDelta)` - Draws component tooltips.
- `protected <C extends UIComponent> C component(Class<C> expectedClass, String id)` - Shorthand for `adapter.rootComponent.childById(...)`.
- `protected void init()` - Initializes the screen. On first initialization, calls `createAdapter()` → `build(...)` → `inflateAndMount()`. On resize, the adapter is `moveAndResize`d instead. Exceptions are logged, reported via `UIErrorToast.report(error)`, and the screen marks itself `invalid` and closes on the next frame.
- `public void renderBackground(GuiGraphics context, int mouseX, int mouseY, float delta)` - No-op.
- `public void render(GuiGraphics context, int mouseX, int mouseY, float delta)` - Renders the screen; closes the screen when `invalid`.
- `public boolean keyPressed(KeyEvent input)` - Forwards to the focused `GreedyInputUIComponent` first, then vanilla, then `shouldCloseOnEsc` handling.
- `public boolean mouseDragged(MouseButtonEvent click, double deltaX, double deltaY)` - Handles mouse drag events.
- `public @Nullable GuiEventListener getFocused()` - Returns the currently focused event listener.
- `public void removed()` - Resets the cursor style to `NONE`.
- `public void dispose()` - Disposes the adapter (from `DisposableScreen`).

### Usage Example
```java
public class DemoScreen extends BaseOwoScreen<FlowLayout> {
    public DemoScreen() { super(Component.literal("Demo")); }

    @Override protected @NotNull OwoUIAdapter<FlowLayout> createAdapter() {
        return OwoUIAdapter.create(this, (hs, vs) -> new FlowLayout(hs, vs));
    }

    @Override protected void build(FlowLayout rootComponent) {
        rootComponent
            .surface(Surface.PANEL)
            .padding(Insets.of(10))
            .child(Components.button(Component.literal("Close"), b -> this.onClose()));

        LabelComponent label = rootComponent.childById(LabelComponent.class, "title");
        label.text(Component.literal("Hello owo"));
    }
}
```
```

--------------------------------

### UIParsing.get(Map<String, E> properties, String key, Function<E, T> parser)

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/ui-parsing.md

Gets a property from a map and parses it using the given parser, returning an Optional.

```APIDOC
## UIParsing.get(Map<String, E> properties, String key, Function<E, T> parser)

### Description
Gets a property from a map and parses it using the given parser, returning an Optional.

### Method
static <T, E extends Node> Optional<T> get(Map<String, E> properties, String key, Function<E, T> parser)

### Parameters
- **properties** (Map<String, E>) - Required - The map of properties.
- **key** (String) - Required - The key to look up.
- **parser** (Function<E, T>) - Required - The parser function.

### Returns
- **Optional<T>** - The parsed value, or empty if the key is not present.
```

--------------------------------

### ClientAccess and ServerAccess environment access implementations

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/network.md

Shows the ClientAccess and ServerAccess classes that implement OwoNetChannel.EnvironmentAccess. ClientAccess is client-side and provides player, runtime, and packetListener. ServerAccess is a record that provides runtime and packetListener.

```java
@Environment(EnvType.CLIENT)
public class ClientAccess implements OwoNetChannel.EnvironmentAccess<LocalPlayer, Minecraft, ClientPacketListener> {
    public ClientAccess(ClientPacketListener packetListener)
    public LocalPlayer player()      // Minecraft.getInstance().player (nullable at runtime)
    public Minecraft runtime()
    public ClientPacketListener packetListener()
}

public record ServerAccess(ServerPlayer player)
        implements OwoNetChannel.EnvironmentAccess<ServerPlayer, MinecraftServer, ServerGamePacketListenerImpl> {
    public MinecraftServer runtime()                       // player.level().getServer()
    public ServerGamePacketListenerImpl packetListener()   // player.connection
}
```

--------------------------------

### ConfigWrapper.optionForKey(Option.Key)

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/config.md

Returns the option for the given key, or null if not found.

```APIDOC
## optionForKey(Option.Key)

### Description
Returns the option for the given key, or `null` if not found.

### Method
optionForKey(Option.Key)

### Parameters
- `key` (Option.Key) - Required - The key to look up.

### Returns
@Nullable Option<T> - The option for the key, or null.

### Usage Example
```java
Option<Boolean> option = CONFIG.optionForKey(new Option.Key("gameplay.enableRockets"));
```
```

--------------------------------

### Add owo-lib dependency with Gradle Kotlin DSL

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/README.md

Kotlin DSL equivalent of the Groovy build setup. Adds the owo-lib repository and dependencies, with optional annotationProcessor and owo-sentinel include.

```kotlin
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
    // sentinel will warn them and give the option to download it automatically
    include("io.wispforest:owo-sentinel:${properties["owo_version"]}")
}
```

--------------------------------

### ClientAccess

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/network.md

Provides client-side environment access, including the local player, Minecraft runtime, and packet listener.

```APIDOC
## ClientAccess

### Description
Provides client-side environment access for network handlers. Implements OwoNetChannel.EnvironmentAccess<LocalPlayer, Minecraft, ClientPacketListener>.

### Constructor
- **ClientAccess(ClientPacketListener packetListener)** - Creates a new ClientAccess instance.

### Methods
- **player()** (LocalPlayer) - Returns the local player (Minecraft.getInstance().player). May be null at runtime.
- **runtime()** (Minecraft) - Returns the Minecraft runtime instance.
- **packetListener()** (ClientPacketListener) - Returns the client packet listener.

### Import Path
`io.wispforest.owo.network.ClientAccess`
```

--------------------------------

### SlotGenerator usage in MyMenu

Source: https://github.com/wisp-forest/owo-lib/blob/braid-ui/_autodocs/api-reference/menu-screens.md

Example menu constructor using SlotGenerator to add a 3x3 grid of ValidatingSlots (only accepting diamonds) and the player inventory. Uses slotFactory to switch between ValidatingSlot and default Slot.

```java
public class MyMenu extends AbstractContainerMenu {
    public MyMenu(int syncId, Inventory inventory) {
        super(MyScreenHandlerType.INSTANCE, syncId);

        SlotGenerator.begin(this::addSlot, 8, 84)
            .slotFactory((container, index, x, y) ->
                    new ValidatingSlot(container, index, x, y, stack -> stack.getItem() == Items.DIAMOND))
            .grid(this.blockInventory, 0, 3, 3)
            .slotFactory(Slot::new)                       // back to default
            .playerInventory(inventory);
    }
}
```
Tokens:
Raw