layout_manager.gd

Go to the documentation of this file.

extends RefCounted
 
 
 
const PHONE_WIDTH := 600
const TABLET_WIDTH := 1000
 
const DENSITY_PRESETS := {
    "compact": {"margin": 8, "gap": 6, "button_height": 44, "font_size": 14},
    "comfortable": {"margin": 14, "gap": 10, "button_height": 54, "font_size": 16},
    "spacious": {"margin": 22, "gap": 14, "button_height": 62, "font_size": 18}
}
 
const BREAKPOINT_DENSITIES := {
    "phone": "compact",
    "tablet": "comfortable",
    "desktop": "spacious"
}
 
const THEME_PRESETS := {
    "dark": {
        "name": "Midnight",
        "background": "#111820",
        "surface": "#1a222b",
        "surface_alt": "#202a34",
        "panel": "#1a222b",
        "panel_alt": "#202a34",
        "button": "#202a34",
        "button_hover": "#273442",
        "button_pressed": "#18202a",
        "button_disabled": "#161d25",
        "border": "#33404d",
        "text": "#eef3f8",
        "muted": "#aab6c4",
        "accent": "#f2c86b",
        "positive": "#55d17a",
        "negative": "#ef5f68",
        "warning": "#ffd166"
    }
}
 
const DEFAULT_STYLE_TARGETS := {
    "screen": {"background_image": "", "texture_mode": "stretch", "opacity": 1.0},
    "panel": {"background_image": "", "texture_mode": "stretch", "opacity": 1.0},
    "button": {"background_image": "", "texture_mode": "stretch", "opacity": 1.0}
}
const THEME_COLOR_KEYS := [
    "background",
    "surface",
    "surface_alt",
    "panel",
    "panel_alt",
    "button",
    "button_hover",
    "button_pressed",
    "button_disabled",
    "border",
    "text",
    "muted",
    "accent",
    "positive",
    "negative",
    "warning"
]
const CUSTOM_THEME_CATALOG_PATH := "user://custom_themes.json"
 
var theme_presets := THEME_PRESETS.duplicate(true)
var density_presets := DENSITY_PRESETS.duplicate(true)
var sprite_manager = preload("res://scripts/systems/spriteManager/sprite_manager.gd").new()
var sprites_loaded := false
var style_cache := {}
var style_cache_hits:int = 0
var style_cache_misses:int = 0
 
 
 
func load_theme_file(file_path:String) -> void:
    clear_style_cache()
    for catalog_path in _theme_catalog_paths(file_path):
        var file = FileAccess.open(catalog_path, FileAccess.READ)
        if file == null:
            continue
        var data = JSON.parse_string(file.get_as_text())
        if not data is Dictionary:
            continue
        for key in data.get("themes", {}).keys():
            theme_presets[key] = _normalize_theme_definition(data["themes"][key])
        for key in data.get("densities", {}).keys():
            density_presets[key] = data["densities"][key]
 
 
 
func get_layout_mode(viewport_size:Vector2) -> String:
    return "mobile" if viewport_size.x <= PHONE_WIDTH else "desktop"
 
 
 
func get_breakpoint(viewport_size:Vector2) -> String:
    if viewport_size.x <= PHONE_WIDTH:
        return "phone"
    if viewport_size.x <= TABLET_WIDTH:
        return "tablet"
    return "desktop"
 
 
 
func get_density_preset(name:String = "comfortable", viewport_size:Vector2 = Vector2.ZERO) -> Dictionary:
    var preset_name = name
    if viewport_size != Vector2.ZERO:
        preset_name = BREAKPOINT_DENSITIES.get(get_breakpoint(viewport_size), name)
    return density_presets.get(preset_name, density_presets["comfortable"]).duplicate(true)
 
 
 
func get_theme_colors(name:String = "dark") -> Dictionary:
    var source = _normalize_theme_definition(theme_presets.get(name, theme_presets["dark"]))
    var fallback = _normalize_theme_definition(THEME_PRESETS["dark"])
    var colors := {}
    for key in THEME_COLOR_KEYS:
        colors[key] = _coerce_theme_color(source.get(key, fallback.get(key, "#ffffff")), _coerce_theme_color(fallback.get(key, "#ffffff"), Color.WHITE))
    for key in source.keys():
        if colors.has(key) or key == "name" or key == "description" or key == "typography" or key == "styles":
            continue
        if _is_color_like(source[key]):
            colors[key] = _coerce_theme_color(source[key], Color.WHITE)
    return colors
 
 
 
