Rubric Annotations

Rubric — Annotations

Every annotation Rubric reads from your config class. All are in package com.oliveryasuna.mc.rubric.api.annotation.

Marker

@Config

Marks a class as the root of a configuration. Exactly one @Config type maps to exactly one on-disk file.

Property	Type	Required	Default	Notes
id	String	Yes	—	Owning mod ID / namespace. Also used for ModMenu / Catalogue auto-discovery — must match your loader mod id (fabric.mod.json#id on Fabric, [[mods]].modId in META-INF/neoforge.mods.toml on NG) if you want the config to surface under your mod entry.
name	String	No	"config"	Base file name without extension.
format	Format	No	Format.TOML	See Formats.
version	int	No	1	Schema version. When a loaded file declares a lower version, registered migrations run in order. See Migration.

Target: TYPE.

@Config(id = "mymod", name = "config", format = Format.TOML, version = 3)
public final class MyConfig { … }

Structure

@Category

Groups entries under a named section (a sub-table in TOML, a nested object in JSON) and a collapsible group in the GUI. On a nested-object field or its type, overrides the section name. On a flat field, tags that field into a named group without requiring a nested class.

Property	Type	Required	Default	Notes
value	String	Yes	—	Section / group name.

Target: FIELD, TYPE.

@Key

Overrides the on-disk key for a field. Default is the Java field name; @Key decouples them so you can rename in Java without breaking existing config files, or follow a different naming convention (kebab-case, etc.).

Property	Type	Required	Default	Notes
value	String	Yes	—	On-disk key. Collisions rejected at registration.

Target: FIELD.

@Comment

Human-readable comment on an entry or category. Written to comment-supporting formats (TOML, HOCON, JSON5) and surfaced as the entry description in the generated GUI. Each array element is one line.

Property	Type	Required	Default	Notes
value	String[]	Yes	—	Comment lines, in order.

Target: FIELD, TYPE.

Constraints (validators)

Each of these attaches a Validator to the entry. Invalid values are corrected-and-logged on load — see Validation.

@Range

Constrains a numeric entry to an inclusive [min, max] range. Applies to byte/short/int/long/float/double and their boxed forms. Out-of-range values are clamped. Bounds also drive slider extents in the GUI.

Property	Type	Default	Notes
min	double	Double.NEGATIVE_INFINITY	Inclusive lower bound.
max	double	Double.POSITIVE_INFINITY	Inclusive upper bound.

Because bounds are declared as double, a long bound larger than 2^53 may be represented imprecisely.

Target: FIELD.

@OneOf

Restricts a String entry to an explicit allow-list. Renders as a dropdown in the GUI. (Enum fields are constrained implicitly and do not need @OneOf.)

Property	Type	Required	Notes
value	String[]	Yes	Permitted values.

Target: FIELD.

@Pattern

Requires a String entry to fully match a regular expression. Non-matching values are reset to default on load.

Property	Type	Required	Notes
value	String	Yes	java.util.regex.Pattern-compatible regex.

Target: FIELD.

@Length

Constrains a String's length or a List / Map's size to an inclusive [min, max] range. Over-long collections are truncated on load; strings failing the bounds are reset to default.

Property	Type	Default	Notes
min	int	0	Inclusive minimum.
max	int	Integer.MAX_VALUE	Inclusive maximum.

Target: FIELD.

@NotNull

Rejects a missing/null value. On load, a null is reset to the field's default.

Target: FIELD.

Presentation

@Hidden

Excludes an entry (or every entry in a category) from the generated GUI. The value is still serialized to and read from the file — only the editor screen hides it.

Target: FIELD, TYPE.

@Widget

Overrides the GUI control for an entry. Default control is inferred from the field's type and other constraints (bounded numeric → slider, enum → dropdown).

Property	Type	Default	Notes
value	Widget.Type	AUTO	See below.
allowInvalid	boolean	false	When false and the widget is in an invalid state, Save & Exit is blocked and a confirm-screen lists the offending paths. When true, invalid inputs are accepted; load-time correction handles cleanup on reload.

Widget types:

Type	Notes
AUTO	Infer from the field's type and constraints.
TOGGLE	Boolean on/off button.
SLIDER	Numeric slider — requires a bounded @Range.
NUMBER_FIELD	Free-form numeric input.
TEXT_FIELD	Free-form text input.
DROPDOWN	Used for enums and @OneOf.
COLOR	Color picker; backed by a "#RRGGBB" string.

Target: FIELD.

Runtime semantics

@Sync

Declares the synchronization scope of an entry. On a type, sets the default for every entry in that config; on a field, overrides for that entry.

Property	Type	Default	Notes
value	Sync.Scope	Scope.CLIENT	See below.

Scopes:

Scope	Semantics
CLIENT	Client-owned, local only, never synced.
SERVER	Server-authoritative. Pushed to clients for the session; client cannot override and it is not written to the client's disk.
COMMON	Server-authoritative when connected; falls back to the client's local defaults in singleplayer.

Target: FIELD, TYPE. Details in Sync.

@Reload

Declares when a changed value takes effect. On a type, sets the default for the config; on a field, overrides.

Property	Type	Default	Notes
value	Reload.Tier	Tier.WORLD	See below.

Tiers:

Tier	Semantics
LIVE	Applied immediately on change. Intended for client / cosmetic values.
WORLD	Applied on the next world (re)load. The default.
RESTART	Applied only after a game restart.

Target: FIELD, TYPE.

@RequiresRestart

Convenience marker equivalent to @Reload(Reload.Tier.RESTART). If both are present on the same element, @Reload wins.

Target: FIELD.

---

Format enum

Not an annotation — the enum accepted by @Config#format.

Value	Notes
TOML	Comment-preserving. Default and recommended.
JSON	Plain JSON. No comment support.
JSON5	Relaxed JSON with comments and trailing commas.

See Formats for how to wire the right adapter into your ConfigIO.