fix(rendering): complete character visual regression fixes

project/char_select_visual_test.gd

@@ -12,15 +12,29 @@ func _initialize() -> void:
 
 func _run() -> void:
 	root.size = Vector2i(1472, 854)
+	var output := OS.get_environment("MT_RENDER_OUTPUT")
+	if output.is_empty():
+		output = ProjectSettings.globalize_path("res://../build/rendering/selection-%d-%d" % [Time.get_unix_time_from_system(), OS.get_process_id()])
+	DirAccess.make_dir_recursive_absolute(output)
+	var hair_part := 0
+	var job := 0
+	var main_part := 20009
+	for arg in OS.get_cmdline_user_args():
+		if arg.begins_with("--hair="):
+			hair_part = int(arg.trim_prefix("--hair="))
+		elif arg.begins_with("--job="):
+			job = clampi(int(arg.trim_prefix("--job=")), 0, 7)
+		elif arg.begins_with("--main-part="):
+			main_part = max(0, int(arg.trim_prefix("--main-part=")))
 	var client := Client.new()
 	root.add_child(client)
 	var screen := Screen.new()
 	root.add_child(screen)
 	screen.setup(client, AssetRoot.path(), [{
-		"index": 0, "name": "[SA]Admin", "job": 0, "level": 105,
+		"index": 0, "name": "[SA]Admin", "job": job, "level": 105,
 		"guild_name": "[GM-TEAM]", "play_minutes": 2180,
 		"ht": 90, "iq": 15, "st": 90, "dx": 90,
-		"main_part": 20009, "hair_part": 0,
+		"main_part": main_part, "hair_part": hair_part,
 	}])
 	for i in 40:
 		await process_frame
@@ -28,19 +42,80 @@ func _run() -> void:
 		printerr("FAIL: selection model did not load")
 		quit(1)
 		return
+	# R2 diagnostics: compare the exact same armour with the configured hair
+	# removed.  This distinguishes an absent/incorrect face surface from a hair
+	# depth or alpha problem; normal visual tests keep the real HairIndex 0.
+	if "--no-hair" in OS.get_cmdline_user_args():
+		screen._pv.model.set("hair_gr2", "")
+		for _i in 2:
+			await process_frame
 	print("Selected armor: ", screen._pv.model.get("gr2_path"))
+	screen._pv.anim.set_process(false)
+	screen._pv.anim.set("blend_time", 0.0)
+	screen._pv.anim.set("time", 0.5)
+	# Sample after freezing the reference pose: GPU deformation lives in the
+	# shader, so its current bounds are requested by the same production framing
+	# path rather than read back from the static ArrayMesh.
+	screen._frame_model()
 	print("Hair skin: ", screen._pv.model.get("hair_skin"))
 	var ua = preload("res://ui/ui_assets.gd")
-	ua.load_dds_image(String(screen._pv.model.get("hair_skin"))).save_png("/tmp/metin2-hair.png")
+	var hair_image: Image = ua.load_dds_image(String(screen._pv.model.get("hair_skin")))
+	if hair_image != null:
+		hair_image.save_png(output.path_join("hair-texture.png"))
+	var mesh_bounds: Array = []
 	for mi in screen._pv.find_children("*", "MeshInstance3D", true, false):
+		var local_aabb: AABB = mi.get_aabb()
+		var world_aabb: AABB = mi.get_global_transform() * local_aabb
+		mesh_bounds.append({
+			"node": String(mi.name),
+			"local_position": [local_aabb.position.x, local_aabb.position.y, local_aabb.position.z],
+			"local_size": [local_aabb.size.x, local_aabb.size.y, local_aabb.size.z],
+			"world_position": [world_aabb.position.x, world_aabb.position.y, world_aabb.position.z],
+			"world_size": [world_aabb.size.x, world_aabb.size.y, world_aabb.size.z],
+		})
 		for surface in mi.mesh.get_surface_count():
 			print("SURFACE ", surface, " ", mi.mesh.surface_get_name(surface))