func get_theme_catalog() -> Dictionary:
    var catalog := {}
    for theme_id in theme_presets.keys():
        var definition = _normalize_theme_definition(theme_presets[theme_id])
        catalog[theme_id] = {
            "id": theme_id,
            "name": str(definition.get("name", str(theme_id).capitalize())),
            "description": str(definition.get("description", "")),
            "colors": get_theme_colors(theme_id),
            "typography": definition.get("typography", {}),
            "styles": get_theme_styles(theme_id)
        }
    return catalog
 
 
 
func get_theme_styles(name:String = "dark") -> Dictionary:
    var source = _normalize_theme_definition(theme_presets.get(name, theme_presets["dark"]))
    var styles = source.get("styles", DEFAULT_STYLE_TARGETS)
    if not styles is Dictionary:
        return DEFAULT_STYLE_TARGETS.duplicate(true)
    return _merge_dict(DEFAULT_STYLE_TARGETS, styles)
 
 
 
func get_custom_draw_palette(name:String = "dark", domain:String = "generic") -> Dictionary:
    var colors = get_theme_colors(name)
    match domain:
        "reflecting_pool":
            return {
                "background": colors.get("background", Color("#213122")).lerp(Color("#2f4a30"), 0.35),
                "lawn": colors.get("surface", Color("#2f4a30")).lerp(Color("#3f653f"), 0.45),
                "far_lawn": colors.get("surface_alt", Color("#2b442d")).lerp(Color("#335536"), 0.35),
                "path": colors.get("accent", Color("#c8b997")).lerp(Color("#c8b997"), 0.62),
                "stone": colors.get("text", Color("#e8e1d1")).lerp(Color("#d7d0c2"), 0.32),
                "muted_stone": colors.get("muted", Color("#b9ad99")).lerp(Color("#b9ad99"), 0.5),
                "water_border": colors.get("border", Color("#6c8a9b")).lerp(Color("#6c8a9b"), 0.45)
            }
    return colors
 
 
 
func make_panel_style(theme_name:String = "dark", density_name:String = "comfortable") -> StyleBoxFlat:
    var cache_key := "panel|%s|%s" % [theme_name, density_name]
    if style_cache.has(cache_key):
        style_cache_hits += 1
        return style_cache[cache_key]
    style_cache_misses += 1
    var colors = get_theme_colors(theme_name)
    var density = get_density_preset(density_name)
    var style = StyleBoxFlat.new()
    style.bg_color = colors.get("panel", colors.get("surface", Color("#1a222b")))
    style.border_color = colors["border"]
    style.set_border_width_all(1)
    style.set_corner_radius_all(8)
    style.content_margin_left = int(density["margin"])
    style.content_margin_right = int(density["margin"])
    style.content_margin_top = int(density["margin"])
    style.content_margin_bottom = int(density["margin"])
    style_cache[cache_key] = style
    return style
 
 
 
func make_button_style(theme_name:String = "dark", state:String = "normal") -> StyleBoxFlat:
    var cache_key := "button|%s|%s" % [theme_name, state]
    if style_cache.has(cache_key):
        style_cache_hits += 1
        return style_cache[cache_key]
    style_cache_misses += 1
    var colors = get_theme_colors(theme_name)
    var style = StyleBoxFlat.new()
    var bg_key = "button"
    match state:
        "hover":
            bg_key = "button_hover"
        "pressed":
            bg_key = "button_pressed"
        "disabled":
            bg_key = "button_disabled"
    style.bg_color = colors.get(bg_key, colors.get("surface_alt", colors["surface"]))
    style.border_color = colors["accent"] if state == "hover" or state == "pressed" else colors["border"]
    style.set_border_width_all(1)
    style.set_corner_radius_all(8)
    style.content_margin_left = 14
    style.content_margin_right = 14
    style.content_margin_top = 10
    style.content_margin_bottom = 10
    style_cache[cache_key] = style
    return style
 
 
 
func clear_style_cache() -> void:
    style_cache.clear()
    style_cache_hits = 0
    style_cache_misses = 0
 
 
 
func get_cache_stats() -> Dictionary:
    return {
        "styleboxes": style_cache.size(),
        "style_cache_hits": style_cache_hits,
        "style_cache_misses": style_cache_misses
    }
 
 
 
func apply_theme(root:Node, theme_name:String = "dark") -> void:
    if root == null:
        return
    var colors = get_theme_colors(theme_name)
    _apply_theme_recursive(root, theme_name, colors)
 
 
 
