Repository navigation
Mod Configs
A ModConfig is written as in tModLoader: a class with public fields (or
properties), described by attributes. It is loaded with the mod, before
Load, so its values can already be read there.
using System.ComponentModel;
using Terraria.ModLoader.Config;
public class ExampleModConfig : ModConfig
{
public override ConfigScope Mode => ConfigScope.ClientSide;
[Header("Items")]
[DefaultValue(true)]
[ReloadRequired]
public bool ExampleWingsToggle;
[Range(60, 250)]
[Increment(5)]
[DefaultValue(100)]
public int SpawnRate;
}Read it with ModContent.GetInstance<ExampleModConfig>(), or declare
public static ExampleModConfig Instance; in the class and it is filled in.
The players change the options in Mod Configuration: a button in the pause
menu and a row at the top of the General tab of the title screen's settings.
It has one tab per mod (with the mod's
icon.png), Discard/Back, Default and Apply. Nothing reaches the
config before Apply; then SaveChanges runs for each config that changed.
| Field type | Shown as |
|---|---|
bool |
On/Off |
int, float, byte... |
slider, from [Range] (default 0–100, or 0–1 for float) in steps of [Increment]
|
enum, string with [OptionStrings]
|
buttons up to 3 choices, a list up to 12, otherwise < >; [Dropdown] and [Cycle] choose |
Color |
the color with hue, saturation and lightness ([ColorHSLSlider(false)] keeps only the hue, [ColorNoAlpha] keeps alpha at 255) |
Other types (lists, dictionaries, Vector2, classes) are saved and loaded but
not shown. [Header("Id")] puts a title over a field. With more than one
config, each one gets its DisplayName as a title.
The texts come from the localization files, with tModLoader's keys:
Mods.<Mod>.Configs.<Config>.DisplayName-
Mods.<Mod>.Configs.<Config>.<Field>.Label(or[LabelKey("$key")]) -
Mods.<Mod>.Configs.<Config>.Headers.<Id>(or[Header("$key")]) -
Mods.<Mod>.Configs.<Enum>.<Value>.Labelfor the choices of anenum
A missing text shows the name with spaces (SpawnRate → "Spawn Rate").
The values are saved in ModConfigs/<Mod>_<Config>.json, next to the
Worlds folder. [DefaultValue] gives the starting value, and the fresh
instance's field initializers apply where there is none.
var pending = (ExampleModConfig)config.Clone();
pending.SpawnRate = 150;
ConfigSaveResult result = config.SaveChanges(pending);SaveChanges writes the file, copies the values and calls OnChanged. In a
world, a change to a [ReloadRequired] field is refused (NeedsReload) and
its row is greyed out; in the title screen it is saved and takes effect the
next time the game starts.
config.Open() opens the screen on the mod's tab, as in tModLoader. In a
world it opens over the game and Back returns to it; onClose runs when the
screen closes. scrollToOption scrolls to a field (nameof(MyConfig.Field)),
or to the header above it with "Header:Field"; centerScrolledOption: false
puts it at the top instead of the middle.
ModContent.GetInstance<ExampleModConfig>().Open(onClose: () => Main.NewText("Closed"), scrollToOption: nameof(ExampleModConfig.SpawnRate));Mode says whose values count:
-
ConfigScope.ClientSide: each player has their own values, saved on their device. They never go over the network. -
ConfigScope.ServerSide: in multiplayer the host's values count for everyone. A player who joins receives them (their own file is not touched) and gets their own values back on leaving. Only the host sees these configs on the screen, under "Server Side Config"; a client in multiplayer does not see them. They also show in single player and on the title screen.
When a mod's code on a client changes a ServerSide config, SaveChanges returns
RequestSentToServer and the change is not applied yet. The host checks it:
a [ReloadRequired] change is refused, and then AcceptClientChanges decides.
An accepted change is saved by the host and sent to every player, a refusal
only to the one who asked. Everyone then gets
HandleAcceptClientChangesReply(success, player, message), and the chat shows
the result. The host's own changes are applied directly and sent to everyone.
public override bool AcceptClientChanges(ModConfig pendingConfig, int whoAmI, ref NetworkText message)
{
if (!NetMessage.DoesPlayerSlotCountAsAHost(whoAmI))
{
message = NetworkText.FromKey("tModLoader.ModConfigRejectChangesNotHost");
return false;
}
return true;
}If the host uses other values in [ReloadRequired] options, the joining
player gets them anyway, with a chat warning: content loaded at start only
follows them after restarting the game with those values (tModLoader reloads
the mods instead).
An option's tooltip comes from Mods.<Mod>.Configs.<Config>.<Option>.Tooltip,
or from [TooltipKey] and [TooltipArgs], as in tModLoader. The touch screen
has no hover, so an option with a tooltip shows a ? button right after its
name. Touching it opens a panel over the list with the option's name and the
tooltip, wrapped to the panel's width ( starts a new line). Any touch
closes it, and touching the ? does not change the option.
Configs: {
ExampleConfig: {
ShowTrail: {
Label: Show trail
Tooltip: Draws a trail behind the sword.
}
}
}
Custom elements ([CustomModConfigItem]), separate pages, and editing lists, dictionaries,
vectors and free text.
Example: samples/ExampleModCSharp (ExampleModConfig,
ModConfigShowcaseRanges, ModConfigShowcaseAcceptClientChanges and the
supported part of ModConfigShowcaseMisc).
Bunny Loader wiki ·
Discord ·
Repository ·
BL Editor
Written for Bunny Loader 0.5.5-beta and Terraria Mobile 1.4.5.8.6.
Bunny Loader is not affiliated with Re-Logic or 505 Games.
