From 60614149dba4f5e432018a09ec50e4e60a9e8bfc Mon Sep 17 00:00:00 2001 From: wusumac <736139669@qq.com> Date: Tue, 25 Aug 2026 10:03:51 +0800 Subject: [PATCH] feat(runtime): add shared foundation primitives --- runtime/foundation/app_services.gd | 42 +++++++ runtime/foundation/screen_context.gd | 48 ++++++++ runtime/foundation/screen_stack.gd | 71 ++++++++++++ runtime/foundation/ui_tokens.gd | 42 +++++++ .../foundation/runtime_foundation_test.gd | 86 ++++++++++++++ runtime/ui/shared/shared_button.gd | 107 ++++++++++++++++++ 6 files changed, 396 insertions(+) create mode 100644 runtime/foundation/app_services.gd create mode 100644 runtime/foundation/screen_context.gd create mode 100644 runtime/foundation/screen_stack.gd create mode 100644 runtime/foundation/ui_tokens.gd create mode 100644 runtime/tests/foundation/runtime_foundation_test.gd create mode 100644 runtime/ui/shared/shared_button.gd diff --git a/runtime/foundation/app_services.gd b/runtime/foundation/app_services.gd new file mode 100644 index 00000000..25c9ca8e --- /dev/null +++ b/runtime/foundation/app_services.gd @@ -0,0 +1,42 @@ +class_name ABGAppServices +extends RefCounted + +const ScreenStackScript = preload("res://foundation/screen_stack.gd") + +## Explicit dependency bundle for new Runtime pages. Existing legacy pages may +## continue to construct their own services until they are migrated, but new +## code should receive this object instead of reaching through a root facade. + +var screen_stack +var _services: Dictionary = {} + + +func _init(initial_services: Dictionary = {}) -> void: + screen_stack = initial_services.get("screen_stack", ScreenStackScript.new()) + for key in initial_services.keys(): + if key == "screen_stack": + continue + _services[StringName(key)] = initial_services[key] + + +func register_service(service_id: StringName, service: Variant) -> void: + if service == null: + _services.erase(service_id) + return + _services[service_id] = service + + +func has_service(service_id: StringName) -> bool: + return _services.has(service_id) and _services[service_id] != null + + +func resolve_service(service_id: StringName) -> Variant: + return _services.get(service_id, null) + + +func service_snapshot() -> Dictionary: + var result: Dictionary = {} + for key in _services.keys(): + result[String(key)] = _services[key] != null + result["screen_stack"] = screen_stack != null + return result diff --git a/runtime/foundation/screen_context.gd b/runtime/foundation/screen_context.gd new file mode 100644 index 00000000..63e8b445 --- /dev/null +++ b/runtime/foundation/screen_context.gd @@ -0,0 +1,48 @@ +class_name ABGScreenContext +extends RefCounted + +## A small, UI-independent description of where a screen was opened from and +## where it should return. Page controllers may carry this across a route or +## overlay, but the context never owns gameplay state or persistence. + +var screen_id := "" +var caller_id := "" +var return_screen_id := "" +var return_focus_path := "" +var presentation_mode := "page" +var metadata: Dictionary = {} + + +func _init(values: Dictionary = {}) -> void: + screen_id = String(values.get("screen_id", "")) + caller_id = String(values.get("caller_id", "")) + return_screen_id = String(values.get("return_screen_id", "")) + return_focus_path = String(values.get("return_focus_path", "")) + presentation_mode = String(values.get("presentation_mode", "page")) + metadata = values.get("metadata", {}).duplicate(true) if values.get("metadata", {}) is Dictionary else {} + + +func is_overlay() -> bool: + return presentation_mode == "overlay" + + +func duplicate_context(): + var copy = get_script().new() + copy.screen_id = screen_id + copy.caller_id = caller_id + copy.return_screen_id = return_screen_id + copy.return_focus_path = return_focus_path + copy.presentation_mode = presentation_mode + copy.metadata = metadata.duplicate(true) + return copy + + +func to_dictionary() -> Dictionary: + return { + "screen_id": screen_id, + "caller_id": caller_id, + "return_screen_id": return_screen_id, + "return_focus_path": return_focus_path, + "presentation_mode": presentation_mode, + "metadata": metadata.duplicate(true), + } diff --git a/runtime/foundation/screen_stack.gd b/runtime/foundation/screen_stack.gd new file mode 100644 index 00000000..19b9608e --- /dev/null +++ b/runtime/foundation/screen_stack.gd @@ -0,0 +1,71 @@ +class_name ABGScreenStack +extends RefCounted + +const ScreenContextScript = preload("res://foundation/screen_context.gd") + +signal changed + +var _entries: Array = [] + + +func push(context) -> Variant: + if context == null or String(context.screen_id).is_empty(): + return null + _entries.append(context.duplicate_context()) + changed.emit() + return current() + + +func replace(context) -> Variant: + if context == null or String(context.screen_id).is_empty(): + return null + if _entries.is_empty(): + return push(context) + _entries[_entries.size() - 1] = context.duplicate_context() + changed.emit() + return current() + + +func pop() -> Variant: + if _entries.is_empty(): + return null + var removed = _entries.pop_back() + changed.emit() + return removed + + +func clear() -> void: + if _entries.is_empty(): + return + _entries.clear() + changed.emit() + + +func current() -> Variant: + if _entries.is_empty(): + return null + return _entries[_entries.size() - 1].duplicate_context() + + +func at(index: int) -> Variant: + if index < 0 or index >= _entries.size(): + return null + return _entries[index].duplicate_context() + + +func contains(screen_id: String) -> bool: + for entry in _entries: + if String(entry.screen_id) == screen_id: + return true + return false + + +func depth() -> int: + return _entries.size() + + +func snapshot() -> Array[Dictionary]: + var result: Array[Dictionary] = [] + for entry in _entries: + result.append(entry.to_dictionary()) + return result diff --git a/runtime/foundation/ui_tokens.gd b/runtime/foundation/ui_tokens.gd new file mode 100644 index 00000000..d2eefd1c --- /dev/null +++ b/runtime/foundation/ui_tokens.gd @@ -0,0 +1,42 @@ +class_name ABGUI_Tokens +extends RefCounted + +## Shared visual/layout vocabulary. These tokens are deliberately not a page +## layout: a page may choose its own composition while retaining the same +## semantic controls, readable type and focus language. + +const DESIGN_ASPECT := 16.0 / 9.0 +const MIN_TOUCH_TARGET := Vector2(48.0, 48.0) +const MIN_FOCUS_GAP := 4.0 +const COLOR_INK := Color("#111921") +const COLOR_NAVY := Color("#182838") +const COLOR_NAVY_LIFT := Color("#263e53") +const COLOR_NAVY_DISABLED := Color("#323b43") +const COLOR_GOLD := Color("#b99a5d") +const COLOR_GOLD_LIGHT := Color("#ead49b") +const COLOR_IVORY := Color("#f5ead0") +const COLOR_SKY := Color("#73b9e7") +const COLOR_DANGER := Color("#a94b53") +const COLOR_MUTED := Color("#73808a") + +const FONT_SIZES := { + "micro": 11, + "label": 14, + "body": 16, + "heading": 22, + "title": 30, +} + + +static func font_size(role: String, text_scale := 1.0) -> int: + var base: int = int(FONT_SIZES.get(role, FONT_SIZES.body)) + return maxi(11, int(round(float(base) * maxf(0.8, text_scale)))) + + +static func touch_size(size: Vector2 = Vector2.ZERO) -> Vector2: + return Vector2(maxf(MIN_TOUCH_TARGET.x, size.x), maxf(MIN_TOUCH_TARGET.y, size.y)) + + +static func is_supported_variant(variant: String) -> bool: + return variant in ["primary", "secondary", "utility", "danger", "icon"] + diff --git a/runtime/tests/foundation/runtime_foundation_test.gd b/runtime/tests/foundation/runtime_foundation_test.gd new file mode 100644 index 00000000..8068666e --- /dev/null +++ b/runtime/tests/foundation/runtime_foundation_test.gd @@ -0,0 +1,86 @@ +extends SceneTree + +const AppServices = preload("res://foundation/app_services.gd") +const ScreenContext = preload("res://foundation/screen_context.gd") +const ScreenStack = preload("res://foundation/screen_stack.gd") +const Tokens = preload("res://foundation/ui_tokens.gd") +const SharedButton = preload("res://ui/shared/shared_button.gd") + +var failures: Array[String] = [] + + +func _initialize() -> void: + call_deferred("run_test") + + +func run_test() -> void: + verify_context_round_trip() + verify_screen_stack() + verify_service_bundle() + await verify_shared_ui_contract() + if failures.is_empty(): + print("ABG_M15_FOUNDATION_OK context=true stack=true services=true ui_tokens=true shared_button=true") + quit(0) + else: + for failure in failures: + push_error(failure) + quit(1) + + +func verify_context_round_trip() -> void: + var context := ScreenContext.new({ + "screen_id": "settings", + "caller_id": "battle_pause_controls", + "return_screen_id": "battle", + "return_focus_path": "BattleLive/Settings", + "presentation_mode": "overlay", + "metadata": {"locale": "zh_CN", "operation_id": "op-1"}, + }) + expect(context.is_overlay(), "overlay context reports its presentation mode") + var restored := ScreenContext.new(context.to_dictionary()) + expect(restored.screen_id == "settings" and restored.return_screen_id == "battle", "context preserves route identity") + expect(restored.return_focus_path == "BattleLive/Settings" and restored.metadata.locale == "zh_CN", "context preserves focus and metadata") + + +func verify_screen_stack() -> void: + var stack = ScreenStack.new() + stack.push(ScreenContext.new({"screen_id": "title"})) + stack.push(ScreenContext.new({"screen_id": "settings", "caller_id": "title"})) + expect(stack.depth() == 2 and stack.contains("settings"), "stack pushes independent screen contexts") + var current = stack.current() + expect(current != null and current.screen_id == "settings", "stack returns the top context") + stack.replace(ScreenContext.new({"screen_id": "credits", "caller_id": "settings"})) + expect(stack.depth() == 2 and stack.current().screen_id == "credits", "stack replaces only the top context") + var popped = stack.pop() + expect(popped != null and popped.screen_id == "credits" and stack.current().screen_id == "title", "stack pops to the previous route") + stack.clear() + expect(stack.depth() == 0 and stack.current() == null, "stack clears without leaving stale context") + + +func verify_service_bundle() -> void: + var sentinel := RefCounted.new() + var services := AppServices.new({"settings": sentinel}) + expect(services.has_service(&"settings") and services.resolve_service(&"settings") == sentinel, "service bundle registers explicit dependencies") + services.register_service(&"audio", sentinel) + expect(services.has_service(&"audio") and services.service_snapshot().screen_stack, "service bundle exposes screen stack and services") + services.register_service(&"audio", null) + expect(not services.has_service(&"audio"), "service bundle removes a cleared dependency") + + +func verify_shared_ui_contract() -> void: + expect(Tokens.touch_size(Vector2(10, 60)) == Vector2(48, 60), "shared touch token enforces the minimum target") + expect(Tokens.font_size("body", 1.0) == 16 and Tokens.font_size("body", 1.3) >= 20, "shared typography token scales predictably") + var button := SharedButton.new() + button.configure("Apply", "primary") + button.set_view_state(true, true, false) + root.add_child(button) + await process_frame + expect(button.semantic_variant == "primary" and button.selected_state and not button.disabled, "shared button exposes semantic view state") + expect(button.custom_minimum_size.x >= 48.0 and button.custom_minimum_size.y >= 48.0, "shared button keeps the touch target") + button.queue_free() + await process_frame + + +func expect(condition: bool, message: String) -> void: + if not condition: + failures.append("M15 Foundation: %s" % message) diff --git a/runtime/ui/shared/shared_button.gd b/runtime/ui/shared/shared_button.gd new file mode 100644 index 00000000..0c45842a --- /dev/null +++ b/runtime/ui/shared/shared_button.gd @@ -0,0 +1,107 @@ +class_name ABGSharedButton +extends Button + +const Tokens = preload("res://foundation/ui_tokens.gd") + +## Generic semantic button. It emits the built-in `pressed` intent and owns no +## game state, save behavior or page lookup. + +var semantic_variant := "secondary" +var selected_state := false +var busy_state := false +var _refreshing := false + + +func _ready() -> void: + focus_mode = Control.FOCUS_ALL + custom_minimum_size = Tokens.touch_size(custom_minimum_size) + _refresh_style() + + +func configure(next_text: String, next_variant := "secondary"): + text = next_text + semantic_variant = next_variant if Tokens.is_supported_variant(next_variant) else "secondary" + _refresh_style() + return self + + +func set_view_state(enabled := true, selected := false, busy := false) -> void: + disabled = not enabled + selected_state = selected + busy_state = busy + _refresh_style() + + +func _refresh_style() -> void: + if _refreshing: + return + if not is_inside_tree() and get_parent() == null: + return + _refreshing = true + var normal_fill := Tokens.COLOR_NAVY + var hover_fill := Tokens.COLOR_NAVY_LIFT + var pressed_fill := Tokens.COLOR_NAVY_LIFT + var border := Tokens.COLOR_GOLD + if semantic_variant == "primary": + normal_fill = Color("#e8d9b7") + hover_fill = Color("#fff1c9") + pressed_fill = Color("#d7c39a") + border = Color("#806536") + elif semantic_variant == "danger": + normal_fill = Color("#4d2830") + hover_fill = Color("#68343d") + pressed_fill = Color("#3b2027") + border = Tokens.COLOR_DANGER + elif semantic_variant == "icon": + normal_fill = Color(Tokens.COLOR_NAVY, 0.72) + hover_fill = Tokens.COLOR_NAVY_LIFT + pressed_fill = Tokens.COLOR_NAVY + border = Tokens.COLOR_SKY + if selected_state: + hover_fill = Color("#34506a") + border = Tokens.COLOR_SKY + if disabled: + normal_fill = Tokens.COLOR_NAVY_DISABLED + hover_fill = normal_fill + pressed_fill = normal_fill + border = Tokens.COLOR_MUTED + var text_color := Tokens.COLOR_IVORY + if semantic_variant == "primary": + text_color = Tokens.COLOR_INK + if disabled: + text_color = Color("#a1a8aa") + add_theme_color_override("font_color", text_color) + add_theme_color_override("font_hover_color", text_color) + add_theme_color_override("font_pressed_color", text_color) + add_theme_color_override("font_focus_color", text_color) + add_theme_font_size_override("font_size", Tokens.font_size("label")) + add_theme_stylebox_override("normal", _style_box(normal_fill, border)) + add_theme_stylebox_override("hover", _style_box(hover_fill, border)) + add_theme_stylebox_override("pressed", _style_box(pressed_fill, border)) + add_theme_stylebox_override("disabled", _style_box(normal_fill, border)) + add_theme_stylebox_override("focus", _focus_box(border)) + _refreshing = false + + +func _style_box(fill: Color, border: Color) -> StyleBoxFlat: + var box := StyleBoxFlat.new() + box.bg_color = fill + box.border_color = border + box.set_border_width_all(1) + box.corner_radius_top_left = 6 + box.corner_radius_top_right = 6 + box.corner_radius_bottom_left = 6 + box.corner_radius_bottom_right = 6 + box.content_margin_left = 12.0 + box.content_margin_right = 12.0 + box.content_margin_top = 8.0 + box.content_margin_bottom = 8.0 + return box + + +func _focus_box(border: Color) -> StyleBoxFlat: + var box := _style_box(Color(0, 0, 0, 0), Tokens.COLOR_SKY) + box.set_border_width_all(2) + box.shadow_color = Color(border, 0.32) + box.shadow_size = 3 + return box