-	if not String(screen._pv.model.get("gr2_path")).to_lower().contains("warrior_5_1"):
+			var mat: Material = mi.get_active_material(surface)
+			if mat is ShaderMaterial:
+				print("MATERIAL mode=", mat.get_shader_parameter("mode"), " alpha_write=", mat.shader.code.contains("ALPHA ="))
+				if "--solid-body" in OS.get_cmdline_user_args():
+					var solid := StandardMaterial3D.new()
+					solid.albedo_texture = mat.get_shader_parameter("albedo_tex")
+					solid.cull_mode = BaseMaterial3D.CULL_DISABLED
+					mi.set_surface_override_material(surface, solid)
+	if main_part == 20009 and not String(screen._pv.model.get("gr2_path")).to_lower().contains("warrior_5_1"):
 		printerr("FAIL: server armor was not applied")
 		quit(1)
 		return
+	if hair_part == 1001 and not String(screen._pv.model.get("hair_gr2")).to_lower().contains("hair_2_1"):
+		printerr("FAIL: standard HairIndex 1001 did not replace the default hair model")
+		quit(1)
+		return
 	if DisplayServer.get_name() != "headless":
 		await RenderingServer.frame_post_draw
-		root.get_texture().get_image().save_png("/tmp/metin2-char-select.png")
+		if root.get_texture().get_image().save_png(output.path_join("selection.png")) != OK:
+			quit(1)
+			return
+	var hashes := {}
+	for path in ["res://ui/char_select_screen.gd", "res://ui/player_view.gd", "res://ui/equip_model.gd", "res://ui/race_spec.gd", "res://char_select_visual_test.gd"]:
+		hashes[path] = FileAccess.get_sha256(path)
+	for key in ["gr2_path", "hair_gr2", "hair_skin"]:
+		var path := String(screen._pv.model.get(key))
+		if not path.is_empty():
+			hashes[path] = FileAccess.get_sha256(path)
+	var library := "res://bin/libmtgodot.macos.template_debug.dylib"
+	hashes[library] = FileAccess.get_sha256(library)
+	var report := FileAccess.open(output.path_join("report.json"), FileAccess.WRITE)
+	report.store_string(JSON.stringify({"sha256": hashes, "engine": Engine.get_version_info(),
+		"job": job, "main_part": main_part, "hair_part": hair_part, "sample_time": 0.5, "args": OS.get_cmdline_user_args(),
+		"gpu_skin": OS.get_environment("MTGODOT_GPUSKIN"),
+		"camera_position": [_cam_pos(screen).x, _cam_pos(screen).y, _cam_pos(screen).z],
+		"mesh_bounds": mesh_bounds,
+		"scope": "assembly assertions; screenshot requires visual review, not 40250 pixel parity"}, "\t"))
+	report.close()
+	print("SELECTION_OUTPUT: ", output)
 	print("PASS: selection model, server armor and UI assembly")
 	quit()
+
+func _cam_pos(screen: Node) -> Vector3:
+	return screen._cam.position if screen._cam else Vector3.ZERO

project/character_winding_test.gd

