Modding/Templates/Map Settings

This mod template adds two rows to the "Custom Game Settings" menu when starting a new game. The two settings can also be changed while in-game. To keep the example short, only percentage sliders are added but you can modify the code to add any kind of UI element. See the file data/map_settings.lua of the base game for more utility functions similar to the AddSlider function included in this example.

This example adds the keys mymod_foo and mymod_bar to the settings table. Make sure to use a prefix of some sort to make the keys unique to your mod to avoid conflicts with other mods or the base game.

Code

def.json

Content

{
    "id": "ModTemplateMapSettings",
    "name": "Mod Template Map Settings",
    "version_name": "1.0",
    "version_code": 1,
    "author": "The Desynced Team",
    "homepage": "https://www.desyncedgame.com/",
    "description": "Mod Template Map Settings",
    "packages": {
        "MyMapSettings": {
            "name": "Map Settings",
            "entry": "entry.lua",
            "map_settings": "map_settings.lua",
            "type": "Addon"
        }
    }
}

map_settings.lua

Content

local function AddSlider(list, text, tooltip, min, max, step, value)
	local hl = list:Add("<HorizontalList child_align=center child_fill=true height=32><Text/><HorizontalList><Slider fill=true/><Text width=50 textalign=right/></HorizontalList></HorizontalList>")
	local lbl, sli, valtxt = hl[1], hl[2][1], hl[2][2]
	lbl.text, lbl.tooltip, sli.min, sli.max, sli.step, sli.value = text, tooltip, min, max, step, value
	sli.on_change = function(_,v) valtxt.text = string.format("%.0f%%", (v * 100)) end
	sli:on_change(value)
	return sli
end

return {
	FillInputList = function(settings, list, in_game)
		local val_foo = settings.mymod_foo or 5
		local val_bar = settings.mymod_bar or 0.3
		list.foo = AddSlider(list, "Foo Amount", "Tooltip", 0, 10, 1, val_foo)
		list.bar = AddSlider(list, "Bar Amount", "Tooltip", 0.1, 1.0, 0.1, val_bar)
	end,

	FillSettings = function(settings, list, in_game)
		settings.mymod_foo = list.foo.value
		settings.mymod_bar = list.bar.value
	end,

	FillInfoList = function(settings, list)
		local val_foo = settings.mymod_foo or 5
		local val_bar = settings.mymod_bar or 0.3
		list:Add('<Canvas><Text text="Foo Amount"/><Text text={val} color=ui_light halign=right/></Canvas>').val = string.format("%.0f%%", (val_foo * 100))
		list:Add('<Canvas><Text text="Bar Amount"/><Text text={val} color=ui_light halign=right/></Canvas>').val = string.format("%.0f%%", (val_bar * 100))
	end,
}

entry.lua

Content

local package = ...

function MapMsg.OnSettingChanged(key_name, old_value, new_value)
	local notify_name, notify_value
	if key_name == 'mymod_foo' then
		notify_name, notify_value = "Foo Amount", string.format("%.0f%%", (new_value * 100))
		-- Perhaps do other stuff when foo changed in-game
	elseif key_name == 'mymod_bar' then
		notify_name, notify_value = "Bar Amount", string.format("%.0f%%", (new_value * 100))
		-- Perhaps do other stuff when bar changed in-game
	end
	if notify_name then
		UI.Run(function()
			if Game.IsHostPlayer() then return end
			Notification.Add("mapsettings_" .. key_name, "info", "Game Settings", L("%s was changed to %s", notify_name, notify_value))
		end)
	end
end