diff --git a/docs/runtime/M51_UI_ASSET_SCALING_CONTRACT.md b/docs/runtime/M51_UI_ASSET_SCALING_CONTRACT.md new file mode 100644 index 00000000..e7ec14e3 --- /dev/null +++ b/docs/runtime/M51_UI_ASSET_SCALING_CONTRACT.md @@ -0,0 +1,24 @@ +# M51 UI Asset Scaling Contract + +This contract separates authored UI materials by their runtime scaling job. +An image is not marked stretchable merely because it has transparent padding. + +| Asset family | Runtime treatment | Fixed elements | Variable area | Do not do | +|---|---|---|---|---| +| Primary/secondary action plate | Nine-patch, horizontal first | corners, seal/icon mount, outline thickness | clean paper center and horizontal spacing | scale the whole bitmap vertically; put text in the bitmap | +| Commission/task board | Nine-patch or layered frame + paper | posts, corner fittings, wood grain edges | blank parchment center in both axes | tile decorative center; let content touch fittings | +| Recruit card frame | Layered frame + portrait + text; nine-patch only for frame | frame corners, portrait aspect, name/value baseline | paper inset and card width within min/max | stretch the character or use a full-frame bitmap as a list icon | +| Semantic seals/icons | Preserve aspect ratio; fixed logical box | silhouette, stroke weight, internal mark | none | nine-patch, non-uniform scaling or color-only state | +| Character sprites/equipment art | Preserve aspect ratio; authored anchor/pivot | silhouette, anatomy, weapon relation | none | crop, squash or use as a UI background | +| Full-screen world background | Aspect-preserving cover with declared safe rect | focal subjects and horizon relationship | decorative edges / revealed world space | nested 16:9 canvas, non-uniform scale or opaque UI poster | + +## Verification matrix + +Stretchable materials are captured at their minimum, reference and wide sizes. +Non-stretchable assets are captured at at least 0.75x, 1x and 1.5x while +checking aspect ratio, silhouette and anchor. Every capture is a normal render. + +The gate checks corner shape, border thickness, texture repetition, content +safe area, text bounds, icon aspect, focal crop and the smallest legal touch +target. A green test or imported PNG is not sufficient evidence. + diff --git a/runtime/tests/foundation/m51_ui_asset_scaling_test.gd b/runtime/tests/foundation/m51_ui_asset_scaling_test.gd new file mode 100644 index 00000000..b364c5b8 --- /dev/null +++ b/runtime/tests/foundation/m51_ui_asset_scaling_test.gd @@ -0,0 +1,131 @@ +extends SceneTree + +const Tokens = preload("res://foundation/ui_tokens.gd") +const UIFactory = preload("res://ui/shared/ui_factory.gd") +const ACTION = preload("res://assets/ui_m51/action_plate@2x.png") +const BOARD = preload("res://assets/ui_m51/commission_board@2x.png") +const CARD = preload("res://assets/ui_m51/recruit_card@2x.png") +const SEALS = preload("res://assets/ui_m51/seals@2x.png") + +const FIXTURES := [{"width": 760, "height": 360}, {"width": 844, "height": 390}, {"width": 1280, "height": 720}] +var failures: Array[String] = [] +var output_root := "" + +func _initialize() -> void: + call_deferred("run_test") + +func run_test() -> void: + output_root = OS.get_environment("ABG_EVIDENCE_DIR") + if output_root.is_empty(): output_root = "/tmp/abg-m51-asset-scaling" + DirAccess.make_dir_recursive_absolute(output_root) + for fixture in FIXTURES: await _capture_fixture(fixture) + if failures.is_empty(): + print("ABG_M51_UI_ASSET_SCALING_OK fixtures=760x360,844x390,1280x720 ninepatch=action,board layered=card fixed=seals") + quit(0) + else: + for failure in failures: push_error(failure) + quit(1) + +func _capture_fixture(fixture: Dictionary) -> void: + var viewport := SubViewport.new() + viewport.size = Vector2i(int(fixture.width), int(fixture.height)) + viewport.render_target_update_mode = SubViewport.UPDATE_ALWAYS + root.add_child(viewport) + var host := Control.new() + host.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT) + viewport.add_child(host) + var bg := ColorRect.new() + bg.color = Color("#263c49") + bg.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT) + host.add_child(bg) + var safe := MarginContainer.new() + safe.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT) + var inset := 14 if int(fixture.width) < 900 else 24 + for edge in ["left", "right", "top", "bottom"]: safe.add_theme_constant_override("margin_%s" % edge, inset) + host.add_child(safe) + var page := VBoxContainer.new() + page.add_theme_constant_override("separation", 8) + safe.add_child(page) + page.add_child(UIFactory.label("M51 ASSET SCALING / 九宫格与等比素材", "heading", 1.0, Tokens.COLOR_IVORY)) + page.add_child(UIFactory.label("Corners stay fixed · clean centers expand · icons never squash", "body", 1.0, Tokens.COLOR_GOLD_LIGHT)) + var actions := HBoxContainer.new() + actions.add_theme_constant_override("separation", 8) + page.add_child(actions) + for width in [120.0, 180.0, 280.0]: + var action := _nine_patch(ACTION, Vector2(width, 48), Vector4(26, 22, 26, 22)) + action.name = "Action%d" % int(width) + actions.add_child(action) + var text := UIFactory.label("确认", "label", 1.0, Tokens.COLOR_INK) + text.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT) + text.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER + text.vertical_alignment = VERTICAL_ALIGNMENT_CENTER + action.add_child(text) + var row := HBoxContainer.new() + row.add_theme_constant_override("separation", 12) + row.size_flags_vertical = Control.SIZE_EXPAND_FILL + page.add_child(row) + var board := _nine_patch(BOARD, Vector2(260 if int(fixture.width) < 900 else 340, 0), Vector4(22, 22, 22, 22)) + board.name = "CommissionBoard" + board.size_flags_vertical = Control.SIZE_EXPAND_FILL + row.add_child(board) + var board_text := UIFactory.label("委托板\n中间羊皮纸扩展,木柱和角件保持比例。", "body", 1.0, Tokens.COLOR_INK) + board_text.set_anchors_and_offsets_preset(Control.PRESET_CENTER) + board_text.custom_minimum_size = Vector2(180, 80) + board_text.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER + board.add_child(board_text) + var card := TextureRect.new() + card.name = "RecruitCardFrame" + card.texture = CARD + card.expand_mode = TextureRect.EXPAND_IGNORE_SIZE + card.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED + card.texture_filter = CanvasItem.TEXTURE_FILTER_LINEAR_WITH_MIPMAPS + card.custom_minimum_size = Vector2(170, 0) + card.size_flags_horizontal = Control.SIZE_EXPAND_FILL + card.size_flags_vertical = Control.SIZE_EXPAND_FILL + row.add_child(card) + var seals := TextureRect.new() + seals.name = "SemanticSeals" + seals.texture = SEALS + seals.expand_mode = TextureRect.EXPAND_IGNORE_SIZE + seals.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED + seals.texture_filter = CanvasItem.TEXTURE_FILTER_LINEAR_WITH_MIPMAPS + seals.custom_minimum_size = Vector2(180, 100) + row.add_child(seals) + await _frames(3) + _verify(host, fixture) + await RenderingServer.frame_post_draw + var image := viewport.get_texture().get_image() + var filename := "scaling-%dx%d.png" % [int(fixture.width), int(fixture.height)] + if image.is_empty() or image.save_png(output_root.path_join(filename)) != OK: failures.append("capture failed: %s" % filename) + viewport.queue_free() + await _frames(2) + +func _nine_patch(texture: Texture2D, requested: Vector2, margins: Vector4) -> NinePatchRect: + var node := NinePatchRect.new() + node.texture = texture + node.region_rect = Rect2(Vector2.ZERO, Vector2(texture.get_width(), texture.get_height())) + node.patch_margin_left = margins.x + node.patch_margin_top = margins.y + node.patch_margin_right = margins.z + node.patch_margin_bottom = margins.w + node.axis_stretch_horizontal = NinePatchRect.AXIS_STRETCH_MODE_TILE_FIT + node.axis_stretch_vertical = NinePatchRect.AXIS_STRETCH_MODE_TILE_FIT + node.custom_minimum_size = requested + node.size_flags_horizontal = Control.SIZE_EXPAND_FILL + return node + +func _verify(host: Control, fixture: Dictionary) -> void: + var bounds := Rect2(Vector2.ZERO, Vector2(float(fixture.width), float(fixture.height))) + for name in ["Action120", "Action180", "Action280", "CommissionBoard", "RecruitCardFrame", "SemanticSeals"]: + var node := host.find_child(name, true, false) as Control + expect(node != null, "%s exists" % name) + if node != null: expect(bounds.encloses(node.get_global_rect()), "%s stays inside bounds" % name) + for name in ["Action120", "Action180", "Action280"]: + var node := host.find_child(name, true, false) as Control + if node != null: expect(node.size.y >= 48.0, "%s keeps 48px height" % name) + +func _frames(count: int) -> void: + for _frame in range(count): await process_frame + +func expect(condition: bool, message: String) -> void: + if not condition: failures.append("M51 Asset Scaling: %s" % message)