Package net.mezzdev.config.api.schema.builder

Interface IConfigSchemaBuilder

@NonExtendable public interface IConfigSchemaBuilder
Declares the settings stored in one config file or synchronized as one server config.

Obtain a builder from IConfigRegistration, add storage categories, build every value, then call build() during mod initialization. Add editor-only categories only when the config screen should organize values differently from the file.

Since:
0.1.0

  • Method Details

    • addCategory

      IConfigCategoryBuilder addCategory(String name)
      Add a named group of values to the config file. Categories are returned from IConfigSchema.getCategories() in the order they are added here.
      Parameters:
      name - stable storage name for the category
      Since:
      0.1.0

    • addEditorCategory

      IConfigEditorCategoryBuilder addEditorCategory(String name)
      Add a config-screen category without changing how values are grouped in the file. Editor categories are returned from IConfigSchema.getEditorCategories() in the order they are added here.
      Parameters:
      name - stable editor category name
      Since:
      0.1.0

    • setLegacySources

      IConfigSchemaBuilder setLegacySources(List<Path> legacyPaths)
      Load this schema from a MezzConfig file at an older location when the destination does not exist yet.

      Use this when a mod moves or renames a MezzConfig file. Values are matched by their current storage names and by the legacy names and migrations declared on IConfigValueBuilder. The first existing source is preserved and backed up, and MezzConfig writes the imported values to the new location in its current format. World-scoped schemas defer this check until their first local world destination becomes active. The migration is considered once per schema instance, not again for each subsequent world.

      To import a file that was not written by MezzConfig, use setLegacyMigration(List, IConfigMigrator) instead.

      Parameters:
      legacyPaths - ordered candidate MezzConfig source paths; must not be empty
      Returns:
      this schema builder
      Throws:
      IllegalArgumentException - if the path list is empty, contains null or duplicate normalized paths, or a path cannot be converted to an absolute path
      IllegalStateException - if a legacy source or migration was already registered or this builder was already built
      Since:
      0.3.0

    • setLegacyMigration

      IConfigSchemaBuilder setLegacyMigration(List<Path> legacyPaths, IConfigMigrator migrator)
      Import a config file that the mod used before adopting MezzConfig.

      Use this when the old file was not written by MezzConfig. To move a MezzConfig file from another location, use setLegacySources(List) and, when needed, declare renamed, moved, or converted values with the legacy methods on IConfigValueBuilder.

      Declare and build the destination values first so the migrator can update them. The paths are checked in order, which supports mods that used more than one old location. Migration is considered only when the new config does not exist. World-scoped schemas defer this check until their first local world destination becomes active. The migration is considered once per schema instance, not again for each subsequent world.

      The migrator parses the old format and supplies typed values; MezzConfig preserves and backs up the source, validates the complete import, and writes the new format atomically. See IConfigMigrator for an example.

      Parameters:
      legacyPaths - ordered candidate legacy file paths; must not be empty
      migrator - callback that parses the selected legacy file and queues typed updates
      Returns:
      this schema builder
      Throws:
      IllegalArgumentException - if the path list is empty, contains null or duplicate normalized paths, or a path cannot be converted to an absolute path
      IllegalStateException - if a legacy source or migration was already registered or this builder was already built
      Since:
      0.3.0

    • build

      IConfigSchema build()
      Finish the declaration, register the schema, and load its initial values.

      Call this once during mod initialization, after every value builder has been built. Build before registering generated config screens so integrations can discover the schema. Client schemas built on a dedicated server remain inactive and default-backed, which allows the same declaration code to run on both sides. Active local files are loaded or created before this method returns.

      Returns:
      the registered config schema
      Throws:
      IllegalArgumentException - when a backing file path is already reserved or the complete default config cannot be safely serialized
      IllegalStateException - when the schema has no storage category, a storage category has no config value, or a value builder has not been built
      UncheckedIOException - when an active backing file cannot initially be read or created
      Since:
      0.1.0