playersettings
==============

This mod provides a GUI (via unified_inventory) that allows players to change various per-player settings.
No settings are actually included, but other mods can provide their own.

To register a setting:

playersettings.register("yourmodname:yoursettingname",{

	type = "number",
	-- Specifies the type of the setting to register.
	-- Valid types are:
	---- "number": An integer or floating-point value.
	---- "string": A text string.
	---- "boolean": A simple yes/no checkbox.
	---- "enum": A list of possible choices.
	
	shortdesc = "Short Description",
	-- A short (human-readable) description of the setting, to be shown as the setting name in the menu.
	
	longdesc = "Long Description Goes Here",
	-- A longer desciption that is shown when the user selects your setting in the menu.
	
	default = 5,
	-- The default value of the setting.
	
	min = 0,
	-- For "number" settings: The smallest selectable value.
	
	max = 10,
	-- For "number" settings: The largest selectable value.
	-- For "string" settings: Maximum length. Default: 200.
	
	integer = true,
	-- For "number" settings: If true, entered numbers will be rounded down to the nearest integer.
	
	values = "some text here",
	-- For "string" settings: Text to be displayed under the entry field to assist the user in selecting valid values.
	
	values = {"Apple", "Orange", "Banana"},
	-- For "enum" settings: A list of the possible choices.
	
	onjoin = function(player_name,setting_value),
	-- A function to be called whenever a player joins the game.
	-- 'player_name' is the name of the player that just joined.
	-- 'setting_value' is the current value of the setting.
	
	onchange = function(player_name,old_value,new_value)
	-- A function to be called when a player tries to change the setting, before the setting is actually changed.
	-- Custom validation logic should go here.
	-- 'player_name' is the name of the player trying to change the setting.
	-- 'old_value' is the current value of the setting.
	-- 'new_value' is the value the player wants to change the setting to.
	-- Return true to allow the change to take place, or false (or nothing at all) to prevent the change.
	
	afterchange = function(player_name,old_value,new_value)
	-- A function to be called after the setting is changed.
	-- Code to apply the new value of the setting should go here.
	-- 'player_name' is the name of the player that changed the setting.
	-- 'old_value' is the old value of the setting, before it was changed.
	-- 'new_value' is the value that the setting was changed to.
})

To set a setting (from another mod):

playersettings.set(player_name,setting_name,new_value)
-- 'player_name' is the player to change the setting for.
-- 'setting_name' is the name of the setting to change.
-- 'new_value' is the new value of the setting.
-- Changing settings via this interface bypasses the built-in validation (such as range checking on numbers) but NOT any specified onchange or afterchange actions.

To reset a setting:

playersettings.reset(player_name,setting_name)
-- 'player_name' is the player to change the setting for.
-- 'setting_name' is the name of the setting to reset/clear.
-- This will cause 'playersettings.get' to fall back to the default value.

To get the value of a setting (from another mod):

playersettings.get(player_name,setting_name)
-- 'player_name' is the player to get the setting value from.
-- 'setting_name' is the name of the setting to get.
