Annotations

Change how a setting syncs, who may edit it, and what happens when it changes.

Annotations go on a single field or on a whole class. A field-level annotation takes precedence over a class-level one, which lets you set a default for the class and then upgrade individual settings.

Permissions and syncing

Annotation	What it does
`@WithPerms`	Sets the operator level needed to edit a setting or class, overriding the config's default.
`@WithCustomPerms` and `@AdminLevel`	Node-style permissions in the LuckPerms and Forge Config API style. Setting-level nodes beat class-level ones. Added in 0.4.0.
`@ClientModifiable`	Lets any player edit a synced setting and push it, whatever their permission level. Use sparingly.
`@NonSync`	Excludes a field from syncing, which also removes its permission requirement since it cannot affect the server. Consider a separate client config first.

Change consequences

@RequiresAction tells the player what they have to do for a change to take effect. Actions are ranked by their enum ordinal, so a class-level action can be upgraded on individual settings.

Action	Prompts the player to
`RESTART`	Restart the game or server. Highest priority.
`RELOG`	Disconnect and reconnect.
`RELOAD_BOTH`	Reload datapacks and resource packs.
`RELOAD_DATA`	Reload datapacks.
`RELOAD_RESOURCES`	Reload resource packs.

@RequiresAction(Action.RESTART)
var renderDistance = ValidatedInt(8, 32, 2)

@RequiresAction(Action.RELOAD_RESOURCES)
var textureVariant = ValidatedIdentifier.ofRegistry(Registries.ITEM)

@RequiresRestart still works but was deprecated in 0.4.0. It is the same as @RequiresAction(Action.RESTART) with no other options.

Structure and versioning

Annotation	What it does
`@Version`	Stamps a version integer at the top of the file. When the file's version does not match, the config's `update()` is called so you can migrate.
`@ConvertFrom`	Reads a config written by another library and scrapes it. Accepts `.toml`, `.json`, `.json5` and `.jsonc`.
`@RootConfig`	Marks one config as the root, so its settings sit on the landing page under the buttons for the others. Does nothing if you only have one config.
`@IgnoreVisibility`	Lets the serializer reach non-public fields. Works on a config, a section, or a class wrapped by `ValidatedAny`.
`@ConfigDeprecated`	Marks a setting deprecated: hidden in the GUI and left out of network traffic, but still read from file so you can migrate it. Added in 0.7.5.

Translation

@Translation overrides the default lang key scheme for a setting or a whole class. Applied to a class, it can be negated on individual settings that should keep the default keys. If the given lang key is missing, the default translation is used instead.

TomlKt, the serializer underneath, supplies its own annotations for shaping the .toml file itself, such as comments and inline tables.

Need more depth on this topic? The wiki has a longer article. Read it on moddedmc.wiki.