-
Notifications
You must be signed in to change notification settings - Fork 0
Config Vars
TBN_MapleWheels edited this page Jan 28, 2023
·
5 revisions
Configuration variables (ConfigVars or CVars) allow you to create named variables that are capable of;
- Save/Load to/from disk;
- Network Synchronization and;
- Being displayed in the Barotrauma Settings Menu when in a lobby.
This allows you to easily add configuration variables to your mod with ease of use by your mod users. If you are only interested in the Networking
All configuration variables are stored under <Game_Root>/Config/<ModName>/<ModName>.xml. ModName is the sanitized version of the Mod Name value so they may not match.
NOTE: As Lua doesn't handle Generic method calls without mess, the only C# function you CANNOT use is AddConfigEntry<T>(), please make use of the helper extensions below. Everything else should follow the C# Config Var instructions further down (but written in Lua Syntax obviously).
-- Availability: CLIENT AND SERVER
-- Simplest version
local mySimpleVar = ConfigManager.AddConfigBool(
"MyVarName1", -- [REQUIRED] Variable name
"MyModName", -- [REQUIRED] Mod name, used for the config file name.
false -- [REQUIRED] Default value.
)
-- Set your value
mySimpleVar.Value = true
-- Access your value
print(mySimpleVar.Value)
-- Save your value to file/disk
ConfigManager.Save(mySimpleVar)
-- Want to access it somewhere else?
local myVar2 = ConfigManager.GetConfigMember("MyModName","MyVarName1")To create a configuration var simply use the API as per the below examples. The API is defined in the ConfigManager class (in /Client and /Shared).
using ModdingToolkit.Config;
//...
void Initialize()
{
// Availability: CLIENT AND SERVER
// Simplest verion
IConfigEntry<bool> mySimpleVar = ConfigManager.AddConfigEntry<bool>(
"MyVarName1", // [REQUIRED] Variable name
"MyModName", // [REQUIRED] Mod name, used for the config file name.
false // [REQUIRED] Default value.
);
//Set your value
mySimpleVar.Value = true;
//Access your value
LuaCsSetup.PrintCsMessage($"MySimpleVar={mySimpleVar.Value}");
//Save your value to file/disk
ConfigManager.Save(mySimpleVar);
}using ModdingToolkit.Config;
//...
void Initialize()
{
// Availability: CLIENT AND SERVER
// T implements IConvertible: Primitive variable (bool, int, float, etc) and string, enum.
// Shows every field.
IConfigEntry<int> myConfigvar = ConfigManager.AddConfigEntry<int>(
name: "MyVarName2", // [REQUIRED] Variable name
modName: "MyModName", // [REQUIRED] Mod name, used for the config file name.
defaultValue: 10, // [REQUIRED] Default value.
networkSync: NetworkSync.NoSync, // [OPTIONAL] Whether or not it should be synced between server and clients.
valueChangePredicate: (newVal) => // [OPTIONAL] Predicate/Validation for a new value, returning false stops Var.Value from being changed.
{
return newVal > 20;
},
onValueChanged: (instance) => // [OPTIONAL] Called whenever the value is sucessfully updated.
{
LuaCsSetup.PrintCsMessage($"Value updated! Now: {instance.Value}")
},
filePathOverride: null, // [OPTIONAL] Allows you to change what disk file the value is loaded from.
// [OPTIONAL] Allows you to change how the config var is displayed in menus
displayData: new DisplayData( // or mods that implement it.
DisplayName: "My Var #2",
DisplayModName: "My Mod",
DisplayCategory: "General",
Tooltip: "Unimplemented",
ImageIcon: null,
MenuCategory: Category.Gameplay
)
);
// Availability: CLIENT AND SERVER
// Dropdown List of strings
IConfigList myConfigList = ConfigManager.AddConfigList(
"MyListVar3", // [REQUIRED] Variable name
"MyModName", // [REQUIRED] Mod name, used for the config file name.
"SomeValue2", // [REQUIRED] Default value, MUST exist in the list of values.
new List<string>(){ "SomeValue1", "SomeValue2", "SomeValue3" }, // [REQUIRED] List of values in the list.
networkSync: NetworkSync.NoSync, // [OPTIONAL] Whether or not it should be synced between server and clients.
valueChangePredicate: (newVal) => // [OPTIONAL] Predicate/Validation for a new value, returning false stops Var.Value from being changed.
{
return newVal.Equals("SomeValue1");
},
onValueChanged: (instance) => // [OPTIONAL] Called whenever the value is sucessfully updated.
{
LuaCsSetup.PrintCsMessage($"Value updated! Now: {instance.Value}")
},
filePathOverride: null, // [OPTIONAL] Allows you to change what disk file the value is loaded from.
// [OPTIONAL] Allows you to change how the config var is displayed in menus
displayData: new DisplayData( // or mods that implement it.
DisplayName: "My Var #3",
DisplayModName: "My Mod",
DisplayCategory: "General",
Tooltip: "Unimplemented",
ImageIcon: null,
MenuCategory: Category.Gameplay
)
);
// Availability: CLIENT AND SERVER
// Displays as a Slider in the Settings Menu: Gameplay Tab
// Creates a limited range variable, only available as INT or FLOAT.
// FOR FLOAT: IConfigRangeFloat => ConfigManager.AddConfigRangeFloat()
IConfigRangeInt icri = ConfigManager.AddConfigRangeInt(
"TestEntry04", // [REQUIRED] Variable name
"ModdingTK", // [REQUIRED] Mod name, used for the config file name.
10, // [REQUIRED] Default value.
0, // [REQUIRED] Minimum value.
20, // [REQUIRED] Maximum value.
21, // [REQUIRED] Steps on the Slider. Should be ((Max - Min)/IncrementPerStep) + 1
networkSync: NetworkSync.ServerAuthority,// [OPTIONAL] Whether or not it should be synced between server and clients.
valueChangePredicate: (newVal) => // [OPTIONAL] Predicate/Validation for a new value, returning false stops Var.Value from being changed.
{
return newVal > 5;
},
onValueChanged: (instance) => // [OPTIONAL] Called whenever the value is sucessfully updated.
{
LuaCsSetup.PrintCsMessage($"Value updated! Now: {instance.Value}")
},
filePathOverride: null, // [OPTIONAL] Allows you to change what disk file the value is loaded from.
// [OPTIONAL] Allows you to change how the config var is displayed in menus
displayData: new DisplayData( // or mods that implement it.
DisplayName: "Test Entry #004",
DisplayModName: "Modding TK",
DisplayCategory: "General",
Tooltip: "Unimplemented",
ImageIcon: null,
MenuCategory: Category.Gameplay
)
);
// Availability: CLIENT ONLY
// Creates a Key/Mouse Bind in the Settings Menu: Controls Tab
IControlConfig myKeybind = ConfigManager.AddConfigKeyOrMouseBind(
"MyKeybindVar", // [REQUIRED] Variable name
"MyModName", // [REQUIRED] Mod name, used for the config file name.
new KeyOrMouse(Keys.C), // [REQUIRED] Default value. Use the "MouseButton" Enum for mouse binds.
displayData: new DisplayData(
DisplayName: "My Keybind #001",
DisplayModName: "My Mod"
)
);
}// Configuration Storage Class
class MyConfig
{
public IConfigList ProfilesList { get; private set; } = ConfigManager.AddConfigList(
"ProfilesList",
"MyModProfiles", // <== VERY IMPORTANT: This mod name MUST be different from the rest of the CVars
// or you will end up in an INFINITE LOOP! See below.
"Normal",
new List<string>(){ "Easy", "Normal", "Hard" },
networkSync: NetworkSync.ServerAuthority,
onValueChanged: (instance) =>
{
this.SetProfile(instance.Value); // Pass the string value in as a profile name.
// If there's anything else you need to do, hook from here.
// INFINITE LOOP: This function is called when a new value is loaded.
// So if you use the same mod name as the others, every time it loads values from disk,
// it'll just call this function again, which repeats the process!
},
displayData: new DisplayData(
DisplayName: "My Var #3",
DisplayModName: "My Mod",
DisplayCategory: "General",
MenuCategory: Category.Gameplay
)
);
public IConfigEntry<int> MyConfigVar01 { get; private set; } = ConfigManager.AddConfigBool(
name: "MyConfigVar01",
modName: "MyMod",
defaultValue: 10,
networkSync: NetworkSync.ServerAuthority
displayData: new DisplayData(
DisplayName: "My Var #2",
DisplayModName: "My Mod",
DisplayCategory: "General",
MenuCategory: Category.Gameplay
)
)
private void SetProfile(string profileName)
{
// build filepath
string filePath = System.IO.Path.Combine(
ConfigManager.BaseConfigDir, // The base location where all config data is stored.
Utils.IO.SanitizePath(config.ModName), // The name of your mod as a container-folder.
Utils.IO.SanitizeFileName(profileName) + ".xml" // The name of your profile + ".xml" = will load => ./Config/MyMod/<profilename>.xml
);
// load and apply to all mod cvars
ConfigManager.ReloadAllValuesForModFromFiles("MyMod", filePath);
}
}
class MyMod : IAssemblyPlugin
{
MyConfig ActiveConfig;
void Initialize()
{
ActiveConfig = new();
}
void OnLoadCompleted()
{
if (ActiveConfig.MyConfigVar01 > 15)
{
// Do something with it / your mod code.
}
}
}