Konado Settings API Documentation

Settings Manager (KonadoSettings)

The settings manager is an autoloaded singleton that manages all setting items.

Signal

setting_changed(category: String, key: String, value: Variant)

• Description: Emitted when a setting value changes.
• Parameters:
  • category: Setting category.
  • key: Key of the setting item.
  • value: New setting value.

Methods

get_setting(category: String, key: String) -> Variant

• Description: Gets the current value of a setting.
• Parameters:
  • category: Setting category.
  • key: Key of the setting item.
• Return value: The setting value. If it does not exist, returns the default value or null.

set_setting(category: String, key: String, value: Variant) -> bool

• Description: Validates and persists a setting, then emits the change signal on success.
• Parameters:
  • category: Setting category.
  • key: Key of the setting item.
  • value: New setting value.
• Return value: true when validation and persistence both succeed; otherwise false.

register_category(cat: KonadoSettingCategory) -> void

• Description: Registers an additional setting category at runtime.
• Parameters:
  • cat: The setting category to register.

reset_category(category_id: String) -> bool

• Description: Resets all settings in the specified category with a single save operation.
• Parameters:
  • category_id: Category ID.
• Return value: true when the reset succeeds; otherwise false.

get_categories() -> Array

• Description: Gets all registered categories, filtered for the current platform.
• Return value: The filtered category array.

get_category(id: String) -> KonadoSettingCategory

• Description: Gets a single category by ID, filtered for the current platform.
• Parameters:
  • id: Category ID.
• Return value: The filtered category object.

Setting Category (KonadoSettingCategory)

A setting category groups related setting items together.

Properties

• id: String: Unique identifier of the category.
• display_name: String: Display name of the category.
• items: Array[KonadoSettingItem]: Array of setting items contained in the category.

Example

var video_cat = KonadoSettingCategory.new()
video_cat.id = "video"
video_cat.display_name = "Video"

# Add setting item
video_cat.items.append(resolution_item)

# Register category
KonadoSettings.register_category(video_cat)

Setting Item (KonadoSettingItem)

A setting item is a single configurable unit.

Enum

Type

• SLIDER (0): Slider type, used for numeric adjustment.
• TOGGLE (1): Toggle type, used for boolean values.
• OPTION (2): Option type, used for drop-down selection.

Properties

• key: String: Unique identifier of the setting item.
• label: String: Display label of the setting item.
• type: Type: Type of the setting item.
• min_value: float: Minimum slider value, only for SLIDER items.
• max_value: float: Maximum slider value, only for SLIDER items.
• step: float: Slider step, only for SLIDER items.
• options: Array[String]: Option list, only for OPTION items.
• platforms: Array[String]: Platform filter. An empty array means visible on all platforms.
• default_value: Variant: Default value. SLIDER uses float, TOGGLE uses bool, and OPTION uses String.

Examples

Create a Slider Setting Item

var volume_item = KonadoSettingItem.new()
volume_item.key = "master_volume"
volume_item.label = "Master Volume"
volume_item.type = KonadoSettingItem.Type.SLIDER
volume_item.min_value = 0.0
volume_item.max_value = 1.0
volume_item.step = 0.01
volume_item.default_value = 1.0
volume_item.platforms = ["all"]

Create a Toggle Setting Item

var fullscreen_item = KonadoSettingItem.new()
fullscreen_item.key = "fullscreen"
fullscreen_item.label = "Fullscreen"
fullscreen_item.type = KonadoSettingItem.Type.TOGGLE
fullscreen_item.default_value = false

Create an Option Setting Item

var language_item = KonadoSettingItem.new()
language_item.key = "language"
language_item.label = "Language"
language_item.type = KonadoSettingItem.Type.OPTION
language_item.options = ["zh", "tc", "en", "ja", "ko"]
language_item.default_value = "zh"

UI Factory (UIFactory)

The UI factory creates controls for setting items.

Method

create_control(cat_id: String, item: KonadoSettingItem, callback: Callable) -> HBoxContainer

• Description: Creates and returns a row (HBoxContainer) for the given setting item.
• Parameters:
  • cat_id: Category ID.
  • item: Setting item.
  • callback: Callback function in the format callback(category_id: String, key: String, value: Variant).
• Return value: The created HBoxContainer.

Example

var row = UIFactory.create_control("audio", volume_item, func(category, key, value):
	print("Setting changed: %s/%s = %s" % [category, key, value])
	KonadoSettings.set_setting(category, key, value)
)

# Add to container
vbox_container.add_child(row)

Settings Panel (SettingsPanel)

The settings panel is a visual interface for displaying and managing settings.

Properties

• _tab_container: TabContainer: Tab container used to display settings from different categories.
• btn_reset: Button: Restore defaults button.
• btn_close: Button: Close button.

Method

rebuild() -> void

• Description: Rebuilds the UI. Useful after registering a new category.

