Added basic code for a pooled factory.

Author: dr-jam

Projects/spell-factory/scripts/pool_factory/pool.gd

@@ -0,0 +1,59 @@
+class_name Pool
+extends RefCounted
+
+var _prefab: PackedScene
+var _inactive: Array[Node] = []
+var _active: Array[Node] = []
+var _prewarm: int
+var _pool_root: Node  # where pooled nodes live when inactive
+
+func _init(prefab: PackedScene, prewarm: int, pool_root: Node) -> void:
+	_prefab = prefab
+	_prewarm = max(prewarm, 0)
+	_pool_root = pool_root
+	_prewarm_nodes()
+
+
+func _prewarm_nodes() -> void:
+	for i in _prewarm:
+		var n := _instantiate()
+		_idle(n)
+
+
+func acquire() -> Node:
+	if _inactive.is_empty():
+		return _mark_active(_instantiate())
+	var n := _inactive.pop_back() as Node
+	return _mark_active(n)
+
+
+func recycle(n: Node) -> void:
+	if not _active.has(n):
+		return
+	_active.erase(n)
+	_idle(n)
+
+
+func _instantiate() -> Node:
+	var n := _prefab.instantiate()
+	return n
+
+
+func _mark_active(n: Node) -> Node:
+	# visible/ready to use; parent is set by the factory caller
+	n.set_process(true)
+	if n.has_property("visible"):
+		n.visible = true
+	_active.append(n)
+	return n
+
+
+func _idle(n: Node) -> void:
+	# move to pool root, disable processing & hide
+	if n.get_parent():
+		n.get_parent().remove_child(n)
+	_pool_root.add_child(n)
+	n.set_process(false)
+	if n.has_property("visible"):
+		n.visible = false
+	_inactive.append(n)

Projects/spell-factory/scripts/pool_factory/pool.gd.uid

@@ -0,0 +1 @@
+uid://bf1f4hwymbj57

Projects/spell-factory/scripts/pool_factory/pool_tag.gd

@@ -0,0 +1,10 @@
+class_name PoolTag
+extends Node
+# Attached at runtime under each pooled instance
+
+var factory: Node
+var id: StringName
+
+func despawn() -> void:
+	if is_instance_valid(factory):
+		factory.recycle(id, get_parent())

Projects/spell-factory/scripts/pool_factory/pool_tag.gd.uid

@@ -0,0 +1 @@
+uid://c7unljwab3sff

Projects/spell-factory/scripts/pool_factory/pooled_factory.gd

@@ -0,0 +1,74 @@
+extends Node
+class_name PooledFactory
+
+# Register your spawnable types here (or expose as exported dictionary).
+var _registry: Dictionary = {
+	"bullet": preload("res://scenes/fireball.tscn"),
+	"slime":  preload("res://scenes/meteor.tscn"),
+	#"vfx":    preload("res://scenes/ultima.tscn"),
+}
+
+# Per-ID pool settings (optional; defaults used if missing)
+var _settings: Dictionary = {
+	"bullet": {"prewarm": 64},
+	"slime":  {"prewarm": 8},
+	"vfx":    {"prewarm": 16},
+}
+
+var _pools: Dictionary = {} # id -> Pool
+var _pool_root: Node       # hidden container for inactive nodes
+
+func _ready() -> void:
+	_pool_root = Node3D.new()
+	_pool_root.name = "PoolRoot"
+	_pool_root.visible = false
+	add_child(_pool_root)
+	_build_pools()
+
+func _build_pools() -> void:
+	for id: StringName in _registry.keys():
+		var prefab: PackedScene = _registry[id]
+		var prewarm := int(_settings.get(id, {}).get("prewarm", 0))
+		_pools[id] = Pool.new(prefab, prewarm, _pool_root)
+
+# --- PUBLIC API (pool use is transparent) ---
+
+## Spawn an instance by id. Optionally parent it and pass a config dictionary.
+func spawn(id: StringName, parent: Node = null, config := {}) -> Node:
+	var pool: Pool = _pools.get(id)
+	if pool == null:
+		push_error("PooledFactory: unknown id: %s" % id)
+		return null
+
+	var n := pool.acquire()
+
+	# Inject a PoolTag (added once)
+	var tag := n.get_node_or_null("PoolTag") as PoolTag
+	if tag == null:
+		tag = PoolTag.new()
+		tag.name = "PoolTag"
+		n.add_child(tag)
+	tag.factory = self
+	tag.id = id
+
+	# Optional product configuration contract
+	if "configure" in n:
+		n.configure(config)
+
+	# Caller decides parenting; if none provided, keep under factory for convenience
+	if parent:
+		parent.add_child(n)
+	else:
+		add_child(n)
+
+	return n
+
+## Optional: let external scripts explicitly recycle (they don’t have to).
+func recycle(id: StringName, node: Node) -> void:
+	var pool: Pool = _pools.get(id)
+	if pool == null or node == null:
+		return
+	# Allow products to clean up before recycling
+	if "on_recycled" in node:
+		node.on_recycled()
+	pool.recycle(node)

Projects/spell-factory/scripts/pool_factory/pooled_factory.gd.uid

@@ -0,0 +1 @@
+uid://b2uib63wwbp0v