func apply_screen_background(root:Control, theme_name:String = "dark") -> void:
    _apply_style_target(root, "screen", get_theme_styles(theme_name))
 
 
 
func apply_density(control:Control, density_name:String = "comfortable") -> void:
    var density = get_density_preset(density_name)
    if control is BoxContainer:
        control.add_theme_constant_override("separation", int(density["gap"]))
    if control is Button:
        control.custom_minimum_size.y = int(density["button_height"])
        control.add_theme_font_size_override("font_size", int(density["font_size"]))
 
 
 
func apply_responsive_shell(root:Control, viewport_size:Vector2) -> void:
    var density_name = BREAKPOINT_DENSITIES.get(get_breakpoint(viewport_size), "comfortable")
    var density = get_density_preset(density_name)
    root.offset_left = int(density["margin"])
    root.offset_top = int(density["margin"])
    root.offset_right = -int(density["margin"])
    root.offset_bottom = -int(density["margin"])
    _apply_density_recursive(root, density_name)
 
 
 
func create_screen_shell(name:String = "ScreenShell", options:Dictionary = {}) -> VBoxContainer:
    var shell = VBoxContainer.new()
    shell.name = name
    shell.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    shell.size_flags_vertical = Control.SIZE_EXPAND_FILL
    var header = HBoxContainer.new()
    header.name = "Header"
    header.custom_minimum_size = Vector2(0, int(options.get("header_height", 54)))
    shell.add_child(header)
    var body = create_scroll_shell("Body")
    body.size_flags_vertical = Control.SIZE_EXPAND_FILL
    shell.add_child(body)
    var nav = HBoxContainer.new()
    nav.name = "Navigation"
    nav.custom_minimum_size = Vector2(0, int(options.get("nav_height", 58)))
    if bool(options.get("show_navigation", true)):
        shell.add_child(nav)
    return shell
 
 
 
func apply_full_rect(control:Control, margin:int = 0) -> void:
    control.set_anchors_preset(Control.PRESET_FULL_RECT)
    control.offset_left = margin
    control.offset_top = margin
    control.offset_right = -margin
    control.offset_bottom = -margin
 
 
 
func fit_popup_to_viewport(popup:PopupPanel, viewport_size:Vector2, options:Dictionary = {}) -> Vector2i:
    if popup == null:
        return Vector2i.ZERO
    var requested = _coerce_size(options.get("size", popup.size), Vector2i(360, 420))
    var margin := int(options.get("margin", 24))
    var minimum = _coerce_size(options.get("minimum", Vector2i(280, 180)), Vector2i(280, 180))
    var popup_size = popup_size_for_viewport(viewport_size, requested, minimum, margin)
    popup.min_size = Vector2i(min(minimum.x, popup_size.x), min(minimum.y, popup_size.y))
    popup.size = popup_size
    var content = popup.get_node_or_null("Content")
    if content is Control:
        apply_full_rect(content, int(options.get("content_margin", 14)))
        content.size_flags_horizontal = Control.SIZE_EXPAND_FILL
        content.size_flags_vertical = Control.SIZE_EXPAND_FILL
    return popup_size
 
 
 
func popup_size_for_viewport(viewport_size:Vector2, preferred:Vector2i = Vector2i(420, 560), minimum:Vector2i = Vector2i(280, 180), margin:int = 24) -> Vector2i:
    var available = Vector2i(max(1, int(viewport_size.x) - margin), max(1, int(viewport_size.y) - margin))
    var effective_min = Vector2i(min(minimum.x, available.x), min(minimum.y, available.y))
    return Vector2i(
        clamp(preferred.x, effective_min.x, available.x),
        clamp(preferred.y, effective_min.y, available.y)
    )
 
 
 
func popup_centered_standard(popup:PopupPanel, viewport_size:Vector2, options:Dictionary = {}) -> void:
    var popup_size = fit_popup_to_viewport(popup, viewport_size, options)
    if popup_size != Vector2i.ZERO:
        popup.size = popup_size
    if popup_size != Vector2i.ZERO and popup.is_inside_tree():
        popup.popup_centered(popup_size)
 
 
 
func create_panel_shell(name:String = "PanelShell") -> PanelContainer:
    var panel = PanelContainer.new()
    panel.name = name
    panel.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    panel.size_flags_vertical = Control.SIZE_EXPAND_FILL
    var content = VBoxContainer.new()
    content.name = "Content"
    content.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    content.size_flags_vertical = Control.SIZE_EXPAND_FILL
    panel.add_child(content)
    return panel
 
 
 
