feat(runtime): add shared foundation primitives

This commit is contained in:
2026-08-25 10:03:51 +08:00
parent 8a6af6cd88
commit 60614149db
6 changed files with 396 additions and 0 deletions
+42
View File
@@ -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
+48
View File
@@ -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),
}
+71
View File
@@ -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
+42
View File
@@ -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"]
@@ -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)
+107
View File
@@ -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