Adding Settings to an Extension

Intro

An Extension must have a settings.lua file in order to interface its Settings with the Extension Manager. See Extension Structure on how to set that up. Once you have your empty settings.lua file, you can continue with this guide.

There is a template at the bottom of this page.

Defining Settings

Settings are defined in a table, where each key marks a Setting. The value of this key is a table that describes the behavior of the Setting. Since all Settings are networked to Clients in order to access and change them, their type must be pre-defined for networking purposes.

Start off by making your local Settings Metatable:

local settings = {
	
}

Adding a Setting

A setting entry in the settings table has this form:

["SettingName"] = {
	Type = ...,
	Default = ...,
	NetWrite = ...,
	NetRead = ...,
	CustomPanel = {
		Create = ...,
		Set = ...,
		Get = ...
	},
	Save = ...,
	Load = ...,
	Parse = ...
}

Each of these except Default are optional!

---

Field	Description
Type	Optional if NetSend, NetRead, and CustomPanel is defined. Necessary otherwise. Defines the expected type of value for this Setting, providing default networking and panel. Supported types are: * TYPE_STRING: String value (Text field) * TYPE_NUMBER: Numeric value (Number field) * TYPE_BOOL: Boolean value (Checkbox with label) * TYPE_VECTOR: Vector (3 number fields with save button) * TYPE_ANGLE: Angle (3 number fields with save button) * TYPE_MATRIX: 4x4 Matrix (4x4 number fields with save button) * TYPE_COLOR: Color (Color selector with save button) This provides defaults for NetWrite, NetRead, and CustomPanel and is not needed if these are overridden. Also supports custom types added through nzu.AddCustomExtensionSettingType. Currently there exist "ResourceSet", "HUDComponent", and "Weapon".
Default	Necessary. Defines the Default value for when the Extension is just loaded, or it did not receive this setting on load.
NetWrite	Optional. Adds custom network handling. Should be a function that takes the value as argument, and calls net.Write* functions. Used with NetRead to send custom networking.
NetRead	Optional. Adds custom network handling. Should be a function that calls net.Read* functions and should return the interpreted result. Used with NetWrite to receive custom networking.
CustomPanel	Optional. Adds custom panel creation to the Extension's Settings Panel for this setting. Should be a table containing: * Create: Function that creates and returns a panel * Set: Function that takes the panel and the received setting value, and applies it to the panel * Get: Function that takes the panel and returns the setting value it is set to See Creating a Custom Panel.
Save	Optional. Allows custom saving behavior by replacing what value gets saved in the Config's settings.txt file. Should be a function that takes the setting value and returns the replacement. Can be used with Load to optimize or specialize saving and loading.
Load	Optional. Allows custom loading behavior by replacing what value gets loaded from the Config's settings.txt file. Should be a function that takes the JSONToTable-interpreted value and returns the real setting. Can be used with Save to read the specialized save data back into its original value.
Parse	Optional. Allows interpreting requested save values. Should be a function that takes the requested save value and returns the replacement. This is performed on the Server before the value is networked. Can be used to ensure certain setting properties.

---

Fill in settings with any amount of these Settings tables as you want for your Extension.

local settings = {
	["StartingPoints"] = {
		Type = TYPE_NUMBER,
		Default = 500,
		Parse = function(n) return math.Round(n) end
	}
}

Creating a Custom Panel

See how the default Type panels were made.

When a Settings Panel is to be created, its Create function is run, passing the parent as the argument if any. This function should create and return a panel to be used for this Setting. The panel gets outfitted with a Send function. It should at some point call it on itself in to network its value to the server.

panel:Send()

This can be on text field focus loss, on value changed, or with a save button you add onto the panel. Avoid using Value Changed for panels that may update their values smoothly every frame, as this creates much unnecessary networking.

Get and Set

The CustomPanel field must also contain Get and Set fields which contain functions for retrieving the panel's represented Setting value, and for applying a Setting value to itself.

Examples of a panel that contains a text field:

Get = function(panel) return panel.TextField:GetValue() end,
Set = function(panel, str) panel.TextField:SetValue(str) end

Get is called when the panel calls Send() and uses this value to network to the server (using NetSend if defined, otherwise default based on Type).

Set is called when networking is received (through NetRead if defined, otherwise default based on Type), and is meant to update the panel so that it is always up to date with the current settings.

Making a Settings Panel

To get your settings to show up on your Extension's panel in the Config Settings tab, you need to define the function that is returned second on the Client (PanelFunction in the template). This function should create the panel that will be added into your Extension's panel.

You have access to the function SettingPanel only within this function. SettingPanel takes a single argument, the name of the setting you are getting the panel for, and returns a panel based on that setting's Type (or CustomPanel if defined). This panel is fully self-networking and will also update itself whenever someone else changes its value. Position, size, stylize, and modify this panel however you see fit onto the main panel you will return. Do this for each setting, and you have your completed Settings Panel. Feel free to add your own small things like text blocks, images, colors, or other panel types that you want on your Settings Panel.

Templates coming later