func create_scroll_shell(name:String = "ScrollShell") -> ScrollContainer:
    var scroll = ScrollContainer.new()
    scroll.name = name
    scroll.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    scroll.size_flags_vertical = Control.SIZE_EXPAND_FILL
    scroll.horizontal_scroll_mode = ScrollContainer.SCROLL_MODE_DISABLED
    var content = VBoxContainer.new()
    content.name = "Content"
    content.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    scroll.add_child(content)
    return scroll
 
 
 
func create_bottom_nav(items:Array) -> HBoxContainer:
    var nav = HBoxContainer.new()
    nav.name = "BottomNav"
    nav.custom_minimum_size = Vector2(0, 58)
    nav.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    for item in items:
        if not item is Dictionary:
            continue
        var button = Button.new()
        button.text = str(item.get("label", "Item"))
        _apply_button_icon(button, str(item.get("sprite_id", "")), 24)
        button.size_flags_horizontal = Control.SIZE_EXPAND_FILL
        button.custom_minimum_size = Vector2(0, 54)
        var callback = item.get("callback", Callable())
        if callback is Callable and callback.is_valid():
            button.pressed.connect(callback)
        nav.add_child(button)
    return nav
 
 
 
func create_save_slot_list(slots:Array, open_callback:Callable, delete_callback:Callable = Callable()) -> VBoxContainer:
    var list = VBoxContainer.new()
    list.name = "SaveSlotList"
    list.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    for slot in slots:
        if slot is Dictionary:
            list.add_child(create_save_slot_row(slot, open_callback, delete_callback))
    return list
 
 
 
func create_save_slot_row(slot:Dictionary, open_callback:Callable, delete_callback:Callable = Callable()) -> HBoxContainer:
    var row = HBoxContainer.new()
    row.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    row.add_theme_constant_override("separation", 8)
    var slot_button = Button.new()
    slot_button.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    slot_button.custom_minimum_size = Vector2(0, 76)
    slot_button.text = str(slot.get("display_label", "Slot %d" % int(slot.get("slot", 0))))
    _apply_button_icon(slot_button, "save", 26)
    if open_callback.is_valid():
        slot_button.pressed.connect(func(): open_callback.call(slot))
    row.add_child(slot_button)
    var delete_button = Button.new()
    delete_button.custom_minimum_size = Vector2(52, 76)
    delete_button.text = ""
    _apply_button_icon(delete_button, "trash", 22)
    delete_button.expand_icon = true
    delete_button.icon_alignment = HORIZONTAL_ALIGNMENT_CENTER
    delete_button.disabled = bool(slot.get("empty", false)) or not delete_callback.is_valid()
    if delete_callback.is_valid():
        delete_button.pressed.connect(func(): delete_callback.call(slot))
    row.add_child(delete_button)
    return row
 
 
 
func create_achievement_notification(achievement:Dictionary) -> PanelContainer:
    var panel = create_panel_shell("AchievementNotification")
    var content = panel.get_node("Content")
    var icon = _make_sprite_icon("achievement_star", 34)
    if icon != null:
        content.add_child(icon)
    var title = Label.new()
    title.name = "Title"
    title.text = "Achievement: %s" % str(achievement.get("name", achievement.get("id", "Unlocked")))
    content.add_child(title)
    var description = Label.new()
    description.name = "Description"
    description.text = str(achievement.get("description", ""))
    description.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
    content.add_child(description)
    return panel
 
 
 
