DynamicHudConfigurator

The DynamicHudConfigurator provides a fluent, chainable API to configure widgets, renderers, movable screens, and save logic for your mod’s HUD.

Overview

DynamicHudConfigurator is used in the configure method of your DynamicHudIntegration implementation to set up your HUD. It allows you to:

• Add and manage widgets.

• Configure or override the renderer.

• Define a movable screen for widget dragging.

• Handle widget saving logic.

• Mark your mod as a utility (no HUD rendering).

All methods return this, enabling method chaining for a clean setup.

Key Methods

addWidget(Widget widget)

Adds a widget to the HUD.

Example:

configurator.addWidget(yourWidgetObject);

Usage:

• Use for any Widget subclass (e.g., TextWidget, GraphWidget).

• Call multiple times to add multiple widgets.

---

configureRenderer(Consumer<WidgetRenderer> wrConsumer)

Customizes the default WidgetRenderer with a consumer.

Example:

configurator.configureRenderer(renderer -> {
    // See more about the `renderer` WidgetRenderer page
    renderer.shouldRenderInGameHud(true);
    renderer.addScreen(TitleScreen.class);
})

Usage:

• Automatically creates a renderer if none exists, using the current widget list.

• Use to tweak the available customisation of renderer like z index, allowed renderable screens,etc.

---

configureRenderer(Consumer<WidgetRenderer> wrConsumer, List<Widget> widgets)

Configures a new renderer with a custom widget list.

Example:

List<Widget> customWidgets = new ArrayList<>(); 
customWidgets.add(new TextWidget(...));
configurator.configureRenderer(renderer -> /* configure here */ , customWidgets);

---

overrideRenderer(WidgetRenderer renderer)

Replaces the default renderer with a custom instance.

Example:

configurator.overrideRenderer(new WidgetRenderer(widgets));

---

onSave(Consumer<List<Widget>> saveHandler)

Defines custom logic to run before saving widgets.

Example:

configurator.onSave(widgets -> System.out.println("Saving " + widgets.size() + " widgets!"));

Usage:

• Use for logging, validation, or modifying widgets before they’re saved to widgets.nbt.

• The consumer receives the current widget list.

---

withMoveableScreen(Function<DynamicHudConfigurator, AbstractMoveableScreen> screenProvider)

Sets the movable screen for widget editing.

Example:

AbstractMoveableScreen moveableScreen = new AbstractMoveableScreen(Text.literal("Editor Screen"), config.getRenderer()){};
configurator.withMoveableScreen(config -> moveableScreen);

Usage:

• Provides a screen for players to drag and customize widgets.

• The function receives the configurator for context (e.g., accessing widgets).

Never return null. A null screen prevents players from editing the HUD, breaking the user experience.

---

modifyWidgets(Consumer<Widget> operation)

Applies a batch operation to all widgets.

Example:

configurator.modifyWidgets(widget -> /* loop through each widget and change it */ );

Usage:

• Use for bulk changes (e.g., colors, positions, visibility).

• Reduces repetitive code when modifying multiple widgets.

• Issue Type: Batch operation fails for some widgets.

  • Fix: Ensure the consumer handles all widget types. Test for type-specific properties to avoid crashes.

---

markAsUtility

A public boolean field to mark the mod as a utility (no HUD rendering).

Example:

configurator.markAsUtility = true;

Usage:

• Set to true if your mod provides widgets for other mods but doesn’t display a HUD.

• Skips rendering but allows widget registration.

Don’t set true if your mod needs a HUD. Your widgets won’t render, leaving players with a blank screen.

---

Internal Methods

These methods are marked @ApiStatus.Internal and should not be called directly:

• setupSaveEvents(File widgetsFile): Registers Fabric events to save widgets (e.g., on server stop, player disconnect). Handled automatically by DynamicHUD.

• registerWidgets(): Adds widgets to WidgetManager. Called internally during initialization.

• saveWidgetsSafely(File widgetsFile, List<Widget> widgets): Saves widgets to the specified file, invoking the saveHandler.

Calling internal methods manually can break widget lifecycle or saving. Let DynamicHUD handle them.

---

Common Issues & Fixes

• Issue: IOException during widget saving.

  • Fix: Ensure getWidgetsFile in DynamicHudIntegration returns a writable path. Verify directory permissions and existence.

• Issue: HUD is blank despite adding widgets.

  • Fix: Check markAsUtility is false if you want a HUD. Confirm configureRenderer or overrideRenderer includes all widgets.

• Issue: Editor screen crashes or doesn’t open.

  • Fix: Verify withMoveableScreen returns a valid AbstractMoveableScreen. Test the keybind (default: Right Shift) and ensure it’s registered via getKeyBind.

• Issue: Custom renderer doesn’t display widgets.

  • Fix: Ensure your WidgetRenderer subclass handles the widget list correctly. Check for null or empty lists in overrideRenderer.