How the API behaves

This page explains category lifecycle, value flow and the current limitations of API v1.

When should a category be registered?

Register once from your Fabric client entrypoint at client startup, after loading the config that supplies initial values. Registration lives in memory for the session and does not depend on a world being loaded, so the settings screen can be opened from the title screen.

Do not register on every world join, screen open or tick. Category IDs are global, and registering the same category ID a second time throws an error.

How are values read and changed?

Your mod loads its configuration.
Your mod registers a category with functions that read and update that configuration.
When the ElytraF5 screen is created, each control reads its current value.
When the player changes a control, the API invokes your onChanged callback.
Your mod updates and saves its configuration.

Callbacks run from the client UI. Keep them fast; do not perform network access or expensive resource loading. If config changes through another path while the screen is open, close and reopen the screen to rebuild its widgets.

What is copied at registration?

The API copies the category’s option list, while option objects and callbacks remain the ones supplied by your mod. Mutating the original list later does not update the registered category. There is currently no method to update or remove a category.

Optional or required integration?

Required dependency

Declare ef5am under depends if your mod requires this integration. You can then reference the API directly from your client entrypoint.

Optional integration

Declare it under suggests. Check whether the mod is loaded with Fabric Loader and keep direct ElytraF5 class references in a dedicated bridge class that is called only when ef5am is present. This helps avoid resolving a missing mod too early. Test both setups: with and without ElytraF5.

The API is in the client source set. Never call it from an entrypoint or class shared with a dedicated server.

Compatibility

ElytraF5SettingsApi.API_VERSION is currently 1. It is an informational check for the API generation when ElytraF5 is already present; it does not replace Fabric dependency checks. Compile against the API version you use and verify signatures after a major update.

What API v1 does not do

It does not persist values for you.
It does not provide numeric sliders, text fields, multi-select lists or nested groups.
It does not expose another mod’s private settings.
It does not refresh an already-open screen when registered categories change.
It does not provide unregister or replace-category methods.
It does not add your translations to the host mod: your strings belong to your own namespace.

Detailed troubleshooting

Error / symptom	Likely cause	Fix
“id must be namespaced”	Category ID has no namespace or includes uppercase/invalid characters.	Use lowercase namespaced IDs such as `examplemod:visuals`.
Category already registered	Registration ran more than once.	Move registration to client initialization and remove world/screen-triggered calls.
“Current choice is not registered”	Config contains an unknown value or was read before initialization.	Load config before registration and migrate old values to a supported choice.
Changes are not saved	Callback changed only a temporary variable.	Update your config’s source of truth and invoke its save routine.
Class not found	Integration is optional but a class directly references the API without checking whether ElytraF5 is installed.	Keep API references in a bridge class and call it only after the Fabric Loader check.
Icon is missing	Namespace, path or capitalization does not match the resource path.	Match the Identifier to `assets/<namespace>/textures/gui/...` and check the 16 × 16 PNG.

See complete examples →