func create_achievement_collection(achievements:Array, options:Dictionary = {}) -> ScrollContainer:
    var scroll = create_scroll_shell("AchievementCollection")
    scroll.custom_minimum_size = Vector2(0, 220)
    var content = scroll.get_node("Content")
    content.add_theme_constant_override("separation", 8)
    if bool(options.get("show_summary", true)):
        content.add_child(_create_achievement_summary(achievements))
    if achievements.is_empty():
        var empty = Label.new()
        empty.name = "Status"
        empty.text = "No achievements yet."
        empty.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER
        content.add_child(empty)
        return scroll
    for achievement in achievements:
        if not achievement is Dictionary:
            continue
        var row_height := int(options.get("row_height", 126))
        var row_button = Button.new()
        row_button.name = "Achievement_%s" % str(achievement.get("id", "row"))
        row_button.text = ""
        row_button.custom_minimum_size = Vector2(0, row_height)
        row_button.set_meta("max_font_size", 1)
        row_button.size_flags_horizontal = Control.SIZE_EXPAND_FILL
        row_button.focus_mode = Control.FOCUS_ALL
        row_button.add_theme_stylebox_override("normal", _achievement_row_style(Color("#1c2630"), Color("#33404d")))
        row_button.add_theme_stylebox_override("hover", _achievement_row_style(Color("#25313d"), Color("#f2c86b")))
        row_button.add_theme_stylebox_override("pressed", _achievement_row_style(Color("#25313d"), Color("#f2c86b")))
        var margin = MarginContainer.new()
        margin.name = "RowMargin"
        margin.set_anchors_preset(Control.PRESET_FULL_RECT)
        margin.offset_left = 10
        margin.offset_top = 7
        margin.offset_right = -10
        margin.offset_bottom = -7
        margin.mouse_filter = Control.MOUSE_FILTER_IGNORE
        row_button.add_child(margin)
        var row = HBoxContainer.new()
        row.name = "Row"
        row.add_theme_constant_override("separation", 8)
        row.size_flags_horizontal = Control.SIZE_EXPAND_FILL
        row.size_flags_vertical = Control.SIZE_EXPAND_FILL
        row.mouse_filter = Control.MOUSE_FILTER_IGNORE
        var icon_id = "achievement_star" if bool(achievement.get("unlocked", false)) else "lock"
        var icon = _make_sprite_icon(icon_id, int(options.get("icon_size", 30)))
        if icon != null:
            icon.mouse_filter = Control.MOUSE_FILTER_IGNORE
            icon.custom_minimum_size = Vector2(34, 34)
            row.add_child(icon)
        var text_stack = VBoxContainer.new()
        text_stack.name = "Text"
        text_stack.size_flags_horizontal = Control.SIZE_EXPAND_FILL
        text_stack.size_flags_vertical = Control.SIZE_EXPAND_FILL
        text_stack.add_theme_constant_override("separation", 4)
        text_stack.mouse_filter = Control.MOUSE_FILTER_IGNORE
        var title = Label.new()
        title.name = "AchievementName"
        title.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
        title.clip_text = true
        title.max_lines_visible = int(options.get("title_lines", 2))
        title.custom_minimum_size = Vector2(0, int(options.get("title_min_height", 26)))
        title.size_flags_horizontal = Control.SIZE_EXPAND_FILL
        title.mouse_filter = Control.MOUSE_FILTER_IGNORE
        title.set_meta("text_size_role", "body")
        title.set_meta("max_font_size", int(options.get("title_max_font_size", 17)))
        title.text = _achievement_title(achievement)
        text_stack.add_child(title)
        var description = Label.new()
        description.name = "Description"
        description.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
        description.max_lines_visible = int(options.get("description_lines", 2))
        description.clip_text = true
        description.custom_minimum_size = Vector2(0, int(options.get("description_min_height", 40)))
        description.size_flags_horizontal = Control.SIZE_EXPAND_FILL
        description.mouse_filter = Control.MOUSE_FILTER_IGNORE
        description.set_meta("text_size_role", "caption")
        description.set_meta("max_font_size", int(options.get("description_max_font_size", 13)))
        description.text = str(achievement.get("description", ""))
        text_stack.add_child(description)
        var meta = Label.new()
        meta.name = "Meta"
        meta.autowrap_mode = TextServer.AUTOWRAP_OFF
        meta.clip_text = true
        meta.custom_minimum_size = Vector2(0, int(options.get("meta_min_height", 18)))
        meta.size_flags_horizontal = Control.SIZE_EXPAND_FILL
        meta.mouse_filter = Control.MOUSE_FILTER_IGNORE
        meta.set_meta("text_size_role", "caption")
        meta.set_meta("max_font_size", int(options.get("meta_max_font_size", 11)))
        meta.text = _achievement_meta(achievement)
        text_stack.add_child(meta)
        row.add_child(text_stack)
        margin.add_child(row)
        content.add_child(row_button)
    return scroll
 
 
func _achievement_title(achievement:Dictionary) -> String:
    var title = str(achievement.get("title", achievement.get("name", ""))).strip_edges()
    if title != "":
        return title
    var id = str(achievement.get("id", "Achievement")).replace("-", "_")
    var words := []
    for part in id.split("_"):
        if str(part).strip_edges() != "":
            words.append(str(part).capitalize())
    return " ".join(words) if not words.is_empty() else "Achievement"
 
 
