Architecture and Core Concepts

Config Overhauled replaces manual configuration handling with a structured, multi-loader declarative framework. The architecture enforces strict separation between definition, memory state, and disk serialization across Fabric, Forge, and NeoForge environments.

Structural Hierarchy

Configuration data is organized into a rigid hierarchical tree.

• ConfigManager: The root authoritative controller allocated per mod ID. Executes disk I/O, hierarchical registry management, and lifecycle synchronization across scopes.

• Category: Top-level structural classifications within the configuration hierarchy. Organizes subsidiary property groups.

• Group: Structural subdivisions within categories that encapsulate properties.

• Property: The foundational data container. Handles state encapsulation, disk serialization, network synchronization, and lifecycle broadcasting.

Registry and Instantiation Module

The framework utilizes ConfigRegistry as the centralized authority for managing and retrieving active configuration managers across all dependent mods. Platform-agnostic instantiation is achieved via the Java ServiceLoader pattern, which dynamically resolves platform-specific factory implementations. Dependent mods request a manager by passing their namespace identifier, and the registry handles allocation through thread-safe double-checked locking.

Scope Authority and Synchronization

Config Overhauled manages network synchronization autonomously based on property Scope Authority. The physical environment holding authority dictates the active state.

• CLIENT: Strictly local to the player's machine. Never synchronized. Utilized for UI themes, rendering tweaks, and local preferences.

• GLOBAL & LEVEL (Server Authoritative): For both of these scopes, the server asserts total authority. When a client joins, the server automatically pushes its configuration state to them, overriding their local values for the duration of the session. If a player with level 2 (OP) permissions modifies these properties via their config screen, a state change request is sent to the server, which then validates and broadcasts the update to all connected players. The primary difference between the two is their persistence and file path:

  • GLOBAL configurations apply to the entire physical server or client installation. They are stored in the main config directory (e.g., config/<modid>/<modid>-global.toml).

  • LEVEL configurations are tied strictly to a specific world save. They are stored inside the world folder (e.g., <world>/serverconfig/<modid>/<modid>-level.toml).

Client/Server Decoupling

Config Overhauled enforces strict physical boundaries. The core data model (ConfigManager) operates independent of graphical interfaces. Dedicated servers load the configuration manager without invoking client-side GUI classes, preventing JVM classloading violations.