Package net.mezzdev.config.api.schema

Interface IConfigSchema

@NonExtendable public interface IConfigSchema
Provides runtime access to a group of config values stored and activated together.

Get an instance from IConfigSchemaBuilder.build(). Most mods keep the IConfigValue objects they build and use the schema when several values must change atomically. Config screens and other integrations can discover schemas through Configs.getSchemas() and inspect their categories.

Runtime methods are thread-safe. Listeners run synchronously after a complete change has been applied; listener failures are logged, and reentrant updates start a separate nested notification. Pending listeners run before effective listeners for the same operation. Within either kind, single-value listeners run before value-scoped batch listeners, and schema batch listeners run last. All listeners for an operation are snapshotted before its first callback. Listener changes made during a callback affect subsequent operations, including reentrant updates, but not the operation in progress.

Listener registrations normally live as long as this schema, which is usually the full mod lifetime, so callers may ignore their returned removal callbacks. Keep and run a removal callback when its listener captures a shorter-lived object, such as a screen, reloadable runtime, or connection-specific component. Client-per-world schemas retain their listeners across world changes and notify them when effective values change.

Since:
0.1.0

  • Method Details

    • getId

      String getId()
      Get the stable storage identifier for integrations that need to distinguish this schema.

      Automatically located schemas use their normalized relative config file name. Explicit-location schemas use their normalized absolute configured path. Treat this as an opaque storage identity rather than display text.

      Since:
      0.3.0

    • getModId

      String getModId()
      Get the mod id that owns this config schema.

      Config editors can use this to group schemas and attach generated config screens to the owning mod.

      Since:
      0.1.0

    • getType

      ConfigSchemaType getType()
      Get this schema's activation, authority, and location behavior.
      Since:
      0.3.0

    • isActive

      boolean isActive()
      Return whether this schema currently supplies values for the running game context.

      ConfigSchemaType.CLIENT schemas are active on a physical client and inert on a dedicated server. ConfigSchemaType.CLIENT_PER_WORLD schemas are active on a physical client only while a singleplayer world or multiplayer connection is available, and are inert on a dedicated server. ConfigSchemaType.SERVER schemas are active while locally authoritative for a loaded world or after a client receives an authoritative server snapshot.

      Since:
      0.2.0

    • getPath

      Optional<Path> getPath()
      Get the current local backing file path, if one exists.

      Client schemas have a path on a physical client. Client-per-world and locally authoritative server schemas have a path while their world or connection context is active. Inert client declarations on a dedicated server and schemas without an active context return an empty optional. An active synchronized remote server schema also returns an empty optional because its backing file belongs to the server; use isActive() to distinguish it from an inactive schema.

      MezzConfig owns this file; mods should use IConfigValue rather than reading or writing it directly.

      Since:
      0.1.0

    • getCategories

      @Unmodifiable List<? extends IConfigCategory> getCategories()
      Get all the categories in this schema. Each category contains values that can be read or edited. Categories are returned in the order they were added to the schema builder.
      Since:
      0.1.0

    • getEditorCategories

      @Unmodifiable List<? extends IConfigEditorCategory> getEditorCategories()
      Get all categories where config editors can show values.

      Storage categories and editor-only categories are returned in the order they were added to the schema builder.

      Since:
      0.1.0

    • batchUpdate

      @Unmodifiable List<? extends IAppliedConfigValueChange<?>> batchUpdate(Consumer<IConfigBatchUpdater> updateBatch)
      Change several values as one atomic user action.

      Use this for related settings that must not expose a partially updated state. Call IConfigBatchUpdater.set(IConfigValue, Object) inside the callback. If any update is invalid or the callback throws, none of them are applied.

      Parameters:
      updateBatch - callback that queues updates
      Returns:
      saved-value changes that were applied
      Throws:
      IllegalArgumentException - if a value is invalid, cannot be safely serialized, or does not belong to this schema
      IllegalStateException - if a non-empty batch is applied while this schema has no active local backing file, including synchronized server schemas viewed on a remote client
      Since:
      0.1.0

    • addBatchListener

      Runnable addBatchListener(IConfigValueBatchChangeListener listener)
      Listen for any effective values in this schema changing together.

      Use this when derived state depends on multiple settings. Pending restart-required edits are reported later, when they become effective.

      Parameters:
      listener - callback accepting the applied changes
      Returns:
      a callback that removes this listener
      Since:
      0.1.0

    • addPendingBatchListener

      Runnable addPendingBatchListener(IConfigValueBatchChangeListener listener)
      Listen for any saved values in this schema changing together, including changes waiting for a restart.

      Use this for editors or diagnostics that need to display what is saved rather than only what is currently effective.

      Parameters:
      listener - callback accepting the pending changes
      Returns:
      a callback that removes this listener
      Since:
      0.3.0