@@ -0,0 +1,63 @@
+# Detect CPU animation dropping winding (including accidentally loading an old dylib).
+extends SceneTree
+
+var failures := 0
+
+func _initialize() -> void:
+	call_deferred("run")
+
+func indices(model: Node) -> Array:
+	var meshes := model.find_children("*", "MeshInstance3D", true, false)
+	var out := []
+	for mi in meshes:
+		for s in mi.mesh.get_surface_count():
+			out.append(mi.mesh.surface_get_arrays(s)[Mesh.ARRAY_INDEX])
+	return out
+
+func check_reversed(a: Array, b: Array, stage: String) -> void:
+	if a.is_empty() or a.size() != b.size():
+		failures += 1
+		printerr("FAIL: missing surfaces at ", stage)
+		return
+	for s in a.size():
+		if a[s].size() != b[s].size():
+			failures += 1
+			continue
+		for t in range(0, a[s].size(), 3):
+			if a[s][t] != b[s][t] or a[s][t + 1] != b[s][t + 2] or a[s][t + 2] != b[s][t + 1]:
+				failures += 1
+				printerr("FAIL: winding lost at ", stage, " surface ", s)
+				break
+
+func run() -> void:
+	var base := AssetRoot.path().path_join("PC/ymir work/pc/warrior")
+	var models := []
+	var animations := []
+	for flip in [false, true]:
+		var model: Node = ClassDB.instantiate("Metin2Model")
+		model.set("gr2_path", base.path_join("warrior_novice.gr2"))
+		model.set("hair_gr2", base.path_join("hair/hair_1_1.gr2"))
+		model.set("flip_winding", flip)
+		model.set("lod_enabled", false)
+		root.add_child(model)
+		models.append(model)
+	check_reversed(indices(models[0]), indices(models[1]), "bind")
+	for model in models:
+		var anim: Node = ClassDB.instantiate("Metin2AnimPlayer")
+		anim.set("model_path", model.get_path())
+		anim.set("anim_path", base.path_join("general/wait.msa"))
+		anim.set("playing", false)
+		root.add_child(anim)
+		animations.append(anim)
+	for time in [0.0, 0.5, 1.0]:
+		for anim in animations:
+			anim.set("time", time)
+		check_reversed(indices(models[0]), indices(models[1]), "animated %s" % time)
+		if indices(models[0]).size() != 4:
+			failures += 1
+			printerr("FAIL: body and hair surfaces must both be exercised")
+	print("character_winding_test: failures=", failures)
+	for node in animations + models:
+		node.queue_free()
+	await process_frame
+	quit(1 if failures else 0)

project/hud.gd

@@ -46,7 +46,9 @@ func setup(world: Node, player: Node3D) -> void:
 	_map_h_m = float(rep["map_size_y"]) * 256.0
 	_build_minimap(int(rep["map_size_x"]), int(rep["map_size_y"]))
 	_build_status()
-	_build_hotbar()
+	# 技能快捷栏由 ui/quickbar.gd 管理：它恢复服务端的 36 个槽位、显示
+	# 技能图标并处理冷却。这里以前画的静态空槽会和它重叠，让实际技能看起来
+	# 没有加载，因此 HUD 不再创建第二条快捷栏。
 	_build_inventory()
 	_build_dungeon_compass()
 
@@ -368,22 +370,6 @@ func _build_target_panel() -> void:
 	_target_fill.size = Vector2(180, 12)
 	slot.add_child(_target_fill)
 
-func _build_hotbar() -> void:
-	var row := HBoxContainer.new()
-	row.set_anchors_preset(Control.PRESET_CENTER_BOTTOM)
-	row.position = Vector2(-8 * 23, -56)
-	row.add_theme_constant_override("separation", 4)
-	add_child(row)
-	for i in 8:
-		var slot := _nine("thinboard", 16, 16)
-		slot.custom_minimum_size = Vector2(42, 42)
-		var n := Label.new()
-		n.text = str(i + 1)
-		n.position = Vector2(4, 2)
-		n.add_theme_font_size_override("font_size", 11)
-		slot.add_child(n)
-		row.add_child(slot)
-
 func _build_inventory() -> void:
 	_inv = _nine("board", 32, 128)
 	_inv.set_anchors_preset(Control.PRESET_CENTER_RIGHT)

project/race_spec_test.gd

@@ -19,10 +19,14 @@ class FakeClient extends Node:
 class StubModel extends Node3D:
 	var gr2_path := ""
 	var weapon_gr2 := ""
+	var hair_gr2 := ""
+	var hair_skin := ""
 	var surf := {}
 	func _set(p, v):
 		if p == "gr2_path": gr2_path = v; return true
 		if p == "weapon_gr2": weapon_gr2 = v; return true
+		if p == "hair_gr2": hair_gr2 = v; return true
+		if p == "hair_skin": hair_skin = v; return true
 		return false
 	func set_surface_texture(s, path): surf[s] = path
 
@@ -33,7 +37,10 @@ func _ck(c: bool, m: String) -> void:
 		printerr("FAIL: " + m)
 
 func _init() -> void:
