Event-Driven Third-Party Registration API

Target: 0.2.8-beta
Type: API / Developer Experience / Interoperability
Status: Planned

#Overview

Nourished already exposes a stable API for third-party mods to register nutrients, food classifications, compatibility data, and related definitions.

The current limitation is the registration lifecycle: external mods must currently register during an internal registration window, which requires addon authors to understand Nourished's initialization timing.

This enhancement would provide a documented, stable registration event so addon authors have an explicit and deterministic point at which Nourished registrations can be submitted.

The goal is not to redesign the existing registration API. The goal is to provide a clean lifecycle contract around the API that already exists.

Nourished currently provides methods such as:

• NourishedAPI.registerValue(...)

• NourishedAPI.registerSourceClassification(...)

• NourishedAPI.registerCompatEntry(...)

These already allow external mods to provide authoritative nutritional data.

However, registration currently depends on Nourished's internal registration window.

An addon author therefore needs to know when that window is open and avoid registering too late.

Introduce a stable Nourished registration event, tentatively:

NourishedRegisterEvent

The event should fire at one clearly documented point:

1. Nourished loads its built-in definitions.

2. Nourished opens the third-party registration phase.

3. NourishedRegisterEvent is dispatched.

4. External mods register through the existing NourishedAPI.

5. Nourished validates the resulting registrations.

6. Nourished closes/freezes registration.

7. Classification/runtime state is built.

The event becomes the documented synchronization point for Nourished integrations.

#Registration timing

• Define exactly when the event fires.

• Ensure built-in Nourished definitions are available when the event fires.

• Ensure registration remains open for the entire event dispatch.

• Freeze registration after the event completes.

• Late registration must continue to fail clearly.

#API compatibility

• Keep existing NourishedAPI.register* methods.

• Do not replace the existing registration system.

• Make the event an orchestration/lifecycle mechanism around the existing API.

• Mark the event/API surface with the appropriate @ApiStatus annotation.

#Registration validation

• Validate unknown nutrient references.

• Validate duplicate registrations.

• Validate invalid nutrient amounts/definitions.

• Define behavior for conflicting classifications.

• Document precedence rules.

#Authoritative classification

• Explicitly document that externally registered classifications are authoritative over automatic inference.

• Document any exceptions, including configured food overrides or exclusions.

• Add a regression test proving explicit registration wins over inference.

Create a minimal example showing how an unrelated NeoForge food mod can integrate with Nourished.

The example should demonstrate:

• Optional Nourished dependency.

• Safe class-loading when Nourished is absent.

• Listening for the Nourished registration event.

• Registering a custom nutrient.

• Registering a food classification.

• Verifying the registration is available after startup.

The example should be small enough to serve as the canonical integration reference.

Document how an addon should behave when Nourished is not installed.

• Define recommended NeoForge dependency metadata.

• Document optional/soft dependency configuration.

• Ensure Nourished-specific classes are not loaded when Nourished is absent.

• Provide a safe integration entry point.

• Document the recommended pattern for addon-side integration code.

Create a small integration/test mod or equivalent test coverage.

• Register a custom nutrient.

• Register a food classification.

• Verify registration succeeds during the event.

• Verify the registration exists after startup.

• Verify the explicit classification takes precedence over inference.

• Verify multiple external mods can register independently.

• Verify late registration fails.

• Verify duplicate/invalid registrations produce clear errors.

• Verify Nourished remains optional for the integrating mod.

Update the Nourished API documentation with:

• Registration lifecycle.

• NourishedRegisterEvent usage.

• Complete Java integration example.

• Optional dependency example.

• Registration precedence.

• Registration validation.

• Stable vs Experimental API boundaries.

• API versioning expectations.

The documentation should make it possible for a third-party developer to integrate without reading Nourished's implementation code.

Illustrative only — exact naming/signatures should be determined during implementation.

@EventBusSubscriber(modid = "examplemod")
public final class ExampleNourishedIntegration {

    @SubscribeEvent
    public static void register(NourishedRegisterEvent event) {
        NourishedAPI.registerValue(...);
        NourishedAPI.registerSourceClassification(...);
    }
}

The event should provide the registration lifecycle guarantee; addon authors should not need to inspect or query Nourished's internal registration state.

#Acceptance Criteria

This enhancement is complete when:

• A third-party mod has one documented registration point.

• The existing NourishedAPI.register* methods remain the underlying registration API.

• Registration timing no longer depends on guessing Nourished's initialization order.

• Explicit third-party classifications are documented as authoritative.

• Optional Nourished integration is documented and demonstrated.

• A minimal third-party integration example exists.

• Automated/regression tests cover registration and precedence behavior.

• The public API is clearly marked Stable/Experimental/Internal.

• No Nourished implementation packages are required for normal addon integration.

#Non-Goals

This enhancement does not aim to:

• Replace the existing classification system.

• Replace automatic food inference.

• Redesign NourishedAPI.

• Move all registration into events.

• Require every food mod to depend on Nourished.

• Make KubeJS part of the Stable Java API.

• Redesign MariesLib.

• Guarantee automatic classification of arbitrary modded foods.

#Related Architecture

Nourished already provides multiple integration paths:

Stable Java API → Datapacks → Compatibility data → Community tags → Automatic classification/inference → Scanner/user overrides

This enhancement primarily addresses the Java API lifecycle boundary.

#Notes

This work is intentionally deferred from the 0.2.7 UI/polish cycle.

The current API is already functional; this enhancement is about making the existing interoperability contract easier and safer for third-party developers to consume.

**Target milestone: 0.2.8-beta **