Native Settings

A small mod for Cyberpunk 2077 that allows other mods to easily add settings options to a custom, fully native UI Mods settings menu. User-friendly and fully controller compatible.

How to use:

1. CET Version 1.18.1+ is required
2. Add this mod to your mod's requirement list: Nexus page
3. Import it into your mod:

   nativeSettings = GetMod("nativeSettings")

Add a new tab:

• Multiple mods can share the same tab
• path should be a / followed by a simple keyword
• label is what will be displayed
• callbackFunction is an optional function parameter that gets called when the tab gets closed

   nativeSettings.addTab("/myMod", "My mod", callbackFunction()) -- Add a tab (path, label, callback)

Add a new subcategory:

• Use subcategories to organize options
• path should be your mods tab path (e.g. /myMod), followed by a /, followed by a simple keyword.
• label is what will be displayed
• optionalIndex is an optional int parameter to control the position of the subcategory (Default is same order as addSubcategory's get called)

   nativeSettings.addSubcategory("/myMod/sub", "A subcategory") -- Add a subcategory (path, label, optionalIndex)

Adding option widgets:

• All option widgets can be added to either a tab directly (Provide the tab path), or a tab's subcategory (Provide full path)

Parameters every widget has:

• path : Where the widget goes, e.g. /myMod or /myMod/sub
• label : What gets displayed to the left of the widget
• desc : A description of what the option does, gets displayed when hovered over
• currentValue : This is what the option's initial value (Type depends on the widget) is. Usually, this value would get read from a settings file / database insideonInit
• defaultValue : This is what the option's default value should be, gets set when the Defaults button is hit
• callback : Here, you pass a function f(value) that gets called when the options gets changed. It gets called with a single parameter, the updated value
• optionalIndex : Optional index parameter that can be used to control the order of the options (Default is same order as the addOption's get called)

Toggle:

• This adds a basic true/false switch
• Datatype is boolean

   -- Parameters: path, label, desc, currentValue, defaultValue, callback, optionalIndex
  
   nativeSettings.addSwitch("/myMod/sub", "Switch", "Description", true, true, function(state)
   	print("Changed SWITCH to ", state)
   	-- Add any logic you need in here, such as saving the changes to file / database
   end)

Slider Int:

• This adds a slider, that can only get set to whole numbers
• Datatype is int
• min : This is the minimum value of the slider
• max : This is the maximum value of the slider
• step : This is the minimum amount the slider can move

   -- Parameters: path, label, desc, min, max, step, currentValue, defaultValue, callback, optionalIndex
  
   nativeSettings.addRangeInt("/myMod/sub", "Slider Int", "Description", 1, 100, 1, 50, 25, function(value)
   	print("Changed SLIDER INT to ", value)
   	-- Add any logic you need in here, such as saving the changes to file / database
   end)

Slider Float:

• This adds a slider, that can be set to any value
• Datatype is float (int also works)
• min : This is the minimum value of the slider
• max : This is the maximum value of the slider
• step : This is the minimum amount the slider can move
• format : This is a format string, to control how the value gets displayed (Works the same as lua's string.format())

   -- Parameters: path, label, desc, min, max, step, format, currentValue, defaultValue, callback, optionalIndex
  
   nativeSettings.addRangeFloat("/myMod/sub", "Slider Float", "Description", 1, 100, 0.25, "%.2f", 50, 1, function(value)
   	print("Changed SLIDER FLOAT to ", value)
   	-- Add any logic you need in here, such as saving the changes to file / database
   end)

String List:

• This adds a list of strings, that can be chosen of
• Datatype is table
• The table must be numerical indexed
• currentValue / defaultValue is the index of the selected element

   -- Parameters: path, label, desc, elements, currentValue, defaultValue, callback, optionalIndex
  
   local  list = {[1] = "Option 1", [2] = "Option 2", [3] = "Option 3", [4] = "Option 4"} -- Create list of options, with numeric index
  
   nativeSettings.addSelectorString("/myMod/sub", "String List", "Description", list, 1, 3, function(value)
   	print("Changed LIST STRING to ", list[value])
   	-- Add any logic you need in here, such as saving the changes to file / database
   end)

Keybind:

• This adds a keybind widget, that can be clicked on to store any pressed key
• Datatype is string
• When pressed, it will return the keycode e.g IK_X of the pressed key
• currentKey and defaultKey needs to be a valid keycode
• isHold determines whether or not the key icon has a "Hold" outline
• The actual reading of raw inputs has to be done via Codeware, for examples on how to implement this using CET, including a simple module for setting up multikey bindings, check the provided example in this repo
• Controller bindings are supported too, but require Codeware to work (Required for actually reading inputs anyways), for an example on how to forward the input events from Codeware to Native Settings check the provided examples

   -- Parameters: path, label, desc, currentKey, defaultKey, isHold, callback, optionalIndex
  
   nativeSettings.addKeyBinding("/myMod/sub", "Keybind", "Description", "IK_1", "IK_5", false, function(key)
   	print("Changed KEYBIND to", key)
   	-- Add any logic you need in here, such as saving the changes to file / database
   end)

Button:

• This adds a simple, interactable button which calls the callback function without any parameters when clicked
• Has no currentValue and defaultValue parameters
• buttonText is the text that gets displayed inside the button
• textSize is the size of the buttonText text

   -- Parameters: path, label, desc, buttonText, textSize, callback, optionalIndex
  
   nativeSettings.addButton("/myMod/sub", "Button", "Description", "Button label", 45, function()
   	print("User clicked BUTTON")
   	-- Add any logic you need in here, such as calling a function from your mod
   end)

Custom Widget:

• This is not a typical widget, i.e. it does not have any visible UI
• It can be used to get a reference to the settings screen's main inkCompoundWidget
• With this reference you can add your own custom widgets to the settings page, such as the Furigana mod is doing
• inkCompoundWidget is the SettingsMainGameController's settingsOptionsList widget

-- Parameters: path, callback, optionalIndex

	nativeSettings.addCustom("/myMod/sub", function(inkCompoundWidget)
		-- Add any logic you need in here, such as adding custom UI to the inkCompoundWidget
	end)

Removing options / subcategories:

• Option widgets as well as subcategories can be added or removed while the UI is active
• Use this in combination with the optionalIndex parameter of any addOption function to add and remove options where they are needed

Options:

• optionTable is what gets returned by any addOption function (switch/int/float/list/button)

   -- Parameters: optionTable
   nativeSettings.removeOption(optionTable)

Subcategories:

• path is the full path to the subcategory you want to remove

   -- Parameters: path
   nativeSettings.removeSubcategory("/myMod/sub")

Custom Restore Defaults:

• A custom callback function can be registered for a tab, and optionally the normal restore default actions can be overridden

   -- Parameters: path, overrideNativeRestoreDefaults, callback
  
   nativeSettings.registerRestoreDefaultsCallback("/myMod", true, function()
   	-- Handle restoring defaults with your own logic
   end)

The refresh function:

• Calling this function is not necessary anymore, as of version 1.4
• Refreshes the UI when active, to reflect changes made by adding (e.g. addSwitch) or removing (e.g. removeOption) option widgets or entire subcategories
• When adding or removing multiple option widgets or subcategories at once, make sure to only call refresh once, after all adding / removing operations are done

   nativeSettings.refresh()

The setOption function:

• The nativeSettings mod only gets the settings values at the startup in form of the currentValue
• If you modify any settings / options from e.g. a secondary ImGui settings window, the values displayed by nativeSettings will be out of sync
• Use the setOption(optionTable, value) function if you change an option from outside the nativeSettings window, to make sure everything stays synced
• optionTable is what gets returned by any addOption function (switch/int/float/list)
• value is the value you want to set
• Example:

   local settingsTables = {} -- An empty table to store the return from the addOption functions, in case we want to use setOption() or removeOption(), can be ignored otherwise
   local switchState = false -- Would usually get loaded from a config file / database
   local nativeSettings
  
   registerForEvent("onInit", function()
   	nativeSettings = GetMod("nativeSettings") -- Get a reference to the nativeSettings mod
  
   	if not nativeSettings then -- Make sure the mod is installed
   		print("Error: NativeSettings not found!")
   		return
   	end
  
   	nativeSettings.addTab("/myMod", "My mod") -- Add our mods tab (path, label)
   	nativeSettings.addSubcategory("/myMod/sub", "A subcategory") -- Optional: Add a subcategory (path, label), you can add as many as you want
  
   	settingsTables["switch"] = nativeSettings.addSwitch("/myMod/sub", "Switch", "Description", switchState, true, function(state) -- Setup a switch, and store its returned table
   		print("Changed SWITCH to ", state)
   		switchState = state
   	end)
   end)
  
   registerForEvent("onDraw", function()
   	if ImGui.Begin("Alternative Settings Window", ImGuiWindowFlags.AlwaysAutoResize) then
   		switchState, changed = ImGui.Checkbox("Switch", switchState)
   		if changed then -- We changed the option value from somewhere else
   			nativeSettings.setOption(settingsTables["switch"], switchState) -- Update the value for the nativeSettings mod
   		end
   	end
   	ImGui.End()
   end)

Credits:

• psiberx for answering all my questions, as well as doing a lot of work on CET that makes this mod even work and creating Cron.lua, UIButton.lua, Ref.lua and EventProxy.lua.
• RMK for adding the keybind widget, making proper handling for adding and removing elements and generally helping with bugfixing
• dkollmann for adding the "custom" widget type and implementing the optional callback for tabs
• nim for hating ImGui