mtgodot-poc/project/fx/effect_registry.gd

# EffectRegistry (P5) —— 按名字 / 路径找 `.mse`，缓存解析结果，生成 EffectPlayer。
#
#   var fxr := preload("res://fx/effect_registry.gd").new()
#   fxr.setup(assets_root)
#   fxr.spawn("geompung_3_sword", weapon_bone_node)      # 挂到某节点下播一次性
#   var pv := fxr.spawn_at("hit_spark", world, global_pos)
extends RefCounted

## Lifecycle boundaries of every effect this registry creates. lifetime_ms is the
## MSE-defined length (-1 = looping, lives as long as its owner). fx_finished is
## emitted when the node actually leaves the tree; reason "cleanup" means its own
## playback clock freed it, "removed" means the owner/scene removed it earlier.
signal fx_spawned(effect: String, fx_id: int, lifetime_ms: int)
signal fx_finished(effect: String, fx_id: int, lifetime_ms: int, elapsed_ms: int, reason: String)

const Mse = preload("res://fx/mse.gd")
const EffectPlayer = preload("res://fx/effect_player.gd")

var assets_root := ""
var _path_cache := {}    # name -> abs .mse path ("" = not found)
var _spec_cache := {}    # abs path -> parsed spec
# Process-wide so ids stay unique when GameScene rebuilds its registry.
static var _next_fx_id := 0

var _basename_index := {}    # lowercase basename / filename -> abs path
var _indexed := false

func setup(assets: String) -> void:
	assets_root = assets
	_path_cache.clear()
	_basename_index.clear()
	_indexed = false

func _ensure_basename_index() -> void:
	if _indexed or assets_root == "":
		return
	_indexed = true
	var dirs: Array = [assets_root]
	while not dirs.is_empty():
		var dir: String = dirs.pop_back()
		var da := DirAccess.open(dir)
		if da == null:
			continue
		for f in da.get_files():
			if f.ends_with(".mse"):
				var abs_p := dir.path_join(f)
				var fn := f.to_lower()
				var bn := f.get_basename().to_lower()
				if not _basename_index.has(bn):
					_basename_index[bn] = abs_p
				if not _basename_index.has(fn):
					_basename_index[fn] = abs_p
		for sub in da.get_directories():
			if sub.begins_with("."):
				continue
			var sub_low := sub.to_lower()
			if sub_low in ["map", "sound", "music", "property", "terrain", "tree", "textureset"]:
				continue
			dirs.append(dir.path_join(sub))

# name 可为： 裸名 "xxx"（扫 **/effect/ 下 xxx.mse）· 相对 "effect/xxx.mse" · "d:/ymir work/.../xxx.mse"
func resolve(name: String) -> String:
	if _path_cache.has(name):
		return _path_cache[name]
	var p := _resolve_uncached(name)
	_path_cache[name] = p
	return p

func _resolve_uncached(name: String) -> String:
	if assets_root == "":
		return ""
	var rel := name.replace("\\", "/")
	if rel.length() >= 2 and rel[1] == ":":
		rel = rel.substr(2)
	rel = rel.lstrip("/")
	if not rel.ends_with(".mse"):
		rel += ".mse"
	# 直接 / 散包相对
	for cand in [assets_root.path_join(rel)]:
		if FileAccess.file_exists(cand):
			return cand
	var da := DirAccess.open(assets_root)
	if da:
		for sub in da.get_directories():
			var c := assets_root.path_join(sub).path_join(rel)
			if FileAccess.file_exists(c):
				return c
	# 裸名：从快速特效索引中查找，避免递归全盘扫描造成主线程卡死
	if not name.contains("/"):
		_ensure_basename_index()
		var bn := rel.get_file().get_basename().to_lower()
		if _basename_index.has(bn):
			return _basename_index[bn]
		var fn := rel.get_file().to_lower()
		if _basename_index.has(fn):
			return _basename_index[fn]
	return ""

func spec_for(name: String) -> Dictionary:
	var p := resolve(name)
	if p == "":
		return {}
	if _spec_cache.has(p):
		return _spec_cache[p]
	var s := Mse.new().parse_file(p)
	_spec_cache[p] = s
	return s

# 挂到 parent 下（跟随 parent 变换），播一次性
func spawn(name: String, parent: Node3D, one_shot := true) -> Node3D:
	var s := spec_for(name)
	if s.is_empty() or parent == null:
		return null
	var fx: Node3D = EffectPlayer.new()
	fx.name = "fx_" + name.get_file().get_basename()
	fx.one_shot = one_shot
	fx.build(s, assets_root)
	parent.add_child(fx)
	fx.play(one_shot)
	_track(fx, name)
	return fx

func _track(fx: Node3D, name: String) -> void:
	_next_fx_id += 1
	var fx_id := _next_fx_id
	var lifetime_ms: int = fx.defined_lifetime_ms
	fx.tree_exiting.connect(_on_fx_exiting.bind(fx, name, fx_id, lifetime_ms, Time.get_ticks_msec()),
		CONNECT_ONE_SHOT)
	fx_spawned.emit(name, fx_id, lifetime_ms)

func _on_fx_exiting(fx: Node3D, name: String, fx_id: int, lifetime_ms: int, spawned_ms: int) -> void:
	var reason := "removed"
	if is_instance_valid(fx) and not String(fx.finish_reason).is_empty():
		reason = fx.finish_reason
	fx_finished.emit(name, fx_id, lifetime_ms, Time.get_ticks_msec() - spawned_ms, reason)

# 在世界某点播一次性
func spawn_at(name: String, world_parent: Node3D, global_pos: Vector3, one_shot := true) -> Node3D:
	var fx := spawn(name, world_parent, one_shot)
	if fx:
		fx.global_position = global_pos
	return fx

func spawn_motion(event: Dictionary, view: Node3D, world_parent: Node3D) -> Node3D:
	var effect := spawn(String(event.get("effect", "")), world_parent, true)
	if effect == null:
		return null
	var anchor := preload("res://fx/motion_effect_anchor.gd").new()
	effect.add_child(anchor)
	if not anchor.configure(view, event):
		effect.free()
		return null
	return effect

func spawn_target(event: Dictionary, target: Node3D, world_parent: Node3D) -> Node3D:
	if not is_instance_valid(target) or bool(event.get("fishing_effect", false)):
		return null # Fishing requires its separate water landing position.
	var effect := spawn(String(event.get("effect", "")), world_parent, true)
	if effect == null: return null
	var anchor := preload("res://fx/target_effect_anchor.gd").new()
	effect.add_child(anchor)
	if not anchor.configure(target, event.get("pos", Vector3.ZERO), bool(event.get("following", false))):
		effect.free()
		return null
	return effect