Add scene-authored FX library and bull ability effects

An Fx autoload + one_shot_effect base so every effect is an inspector-editable .tscn (the systems/fx/ authoring dir): blood/slam/spark/flash primitives and the bull's kick/dash/slam/roll + movement effects (bull_*.tscn), fired via Fx.spawn() / Fx.attach(). Plus a preview gallery + smoke test, and bull_impact_fx.gd for the coded, non-particle slam rings + kick flash-pop. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CCyaJPTHCH9EDthpf4A5Sj
2026-09-08 14:56:01 +03:00
parent 9458085abb
commit c0a022fed4
26 changed files with 1174 additions and 0 deletions
@@ -0,0 +1,71 @@
+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 = {
+	# Generic hit effects.
+	&"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",
+	# Bull ability effects — one-shots fired by spawn(), continuous ones held via attach().
+	&"bull_slam": "res://systems/fx/bull_slam.tscn",
+	&"bull_kick": "res://systems/fx/bull_kick.tscn",
+	&"bull_dash": "res://systems/fx/bull_dash.tscn",
+	&"bull_hoof_dust": "res://systems/fx/bull_hoof_dust.tscn",
+	&"bull_charge_trail": "res://systems/fx/bull_charge_trail.tscn",
+	&"bull_roll_sparks": "res://systems/fx/bull_roll_sparks.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
+
+
+# Instance a CONTINUOUS effect as a child of `parent` and hand it back. Unlike spawn(), it neither
+# positions nor auto-frees the effect — the caller keeps the reference to place it and toggle
+# `emitting` (hoof dust that follows the bull, the charge trail). Returns null if unknown/missing.
+func attach(effect: StringName, parent: Node) -> Node:
+	var scene := _scene(effect)
+	if scene == null or parent == null:
+		return null
+	var inst := scene.instantiate()
+	parent.add_child(inst)
+	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