-	_run()
+	call_deferred("_run_and_finish")
+
+func _run_and_finish() -> void:
+	await _run()
 	if _fail == 0:
 		print("PASS: race_spec_test (msm parse + body swap)")
 		quit(0)
@@ -60,6 +67,7 @@ func _run() -> void:
 
 	var rs := RaceSpec.new()
 	_ck(rs.load_file(spec_path), "race spec parsed: %s" % spec_path)
+	_ck(not rs.base_model.begins_with(String.chr(1)), "quoted tokens do not retain lexer sentinel")
 	_ck(rs.shapes.size() >= 5, "shapes parsed (%d)" % rs.shapes.size())
 	_ck(rs.base_model.to_lower().contains("warrior_novice"), "base_model = warrior_novice (%s)" % rs.base_model)
 	var s0: Dictionary = rs.shape(0)
@@ -72,6 +80,15 @@ func _run() -> void:
 	if not h3.is_empty():
 		_ck(h3.get("model", "").contains("hair"), "hair 3 model has 'hair' (%s)" % h3.get("model"))
 		_ck(h3.get("target_skin", "").contains("red"), "hair 3 target_skin = red variant (%s)" % h3.get("target_skin"))
+	# 用户出错的角色用 HairIndex 0；它不是推测的默认路径，必须由 MSM
+	# 明确解析到 hair_1_1，且保持可换的 TargetSkin。
+	var h0: Dictionary = rs.hair(0)
+	_ck(h0.get("path", "") == rs.hair_path and rs.hair_path != "",
+			"empty SpecialPath inherits HairData PathName")
+	_ck(h0.get("model", "").to_lower() == "hair/hair_1_1.gr2",
+			"hair 0 model = hair/hair_1_1.gr2 (%s)" % h0.get("model", ""))
+	_ck(h0.get("target_skin", "").to_lower().contains("warrior_hair_01"),
+			"hair 0 target skin is warrior_hair_01 (%s)" % h0.get("target_skin", ""))
 
 	# --- equip_model 用 race_spec 换身体 ---
 	var fc := FakeClient.new()
@@ -95,3 +112,29 @@ func _run() -> void:
 	if not rs.shape(1).is_empty():
 		_ck(model.gr2_path.to_lower().contains("novice"), "shape 1 -> novice body")
 		_ck(model.surf.has(0), "shape 1 recolour -> set_surface_texture(0, ...)")
+
+	# 标准发型有两段编号：0..5 是 hair_1 的换色，1001..1012 才是
+	# hair_2..4 的不同几何。它们不是道具 vnum，远端/选角不能把它们
+	# 丢给 item_list 后静默回落到 PlayerView 的 hair_1_1 默认模型。
+	var remote_model := StubModel.new()
+	get_root().add_child(remote_model)
+	var remote: Node = EquipModel.new()
+	get_root().add_child(remote)
+	remote.setup_remote(null, func() -> Node: return remote_model, assets, 0,
+			[0, 0, 0, 1001])
+	await process_frame
+	var h1001: Dictionary = rs.hair(1001)
+	_ck(not h1001.is_empty(), "hair 1001 exists in warrior.msm")
+	var remote_h1001: Dictionary = remote._spec_hair(1001)
+	_ck(not remote_h1001.is_empty(), "remote actor resolves hair 1001 (%s)" % remote_h1001)
+	_ck(remote._hair_part() == 1001, "remote actor preserves hair part 1001 (%s)" % str(remote._remote_parts))
+	var remote_hair_model: String = remote._resolve_spec_asset(remote_h1001, String(remote_h1001.get("model", "")))
+	_ck(remote_hair_model != "", "hair 1001 source model path resolves (%s)" % remote_hair_model)
+	# setup_remote refreshes synchronously; this direct retry distinguishes a
+	# setup ordering bug from asset/spec resolution failure.
+	remote._apply_hair_from_parts(remote_model, true)
+	if not h1001.is_empty():
+		_ck(remote_model.hair_gr2.to_lower().ends_with(String(h1001.get("model", "")).to_lower()),
+				"standard hair 1001 resolves MSM geometry (%s)" % remote_model.hair_gr2)
+		_ck(remote_model.hair_skin.to_lower().ends_with(String(h1001.get("target_skin", "")).to_lower()),
+				"standard hair 1001 resolves MSM skin (%s)" % remote_model.hair_skin)