func _achievement_meta(achievement:Dictionary) -> String:
    var parts := [
        "Unlocked" if bool(achievement.get("unlocked", false)) else "Locked",
        str(achievement.get("category", "general")).replace("_", " ").capitalize()
    ]
    var date_text = _achievement_unlock_date(achievement)
    if date_text != "":
        parts.append(date_text)
    return " | ".join(parts)
 
 
func _achievement_unlock_date(achievement:Dictionary) -> String:
    if not bool(achievement.get("unlocked", false)):
        return ""
    if not achievement.has("unlocked_at"):
        return ""
    var timestamp := int(achievement.get("unlocked_at", 0))
    if timestamp <= 0:
        return ""
    var date = Time.get_datetime_dict_from_unix_time(timestamp)
    return "%02d-%02d-%04d" % [int(date.get("month", 1)), int(date.get("day", 1)), int(date.get("year", 1970))]
 
 
 
func create_achievement_filter_bar(options:Dictionary = {}, current_filters:Dictionary = {}, changed_callback:Callable = Callable()) -> HBoxContainer:
    var bar = HBoxContainer.new()
    bar.name = "AchievementFilters"
    bar.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    bar.add_theme_constant_override("separation", 8)
    var state_button = _create_filter_option("State", ["all", "locked", "unlocked"], str(current_filters.get("state", "all")), changed_callback)
    bar.add_child(state_button)
    var game_values = options.get("game_ids", [])
    if not game_values.is_empty():
        bar.add_child(_create_filter_option("Game", game_values, str(current_filters.get("game_id", "all")), changed_callback))
    var category_values = options.get("categories", [])
    if not category_values.is_empty():
        bar.add_child(_create_filter_option("Category", category_values, str(current_filters.get("category", "all")), changed_callback))
    return bar
 
 
func _create_filter_option(label:String, values:Array, selected_value:String, changed_callback:Callable) -> OptionButton:
    var option = OptionButton.new()
    option.name = "%sFilter" % label
    option.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    for value in values:
        option.add_item(str(value).replace("_", " ").capitalize())
        option.set_item_metadata(option.item_count - 1, str(value))
        if str(value) == selected_value:
            option.select(option.item_count - 1)
    if option.selected < 0 and option.item_count > 0:
        option.select(0)
    if changed_callback.is_valid():
        option.item_selected.connect(func(index): changed_callback.call(label.to_lower(), str(option.get_item_metadata(index))))
    return option
 
 
func _create_achievement_summary(achievements:Array) -> Label:
    var unlocked := 0
    var locked := 0
    var categories := {}
    for achievement in achievements:
        if not achievement is Dictionary:
            continue
        if bool(achievement.get("unlocked", false)):
            unlocked += 1
        else:
            locked += 1
        var category = str(achievement.get("category", "general"))
        categories[category] = true
    var summary = Label.new()
    summary.name = "Status"
    summary.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
    summary.text = "%d unlocked / %d locked - %d categories" % [unlocked, locked, categories.keys().size()]
    return summary
 
 
func _achievement_row_style(bg:Color, border:Color) -> StyleBoxFlat:
    var cache_key := "achievement_row|%s|%s" % [bg.to_html(true), border.to_html(true)]
    if style_cache.has(cache_key):
        style_cache_hits += 1
        return style_cache[cache_key]
    style_cache_misses += 1
    var style = StyleBoxFlat.new()
    style.bg_color = bg
    style.border_color = border
    style.set_border_width_all(1)
    style.set_corner_radius_all(6)
    style.content_margin_left = 8
    style.content_margin_right = 8
    style.content_margin_top = 6
    style.content_margin_bottom = 6
    style_cache[cache_key] = style
    return style
 
 
 
func create_pause_overlay(actions:Dictionary = {}) -> PopupPanel:
    var popup = PopupPanel.new()
    popup.name = "PauseOverlay"
    popup.size = Vector2i(340, 500)
    var content = VBoxContainer.new()
    content.name = "Content"
    apply_full_rect(content, 14)
    content.add_theme_constant_override("separation", 10)
    popup.add_child(content)
    var title = Label.new()
    title.name = "Title"
    title.text = str(actions.get("title", "Paused"))
    title.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER
    content.add_child(title)
    for action_id in ["resume", "settings", "input", "stats", "achievements", "main_menu", "quit"]:
        if not actions.has(action_id):
            continue
        var action = actions[action_id]
        if not action is Dictionary:
            continue
        var button = Button.new()
        button.name = "%sButton" % action_id.capitalize()
        button.text = str(action.get("label", action_id.capitalize()))
        _apply_button_icon(button, str(action.get("sprite_id", _default_pause_sprite(action_id))), 26)
        button.custom_minimum_size = Vector2(0, 52)
        button.size_flags_horizontal = Control.SIZE_EXPAND_FILL
        var callback = action.get("callback", Callable())
        if callback is Callable and callback.is_valid():
            button.pressed.connect(callback)
        content.add_child(button)
    return popup
 
 
