Settings

SettingsGameTemplate

SettingsGameTemplate

Handled for you: The engine initializes settings, binds dialog definitions discovered on the game, applies voted settings, tracks team configuration, exposes leader-only runtime updates, and invalidates typed config caches.

Use it for: Games with pre-game configuration, voting, presets, team selection, or runtime-adjustable knobs.

class LaserTagGame : SettingsGameTemplate() {
    override fun supportsTeamSelection(): Boolean = true
    override fun supportsTeamBasedVoting(): Boolean = supportsTeamSelection()

    override fun onSettingsFinalized() {
        gameRuntime.platform.logger().info("Settings finalized: $config")
    }
}

Use GameTemplate for fixed-rule games. Use SettingsGameTemplate when the game should participate in the settings flow before setup.

Dialog settings DSL

Define settings in a property named dialogSettings so the binder can discover it:

@Suppress("unused")
private val dialogSettings by lazy {
    dialogSettings {
        config {
            factory { LaserTagConfig.from(it) }

            option("game_mode", "Deathmatch", "Team Deathmatch", "Gun Game") {
                label = "<gold>Game Mode"
                default = "Deathmatch"
            }

            toggle("double_jump", default = true) {
                label = "<yellow>Double Jump"
                runtime = true
            }

            intSlider("respawn_seconds", default = 5, min = 2, max = 12, step = 1) {
                label = "<aqua>Respawn Time"
                format = "%s: %s seconds"
                runtime = true
            }

            text("arena_seed", default = "", maxLength = 32) {
                label = "<gray>Arena Seed"
                placeholder = "<dark_gray>Optional"
            }
        }
    }
}

Available shapes:

DSL	Stored type	Good for
toggle	"Enabled" / "Disabled"	Boolean feature flags.
option	String option	Modes, maps, item pools, finite choices.
floatSlider	Float string	Tunable rates and multipliers.
intSlider	Int-like string	Counts, timers, lives, limits.
doubleSlider	Double string	Precision tuning.
slider	Float descriptor	Ad-hoc slider fully configured in block.
text	String	Seeds, labels, short prompts.

Convenience builders include intChoices, durationMinutes, intervalChoices, durationOrNever, enabledDisabled, yesNo, and secondsSlider.

Typed config

The factory turns the current string map into your own typed data class:

data class LaserTagConfig(
    val doubleJumpEnabled: Boolean,
    val respawnSeconds: Int,
) {
    companion object {
        fun from(game: SettingsGameTemplate) =
            LaserTagConfig(
                doubleJumpEnabled = game.settingBool("double_jump", default = true),
                respawnSeconds = game.settingInt("respawn_seconds", default = 5),
            )
    }
}

private val config: LaserTagConfig
    get() = gameConfig()

gameConfig() caches the result and invalidates when runtime settings change.

Descriptors and presets

Settings descriptors parse and serialize values consistently. Presets can use raw keys or descriptors:

private val dialogSettings by lazy {
    dialogSettings {
        config {
            val lives = intSlider("lives", default = 3, min = 1, max = 10) {
                label = "<red>Lives"
            }
            factory { BattleConfig.from(it) }
        }
        presets {
            preset("quick", "<green>Quick") {
                "lives"(1)
            }
        }
    }
}

Preset values are serialized

PresetValuesScope runs values through the descriptor registry when possible. This keeps toggles, sliders, and options in the same format as dialog responses.

Runtime settings

Mark a setting runtime = true if the leader may change it during the match:

override fun onRuntimeSettingChanged(
    name: String,
    oldValue: String,
    newValue: String,
    by: GamePlayer?,
) {
    if (name == "double_jump") {
        reconfigureDoubleJump()
    }
}

updateRuntimeSetting(player, name, newValue) checks that the setting exists, the value is valid, the player is allowed, and the value changed. By default only the leader may update runtime settings.

Teams

Team helpers are built into SettingsGameTemplate:

supportsTeamSelection()
getTeams()
playersInTeams()
isTeamBasedVoting()
getPlayerTeam(player)
getPlayerTeamIndex(player)

Use them for friendly-fire checks, team scoring, spawn assignment, and team-based voting behavior.