Versioning, boundaries and error isolation

API version and compatibility

The runtime API version is published via JelloApi.version() as an ApiVersion (major, minor, patch). The current version is 1.3.0, kept in gradle.properties as jelloui_api_version and in the jar metadata under custom.jelloui:api_version.

ApiVersion.isCompatibleWith implements this rule:

• an addon is accepted when the runtime major equals the required major
• and the runtime is at least as new in minor/patch

ApiVersion runtime = JelloApi.get().version();
ApiVersion required = new ApiVersion(1, 1, 0);
boolean ok = runtime.isCompatibleWith(required); // 1.3.0 can serve 1.1.0

A mismatched major is a hard incompatibility. The runtime does not enforce this automatically for addon entry points, so addons must perform the check before registration. Additive compatible API changes bump the minor; breaking changes require a new major and migration notes.

Your fabric.mod.json should also depend on the mod:

"depends": {
  "jelloui": ">=1.0.1+26.2"
}

The Fabric dependency is the JelloUI mod version (currently 1.0.1+26.2), not the API version. Use both checks: Fabric prevents a missing/old artifact from loading, while ApiVersion verifies the public contract exposed by that jar.

Core and addon boundary

JelloUI core ships the platform: the public API, Jello screens and ClickGUI shell, HUD and render dispatch, notifications, themes, fonts, animation, profiles and keybind infrastructure, the main menu and loading screen, Music Player and Music Manager, and the reusable world marker renderers.

The JelloUI Official Addon is a separate artifact that registers exactly the GUI-category modules: ActiveMods, BrainFreeze, Coords, Compass, MiniMap, KeyStrokes, MusicParticles and TabGUI. It does not ship gameplay, movement, combat or world modules.

Gameplay logic must never leak into core. Core owns none of: KillAura, BlockFly and equivalent feature logic; ESP target enumeration or filtering; or addon-specific module classes. When you contribute an ESP, the target selection stays in your addon and core only provides the drawing primitives (see 06-world-markers).

Error isolation

JelloUI places surface-specific exception boundaries around addon callbacks. Lifecycle, render, keybind, profile and similar dispatch paths contain callback failures so they do not abort an ongoing frame or tick. A RuntimeException from an addon initializer is logged and startup continues with the remaining addons. The exact boundary depends on the surface: those dispatch paths use ErrorIsolators, visibility and component paths perform their own catch/report handling, and theme token resolution falls back locally. Do not assume every callback failure reaches the process-global ApiErrorHandler.

Addons can use the public ErrorIsolators helpers around their own external callbacks:

String ownerId = owner.id().toString();
String result = ErrorIsolators.isolate(
        "example.operation", ownerId, "compute result", () -> "ok");
ErrorIsolators.swallow(
        "example.render", ownerId, "draw overlay", () -> { });

• isolate rethrows the failure as ApiRuntimeException so the caller can decide whether to continue
• swallow is the render/tick variant: a single failing listener must not abort the frame

setHandler replaces one process-global handler. If an addon temporarily installs one for diagnostics, retain and restore the previous handler in a finally block; do not permanently take error reporting away from the host or another addon:

ApiErrorHandler previous = ErrorIsolators.handler();
try {
    ErrorIsolators.setHandler((source, ownerId, message, throwable) ->
            myLogger.error("{} [{}] {}", source, ownerId, message, throwable));
    // Run the diagnostic operation.
} finally {
    ErrorIsolators.setHandler(previous);
}

Handlers run on the render and client threads, so they must be cheap and side-effect free, and must never rethrow. A failing handler falls back to a last-resort stderr report, never a way to take the game down.

Addon entry points have a separate startup guard that catches RuntimeException, logs it and continues with other addons.

Public API exception hierarchy

The base type is ApiError (a RuntimeException). Two subclasses let a caller distinguish failure classes:

• ApiRuntimeException - wraps a failure reported by ErrorIsolators.isolate
• ApiUsageException - the caller used the API incorrectly (duplicate id, invalid argument or invalid setting value)

ApiUsageExceptions are programming errors; they should never occur in a correctly written addon after release.

Current extension boundaries

JelloUI core owns the main menu, loading screen, ClickGUI, Music Player and the Spotlight UI. The public API currently does not replace the main-menu layout, replace the loading composition, or register arbitrary non-module Spotlight results. Generic Spotlight registration is not public and is not documented as supported. Do not depend on internal screen classes for these use cases. Custom ComponentProvider registration is public, but the current core does not install its opener bridge, so ComponentRegistry.open returns false.