func _ensure_ui_sprites_loaded() -> void:
    if sprites_loaded:
        return
    sprite_manager.load_packs([
        "res://assets/sprites/ui/ui_core.json",
        "res://assets/sprites/ui/ui_navigation.json"
    ])
    sprites_loaded = true
 
 
func _make_sprite_icon(sprite_id:String, size:int = 28):
    if sprite_id == "":
        return null
    _ensure_ui_sprites_loaded()
    var texture = sprite_manager.get_scaled_texture(sprite_id, size)
    if texture == null:
        return null
    var icon = TextureRect.new()
    icon.texture = texture
    icon.custom_minimum_size = Vector2(size, size)
    icon.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED
    icon.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
    icon.size_flags_horizontal = Control.SIZE_SHRINK_CENTER
    icon.size_flags_vertical = Control.SIZE_SHRINK_CENTER
    icon.mouse_filter = Control.MOUSE_FILTER_IGNORE
    return icon
 
 
func _apply_button_icon(button:Button, sprite_id:String, size:int = 24) -> void:
    if sprite_id == "":
        return
    _ensure_ui_sprites_loaded()
    var texture = sprite_manager.get_scaled_texture(sprite_id, size)
    if texture == null:
        return
    button.icon = texture
    button.icon_alignment = HORIZONTAL_ALIGNMENT_LEFT
 
 
func _default_pause_sprite(action_id:String) -> String:
    return {
        "resume": "play",
        "settings": "settings_gear",
        "input": "keyboard",
        "stats": "trophy",
        "achievements": "achievement_star",
        "main_menu": "home",
        "back": "back",
        "quit": "cancel"
    }.get(action_id, "")
 
 
func _apply_theme_recursive(node:Node, theme_name:String, colors:Dictionary) -> void:
    if node == null:
        return
    var styles = get_theme_styles(theme_name)
    if node is PanelContainer or node is PopupPanel:
        node.add_theme_stylebox_override("panel", make_panel_style(theme_name))
        _apply_style_target(node, "panel", styles)
    if node is Label:
        var color_key = "muted" if str(node.name).to_lower().contains("description") or str(node.name).to_lower().contains("info") or str(node.name).to_lower().contains("status") else "text"
        node.add_theme_color_override("font_color", colors[color_key])
    if node is Button or node is OptionButton or node is CheckButton:
        node.add_theme_color_override("font_color", colors["text"])
        node.add_theme_stylebox_override("normal", make_button_style(theme_name, "normal"))
        node.add_theme_stylebox_override("hover", make_button_style(theme_name, "hover"))
        node.add_theme_stylebox_override("pressed", make_button_style(theme_name, "pressed"))
        node.add_theme_stylebox_override("disabled", make_button_style(theme_name, "disabled"))
        _apply_style_target(node, "button", styles)
    if node is ItemList:
        node.add_theme_color_override("font_color", colors["text"])
        node.add_theme_color_override("font_selected_color", colors["text"])
    for child in node.get_children():
        _apply_theme_recursive(child, theme_name, colors)
 
 
func _normalize_theme_definition(definition) -> Dictionary:
    var base := THEME_PRESETS["dark"].duplicate(true)
    if not definition is Dictionary:
        return base
    var source:Dictionary = definition
    if source.has("colors") and source["colors"] is Dictionary:
        base["name"] = str(source.get("name", base.get("name", "Dark")))
        base["description"] = str(source.get("description", ""))
        if source.get("typography", {}) is Dictionary:
            base["typography"] = source.get("typography", {})
        if source.get("styles", {}) is Dictionary:
            base["styles"] = source.get("styles", {})
        for key in source["colors"].keys():
            if _is_color_like(source["colors"][key]):
                base[key] = source["colors"][key]
    else:
        for key in source.keys():
            if key == "styles" and source[key] is Dictionary:
                base["styles"] = source[key]
            elif key == "typography" and source[key] is Dictionary:
                base["typography"] = source[key]
            elif key == "name" or key == "description":
                base[key] = source[key]
            elif _is_color_like(source[key]):
                base[key] = source[key]
    base["panel"] = base.get("panel", base.get("surface", "#1a222b"))
    base["panel_alt"] = base.get("panel_alt", base.get("surface_alt", "#202a34"))
    base["button"] = base.get("button", base.get("surface_alt", "#202a34"))
    base["button_hover"] = base.get("button_hover", base.get("button", "#202a34"))
    base["button_pressed"] = base.get("button_pressed", base.get("surface", "#1a222b"))
    base["button_disabled"] = base.get("button_disabled", base.get("surface", "#1a222b"))
    return base
 
 
