gd-object-pool

Reuse objects and nodes in Godot 4 instead of constantly allocating new ones.

Use this addon for bullets, cards, temporary effects, data containers, or any object type that benefits from predictable reuse.

Installation

Via gdam

gdam install @aviorstudio/gd-object-pool

Manual

Copy addon/ into res://addons/@aviorstudio_gd-object-pool/ and enable the plugin.

Quick Start

const ObjectPoolModule = preload("res://addons/@aviorstudio_gd-object-pool/src/object_pool_module.gd")

var pool := ObjectPoolModule.new()
var config := ObjectPoolModule.ObjectPoolConfig.new(100, "reset", Callable())

var obj: Object = pool.get_pooled(MyPooledThing, config)
# Use obj...
pool.return_to_pool(obj, MyPooledThing, config)

Reset Your Objects

Pooled objects should be clean every time they are checked out. Use one of these reset strategies:

• Add a method matching ObjectPoolConfig.reset_method, which defaults to reset.
• Or pass ObjectPoolConfig.reset_callable to reset instances externally.

class_name BulletData

var damage := 0
var target_id := ""

func reset() -> void:
	damage = 0
	target_id = ""

What You Get

• get_pooled: acquire a reused or newly-created object.
• return_to_pool: return an object for reuse.
• warm_pool: pre-allocate objects before gameplay starts.
• get_stats: inspect created, reused, returned, and disposed counts.
• dispose_callable: customize cleanup when a pool is full.

Notes

• No project settings are required.
• Node instances are queued for free when they cannot be retained.
• Keep ownership rules in your game code so pooled nodes are removed from the scene tree before returning them.

Repository Layout

• addon/: Godot plugin source packaged for GDAM and manual installation.
• addon/plugin.cfg: plugin name, version, description, and entry script.
• addon/src/: reusable GDScript modules.
• tests/: Godot test project/scripts for addon behavior.
• .github/workflows/ci.yml: validates package shape and runs tests.
• .github/workflows/release.yml: creates GitHub release ZIPs and publishes to GDAM.

Versioning And Releases

The version in addon/plugin.cfg is the addon package version. Releases are created from main with the manual release workflow and plain semver tags like v0.0.1; the workflow verifies plugin.cfg, builds @aviorstudio_gd-object-pool.zip, and publishes @aviorstudio/gd-object-pool to GDAM.

Testing

Run locally with:

./tests/test.sh

CI runs the same test script when available.

License

MIT