project/skill_test.gd

@@ -319,7 +319,11 @@ func _run() -> void:
 	fc.quickslots = [{"pos": 2, "type": 2, "ref": 16}, {"pos": 3, "type": 1, "ref": 9},
 			{"pos": 4, "type": 3, "ref": 11}]
 	qb2.setup(fc, st, ui, func() -> Node: return pl)   # setup 里自动 restore_from_server
+	_ck(qb2._root.size == Vector2(400, 56) and qb2._root.z_index > 0,
+			"quickbar has a real bottom-anchor extent and stays above legacy HUD")
 	_ck(qb2._state[2].kind == "skill" and int(qb2._state[2].id) == 16, "quickslot 恢复：格2=技能16")
+	_ck(qb2._slots[2].icon.texture != null and qb2._slots[2].icon.visible,
+			"server-restored skill slot renders its icon")
 	_ck(qb2._state[3].kind == "item" and int(qb2._state[3].id) == 9, "quickslot 恢复：格3=道具9")
 	_ck(qb2._state[4].kind == "emote" and int(qb2._state[4].id) == 11, "quickslot 恢复：格4=表情11")
 	qb2.activate(4)

project/ui/char_select_screen.gd

@@ -238,7 +238,7 @@ func _build_stage() -> void:
 	root.add_child(we)
 
 	_pivot = Node3D.new()
-	_pivot.rotation.y = -PI * 0.5
+	_pivot.rotation.y = PI * 0.5
 	root.add_child(_pivot)
 
 	_cam = Camera3D.new()
@@ -254,10 +254,20 @@ func _frame_model() -> void:
 		return
 	var aabb := AABB()
 	var first := true
+	# GPU skinning happens in the vertex shader, so MeshInstance3D's mesh AABB
+	# remains in bind pose.  Prefer the extension's matching deformed bounds for
+	# the main body; accessories continue through their own mesh bounds below.
+	if _pv.model and _pv.model.has_method("get_visual_aabb"):
+		var posed: AABB = _pv.model.call("get_visual_aabb")
+		if posed.size.length_squared() > 0.0:
+			aabb = (_pv.model as Node3D).global_transform * posed
+			first = false
 	for mi in (_pv as Node).find_children("*", "MeshInstance3D", true, false):
 		var m := mi as MeshInstance3D
 		if m.mesh == null:
 			continue
+		if m.get_parent() == _pv.model and m.name == "MeshInstance3D":
+			continue # already covered by Metin2Model.get_visual_aabb()
 		var wb: AABB = m.get_global_transform() * m.get_aabb()
 		aabb = wb if first else aabb.merge(wb)
 		first = false
@@ -274,6 +284,13 @@ func _frame_model() -> void:
 	_cam.position = target + Vector3(0, dist * sin(deg_to_rad(6.0)), dist * cos(deg_to_rad(6.0)))
 	_cam.look_at(target, Vector3.UP)
 
+# Metin2AnimPlayer enables the optional GPU skin path on its first animation
+# sample.  Its material/mesh swap changes the MeshInstance AABB after the
+# initial CPU framing pass, so frame again after the extension confirms it.
+func _on_model_visual_bounds_changed(pv: Node) -> void:
+	if pv == _pv and is_instance_valid(pv):
+		call_deferred("_frame_model")
+
 func _rebuild_model() -> void:
 	if _pivot == null:
 		return
@@ -290,6 +307,8 @@ func _rebuild_model() -> void:
 	_pivot.add_child(pv)
 	if pv.build(_assets, job, pump):
 		_pv = pv
+		if pv.model and pv.model.has_signal("visual_bounds_changed"):
+			pv.model.visual_bounds_changed.connect(_on_model_visual_bounds_changed.bind(pv))
 		if _proto == null and ClassDB.class_exists("Metin2Proto"):
 			_proto = ClassDB.instantiate("Metin2Proto")
 			add_child(_proto)

