About

Seamless API is the shared integration backbone for the Seamless mod ecosystem. It mostly just makes mod development easier for myself by being able to reuse things.

It lets modders register gameplay data through stable hooks instead of patching internals, so multiple addons can extend the same systems cleanly and safely.

This release focuses on a practical, production-ready API surface for food buffs, combo definitions, deconstruction mappings, meteor triggers, and reusable thrown-item visuals.

Project Goal

Build one long-term API foundation that keeps gameplay authority in host mods while giving addon developers a clean and predictable way to integrate.

That means:

• easy registration
• safe multiplayer behavior
• extension points for future systems
• minimal breakage risk as the ecosystem grows

Features

• Unified Seamless Facade: one entry path for Food, Deconstruction, Meteor, and Visual modules
• Food Buff Registration: builder-based food buff definitions with duration, magnitude, and hearts
• Combo Registration: define multi-food combo requirements and bonus effects
• Deconstruction API: register item breakdown recipes with dynamic output modifier hooks
• Meteor Event Bridge: trigger meteor shower events when the meteor implementation mod is present
• Visual Utility API: reusable thrown-item profiles, spin/tumble animation logic, and trail math helpers
• Freeze and Merge Lifecycle: host mods lock registration and merge immutable data at startup
• Server-First Contract: designed for multiplayer-safe integrations and controlled runtime behavior

Developer Workflow

1. Register foods, combos, and deconstruction data during mod setup.
2. Host mods freeze and consume registrations.
3. Use runtime query/events/modifiers for advanced behavior where supported.

Late registration intentionally throws after freeze to prevent unstable state.

Module Overview

• Food Module: food buffs, combo metadata, query/events/modifier integration points
• Deconstruction Module: input-to-output mapping plus modifier chain for contextual scaling
• Meteor Module: optional API bridge for starting and stopping meteor showers
• Visual Module: shared math/profiles for polished thrown-item rendering and trails

Requirements

• Minecraft 1.21.11
• Fabric Loader 0.18.5+
• Fabric API 0.141.3+ (1.21.11)
• Java 21+

Notes

• Seamless API is intentionally gameplay-light: host mods remain the source of truth.
• The API is designed to degrade gracefully when optional companion implementations are absent.
• Ideal for addon mods, modpack integrations, and ecosystem-wide compatibility without hard patches.

API Integration

Typical local integration flow:

1. Publish Seamless API to local Maven.
2. Add it as compile/runtime dependency in your mod.
3. Register your content during initialization.
4. Let host mods freeze and merge for runtime use.

This keeps integrations clean, versionable, and easy to maintain across updates.

Also Check Out

Seamless-API

Seamless-API is a lightweight integration layer that lets other mods add food buffs and combo definitions to Advanced Food System without patching its internals.

This API is the shared base for all of my mods, and it is intentionally designed to grow as my mod ecosystem grows.

Core design goals:

• Keep registration simple and stable.
• Keep gameplay authority in the main mod.
• Provide enough hook points for extension and interoperability.
• Stay safe under multiplayer server rules.
• Remain forward-looking so new systems can be added in future versions without breaking existing integrations.

Companion project:

• This API is consumed by Advanced Food System.
• Main gameplay architecture and built-in combos are documented in ../Advanced-Food-System/BIG_README.md.

What This API Provides

• Food registration API with builder-based schema.
• Combo registration API with requirements/effects/capstone metadata.
• Buff lifecycle event classes for applied/removal/pre-apply interception.
• Query API for active buffs on server players.
• Dynamic modifier registry for magnitude/health/filter hooks.
• Immutable buff data transfer object for integrations.

Integration Lifecycle

1) Registration Phase (before freeze)

Third-party mods call:

• SatiationAPI.registerFood(...)
• SatiationAPI.registerCombo(...)

2) Freeze and Merge

Advanced Food System calls:

• SatiationAPI.freezeAndGetAll()
• SatiationAPI.freezeAndGetCombos()

After freeze, late registration throws by design.

3) Runtime Query and Hooks

At runtime, mods can:

• inspect active buffs
• remove selected buff groups
• subscribe to or emit behavior around buff lifecycle events
• register dynamic modifiers/filters

API Surface (Class Guide)

Root

• SeamlessApiMod: minimal NeoForge mod entrypoint for the API jar.
• SatiationAPI: central registration gateway and freeze control.

Data and Registration Models

• api/FoodBuffRegistration: immutable food buff descriptor with fluent builder.
• api/ComboRegistration: immutable combo descriptor with fluent builder.
• api/BuffData: immutable snapshot of one active buff instance.

Runtime Extension APIs

• api/BuffQueryAPI:

  • getAllBuffs
  • getBuffsMatching
  • hasBuffWithId
  • getAggregateMagnitude
  • getActiveFoodBuffCount
  • removeBuffsWithId
  • removeBuffsFromSource

  • api/BuffModifiers:

    • registerMagnitudeModifier
    • registerHealthModifier
    • registerApplicationFilter
    • applyMagnitudeModifiers (internal usage)
    • applyHealthModifiers (internal usage)
    • shouldApplyBuff (internal usage)

  • api/BuffEvents:

    • BuffAppliedEvent
    • BuffRemovedEvent (with RemovalReason enum)
    • BuffApplyingEvent (cancel/mutate before apply)

Typical Usage Patterns

Add a Food

• Define buff ids, duration, magnitude, and hearts through FoodBuffRegistration.builder().
• Register during mod setup before load-complete.

Add a Combo

• Define required food ids and buff effects through ComboRegistration.builder().
• Optionally mark capstone and final-heart unlock behavior.
• Register before freeze.

React to Buff Lifecycle

• Subscribe to BuffEvents classes through NeoForge event bus.
• Trigger side effects (logging, achievements, conditions) when buffs apply/remove.

Modulate Behavior Dynamically

• Use BuffModifiers to scale values from external systems (gear, biome, dimension, etc.).
• Use filters to block buff application contextually.

Compatibility Contract

• API jar intentionally avoids owning gameplay authority.
• Advanced Food System remains the source of truth for storage, ticking, and effective application.
• Reflection bridges in query helpers are designed to degrade safely when internals are unavailable.

Build and Publishing

From Seamless-API root:

• Windows: gradlew.bat clean build publishToMavenLocal

Typical local workflow:

1. publish Seamless-API to mavenLocal
2. build Advanced-Food-System against that artifact

Why This Exists

Without this API, each modpack or addon would need custom hard patches into Advanced Food System. With this API, ecosystem mods can register new foods and combo ideas quickly while keeping one consistent runtime pipeline.

This project is planned as a long-term foundation for all of my mods, with additional APIs and integration points to be added over time.