VanillaConfig Mod Wiki

VanillaConfig (v26.1.2 for Minecraft) is a backend library and API developed by TreSet. It is designed to streamline the creation, management, and visual presentation of mod configurations. By providing a unified framework, it ensures that all dependent mods—such as Better Statistics Screen, Better Advancements, and Simple Compass—feature a consistent, high-quality settings menu that integrates seamlessly with the native Minecraft 'Options' aesthetic.

As a library mod, VanillaConfig does not add standalone gameplay elements like mobs, blocks, or biomes. Instead, it serves as a critical dependency for other mods, handling the complex logic of saving, loading, and migrating user settings while providing a robust GUI for players to interact with.

For developers looking to utilize VanillaConfig in their own projects, the mod must be added as a dependency in the build configuration. This grants access to the VanillaConfig entry point and its builder-based API.

Documentation Legend

To navigate the technical documentation, please refer to the following legend:

• [placeholder]: Parameters in square brackets are placeholders and must be replaced with actual code values (e.g., your mod's ID).
• Type1/Type2: Methods with parameter types separated by a slash can accept either of the two types.
• ?Type: Parameters prefixed with a question mark are optional and can be omitted.

Implementation

Developers typically initialize their configuration in the mod's main entry point using the following structure: Config [myConfig] = VanillaConfig.create("[modid]");

The configuration process is divided into two main components: Categories and Options. Categories act as organizational headers or tabs within the UI, while Options represent the actual settings the user can modify.

Configuration Hierarchy

1. Config Object: The root container for all settings.
2. Categories: Created via [myConfig].addCategory("[category_name]"). These group related settings together.
3. Options: Individual settings added to a category using type-specific methods (e.g., addBoolean, addInt).

VanillaConfig supports a diverse range of data types, each mapped to a specific UI element in the configuration screen to ensure ease of use for the player.

To ensure that user settings are not lost during mod updates, VanillaConfig includes advanced systems for tracking file versions and migrating legacy keys.

Version Management

Configuration files can include a config_version integer. When a mod is updated and requires a new file format, VanillaConfig compares the version in the existing file to the current mod version. If they do not match, the mod can execute specific logic to update the file without resetting user preferences.

Option Migration

The OptionMigration class allows developers to map old configuration keys to new ones. If a setting is renamed in a newer version of the mod, VanillaConfig will automatically find the value under the old key and move it to the new one upon the first launch.

Callbacks are essential for mods that need to react immediately when a user changes a setting. VanillaConfig provides several hooks for this purpose:

• onLoad: Executed immediately after the configuration file is read from the disk. This is used to apply settings when the game starts.
• onSave: Executed whenever the user clicks 'Done' or 'Save' in the config screen. This is ideal for triggering resource reloads or world updates.
• onChanged: A granular callback that can be attached to a specific option. It fires only when that individual setting is modified, allowing for efficient, targeted updates.

The Config Screen is the visual interface generated by the library. It is designed to match the native Minecraft 'Options' menu perfectly, providing a seamless user experience.

Key Features

• Search Bar: Allows users to filter through dozens of options by typing keywords.
• Reset to Default: Every individual option and every category has a reset button to quickly revert changes.
• ModMenu Integration: VanillaConfig automatically integrates with the ModMenu mod, adding a 'Configure' button to the mod list for every mod that uses the library.
• Dynamic Tooltips: Hovering over an option displays a descriptive tooltip, which can include multi-line explanations and default value indicators.

VanillaConfig is built with accessibility in mind, ensuring that all players can navigate and modify their settings regardless of their input method or visual needs.

• Narrator Integration: Every button, slider, and text field is fully compatible with the Minecraft Narrator, providing audible feedback for option names and current values.
• Keyboard Navigation: Users can navigate the entire configuration screen using only the keyboard (Tab, Shift+Tab, Enter, and Arrow keys).
• High Contrast Support: The UI elements respect vanilla high-contrast settings and provide clear visual focus indicators.

As a technical library and API, VanillaConfig does not add any mobs, items, or blocks to the game. It is a backend utility that powers the settings menus of other mods.

If you are looking for specific gameplay features, please refer to the documentation for the mods that depend on VanillaConfig, such as:

• Better Statistics Screen: Enhances the in-game statistics menu.
• Better Advancements: Overhauls the advancements UI.
• Simple Compass: Adds a customizable HUD compass.
• RideHud: Displays advanced information about ridden entities.