func _is_color_like(value) -> bool:
    if value is Color:
        return true
    if value is String:
        return Color.html_is_valid(str(value).strip_edges())
    return false
 
 
func _coerce_theme_color(value, fallback:Color) -> Color:
    if value is Color:
        return value
    if value is String:
        var text := str(value).strip_edges()
        if Color.html_is_valid(text):
            return Color.html(text)
    return fallback
 
 
func _apply_style_target(node:Node, target:String, styles:Dictionary) -> void:
    if not styles.has(target) or not styles[target] is Dictionary:
        return
    if not node is Control:
        return
    var style:Dictionary = styles[target]
    var image_path := str(style.get("background_image", ""))
    if image_path == "" or not ResourceLoader.exists(image_path):
        return
    var texture = sprite_manager.get_texture_for_path(image_path)
    if texture == null:
        return
    var control := node as Control
    if control.get_node_or_null("ThemeBackgroundImage") != null:
        return
    var image = TextureRect.new()
    image.name = "ThemeBackgroundImage"
    image.texture = texture
    image.modulate.a = clampf(float(style.get("opacity", 1.0)), 0.0, 1.0)
    image.mouse_filter = Control.MOUSE_FILTER_IGNORE
    image.set_anchors_preset(Control.PRESET_FULL_RECT)
    match str(style.get("texture_mode", "stretch")):
        "tile":
            image.stretch_mode = TextureRect.STRETCH_TILE
        "keep":
            image.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_COVERED
        _:
            image.stretch_mode = TextureRect.STRETCH_SCALE
    control.add_child(image)
    control.move_child(image, 0)
 
 
func _merge_dict(base:Dictionary, override:Dictionary) -> Dictionary:
    var merged := base.duplicate(true)
    for key in override.keys():
        if merged.get(key) is Dictionary and override[key] is Dictionary:
            merged[key] = _merge_dict(merged[key], override[key])
        else:
            merged[key] = override[key]
    return merged
 
 
func _theme_catalog_paths(primary_path:String) -> Array:
    var paths := [primary_path]
    if primary_path == "res://data/themes/default.json" and FileAccess.file_exists(CUSTOM_THEME_CATALOG_PATH):
        paths.append(CUSTOM_THEME_CATALOG_PATH)
    return paths
 
 
func _coerce_size(value, fallback:Vector2i) -> Vector2i:
    if value is Vector2i:
        return value
    if value is Vector2:
        return Vector2i(int(value.x), int(value.y))
    if value is Dictionary:
        return Vector2i(int(value.get("x", fallback.x)), int(value.get("y", fallback.y)))
    return fallback
 
 
func _apply_density_recursive(node:Node, density_name:String) -> void:
    if node is Control:
        apply_density(node, density_name)
    for child in node.get_children():
        _apply_density_recursive(child, density_name)
 
 
 
func create_confirmation_dialog(title:String, message:String, confirm_label:String = "Confirm", cancel_label:String = "Cancel") -> PanelContainer:
    var panel = create_panel_shell("ConfirmationDialog")
    var content = panel.get_node("Content")
    var title_label = Label.new()
    title_label.text = title
    title_label.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER
    content.add_child(title_label)
    var message_label = Label.new()
    message_label.text = message
    message_label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
    content.add_child(message_label)
    var actions = HBoxContainer.new()
    actions.name = "Actions"
    content.add_child(actions)
    var confirm = Button.new()
    confirm.name = "Confirm"
    confirm.text = confirm_label
    confirm.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    actions.add_child(confirm)
    var cancel = Button.new()
    cancel.name = "Cancel"
    cancel.text = cancel_label
    cancel.size_flags_horizontal = Control.SIZE_EXPAND_FILL
    actions.add_child(cancel)
    return panel