project/ui/equip_model.gd

@@ -346,11 +346,19 @@ func _resolve_spec_asset(e: Dictionary, rel: String) -> String:
 	var byp := _resolve_asset(String(e.get("path", "")) + rel)
 	if byp != "":
 		return byp
-	# 按 basename 在 pc/<cls>/ 和 pc2/<cls>/ 下找
+	# 规格覆盖层（例如 root/msm/warrior_m.msm）可能只给 Model 名而没有
+	# PathName。按 basename 回退时除职业根目录外，还必须查 hair/；否则
+	# HairIndex 1001..1012 能解析却加载失败，并静默保留 PlayerView 的
+	# hair_1_1 默认模型，造成选角发型遮脸。
 	var bn := rel.get_file()
 	if race >= 0:
 		var cls: String = CLASS_OF[race & 3]
-		for sub in ["PC/ymir work/pc/%s/%s" % [cls, bn], "pc2/ymir work/pc2/%s/%s" % [cls, bn]]:
+		for sub in [
+			"PC/ymir work/pc/%s/%s" % [cls, bn],
+			"PC/ymir work/pc/%s/hair/%s" % [cls, bn],
+			"pc2/ymir work/pc2/%s/%s" % [cls, bn],
+			"pc2/ymir work/pc2/%s/hair/%s" % [cls, bn],
+		]:
 			var q := _resolve_asset(sub)
 			if q != "":
 				return q

project/ui/player_view.gd

@@ -43,6 +43,8 @@ func build(assets_root: String, race: int, pump := Callable()) -> bool:
 
 	model = ClassDB.instantiate("Metin2Model")
 	model.name = "Metin2Model"
+	# PC GR2 surfaces need the same outward winding in bind, CPU and GPU poses.
+	model.set("flip_winding", true)
 	model.set("texture_dir", base)
 	if pump.is_valid(): pump.call()
 	var body := _first_existing([base.path_join("%s_novice.gr2" % cls), base.path_join("%s.gr2" % cls)])

project/ui/quickbar.gd

@@ -339,7 +339,12 @@ func _swap(local_a: int, local_b: int) -> void:
 func _build(parent: Node) -> void:
 	_root = Control.new()
 	_root.set_anchors_preset(Control.PRESET_CENTER_BOTTOM)
-	_root.position = Vector2(-SLOTS_PER_PAGE * 23, -54)
+	# Give the root a real extent.  A zero-sized Control happened to work with
+	# some viewport sizes, but makes anchoring and hit testing fragile on Retina
+	# windows.  The old HUD's empty row then made this look like missing skills.
+	_root.size = Vector2(400, 56)
+	_root.position = Vector2(-200, -62)
+	_root.z_index = 10
 	parent.add_child(_root)
 	var prev := Button.new()
 	prev.text = "‹"

project/ui/race_spec.gd

@@ -57,7 +57,9 @@ func shape(idx: int) -> Dictionary:
 	if e.is_empty():
 		return {}
 	e = e.duplicate()
-	e["path"] = String(e.get("special_path", shape_path))
+	e["path"] = String(e.get("special_path", ""))
+	if e["path"] == "":
+		e["path"] = shape_path
 	e["spec_dir"] = _dir
 	return e
 
@@ -66,7 +68,9 @@ func hair(idx: int) -> Dictionary:
 	if e.is_empty():
 		return {}
 	e = e.duplicate()
-	e["path"] = String(e.get("special_path", hair_path))
+	e["path"] = String(e.get("special_path", ""))
+	if e["path"] == "":
+		e["path"] = hair_path
 	e["spec_dir"] = _dir
 	return e
 
@@ -150,6 +154,8 @@ func _parse_block(toks: Array, i: Array, top := false) -> Dictionary:
 	return d
 
 func _tokval(t):
+	if t is String and t.begins_with(String.chr(1)):
+		return t.substr(1)
 	if t is Dictionary and t.has("str"):
 		return t["str"]
 	return str(t)