Signals

• btn_reset.pressed: Emitted when the restore defaults button is clicked.
• btn_close.pressed: Emitted when the close button is clicked.

Example

# Load the settings panel scene
var settings_panel = preload("res://addons/konado_settings/ui/konado_settings_panel.tscn").instantiate()
add_child(settings_panel)

# Show the settings panel
settings_panel.show()

# Rebuild the panel after registering a new category
KonadoSettings.register_category(new_category)
settings_panel.rebuild()

Platform Detection

The settings system automatically detects the current runtime platform and filters displayed items according to each setting item's platforms property.

Platform Identifiers

• all - All platforms
• android - Android
• bsd - BSD
• linux - Linux
• macos - macOS
• ios - iOS
• visionos - visionOS
• windows - Windows
• linuxbsd - Linux or BSD
• debug - Debug build
• release - Release build
• editor - Editor build

Platform Detection Logic

1. First checks whether the game is running in the editor.
2. Uses OS.has_feature() to detect the specific platform.
3. Sets the current platform identifier based on the detection result.
4. Filters setting items by platform when categories are retrieved.

Persistent Storage

Setting values are automatically saved to user://konado_settings.cfg using Godot's ConfigFile format.

Save Timing

• When set_setting() is called.
• Setting values are automatically written to the configuration file.

Load Timing

• When the plugin is initialized.
• Saved setting values are automatically loaded from the configuration file.

Complete Usage Examples

1. Basic Usage

# Get a setting value
var master_volume = KonadoSettings.get_setting("audio", "master_volume")

# Set a value
KonadoSettings.set_setting("audio", "master_volume", 0.8)

# Listen for setting changes
KonadoSettings.setting_changed.connect(func(category, key, value):
	if category == "audio" and key == "master_volume":
		# Handle volume changes
		AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), linear_to_db(value))
)

2. Register New Settings at Runtime

# Create a new setting category
var video_cat = KonadoSettingCategory.new()
video_cat.id = "video"
video_cat.display_name = "Video"

# Create setting item
var resolution_item = KonadoSettingItem.new()
resolution_item.key = "resolution"
resolution_item.label = "Resolution"
resolution_item.type = KonadoSettingItem.Type.OPTION
resolution_item.options = ["1280x720", "1920x1080", "2560x1440"]
resolution_item.default_value = "1920x1080"

# Add to category
video_cat.items.append(resolution_item)

# Register category
KonadoSettings.register_category(video_cat)

# Rebuild the settings panel if it is already visible
if settings_panel:
	settings_panel.rebuild()

3. Custom Settings Panel

# Create a custom settings panel
var panel = CanvasLayer.new()

# Create tab container
var tab_container = TabContainer.new()
tab_container.size_flags_horizontal = Control.SIZE_EXPAND_FILL
tab_container.size_flags_vertical = Control.SIZE_EXPAND_FILL
panel.add_child(tab_container)

# Build settings UI
var mgr = KonadoSettings
for cat in mgr.get_categories():
	var scroll = ScrollContainer.new()
	scroll.name = cat.display_name
	scroll.size_flags_vertical = Control.SIZE_EXPAND_FILL

	var vbox = VBoxContainer.new()
	vbox.size_flags_horizontal = Control.SIZE_EXPAND_FILL
	scroll.add_child(vbox)

	for item in cat.items:
		var row = UIFactory.create_control(cat.id, item, func(cat_id, key, value):
			mgr.set_setting(cat_id, key, value)
		)
		vbox.add_child(row)

	tab_container.add_child(scroll)

# Add to scene
add_child(panel)

Notes

• All API calls should be made after the game has started.
• After registering a new category, call rebuild() to update the settings panel.
• Platform filtering only affects whether setting items are displayed. It does not affect storage of setting values.
• Each setting item's key must be unique within its category.
• For OPTION items, the default value must exist in the options list.

Error Handling

• If a setting item does not exist, get_setting() returns null and emits a warning.
• If the configuration file format is invalid, a warning is emitted and default values are used.
• If platform detection fails, the platform defaults to all.

Performance Considerations

• The settings system uses lazy loading and parses the configuration file only when needed.
• Platform filtering is performed when categories are retrieved and does not affect setting value access performance.
• UI creation is on demand. Controls are created only when the settings panel is displayed.

Extension Suggestions

1. Add a new setting type:

   • Add a new enum value to KonadoSettingItem.Type.
   • Add the corresponding creation logic in UIFactory.

2. Customize the storage method:

   • Modify _load_saved() and set_setting() in settings_manager.gd.
   • Implement custom save and load logic.

3. Extend setting validation:

   • Extend _validate_value() for custom setting types.
   • Built-in types already validate numeric ranges, Boolean values, and option membership.

4. Add internationalization support:

   • Modify how display_name and label are processed.
   • Support multilingual settings interfaces.