extends Node
## Fx — the one place gameplay code fires a visual effect. Code names WHICH effect and WHERE;
## the .tscn owns HOW it looks (colour, curves, emission — all inspector-editable, no recompile).
## Autoload singleton. Usage:  Fx.spawn(&"blood_burst", hit_transform)
##
## Scenes are loaded lazily (not preloaded) so this autoload compiles and boots even before the
## placeholder .tscn are seeded — see tools/seed_fx_placeholders.gd.

const _PATHS: Dictionary = {
	&"blood_burst": "res://systems/fx/blood_burst.tscn",
	&"slam_dust": "res://systems/fx/slam_dust.tscn",
	&"spark": "res://systems/fx/spark.tscn",
	&"hit_flash": "res://systems/fx/hit_flash.tscn",
}

var _cache: Dictionary = {}


# Spawn a named effect at `xform`, parented to `parent` (or the current scene). Returns the
# instance, or null if the effect is unknown or its scene is missing.
func spawn(effect: StringName, xform: Transform3D, parent: Node = null) -> Node:
	var scene := _scene(effect)
	if scene == null:
		return null
	var host := parent if parent != null else _default_host()
	if host == null:
		push_warning("Fx.spawn(%s): no parent and no current scene to attach to" % effect)
		return null
	var inst := scene.instantiate() as Node3D
	host.add_child(inst)
	inst.global_transform = xform
	return inst


func _scene(effect: StringName) -> PackedScene:
	if _cache.has(effect):
		return _cache[effect]
	if not _PATHS.has(effect):
		push_warning("Fx.spawn: unknown effect '%s' (add it to fx/fx.gd)" % effect)
		return null
	var scene := load(_PATHS[effect]) as PackedScene
	if scene == null:
		push_warning("Fx.spawn: scene missing for '%s' at %s" % [effect, _PATHS[effect]])
		return null
	_cache[effect] = scene
	return scene


func _default_host() -> Node:
	var tree := get_tree()
	return tree.current_scene if tree != null else null