Swarm Kit for Godot 4

Swarm Kit - one Godot 4 node for thousands of enemies, bullets or flock members

Swarm2D is a 2D node for Godot 4.3 and newer: you spawn entities into it, give each one a rule (chase a target, flee, flock, wander, or fly straight), and ask it who got hit. Entities are not nodes, so 20,000 of them add no nodes to the scene tree; their movement, separation and hit tests run in a native extension written in C++, and the zip has libraries for Linux, Windows and macOS.

What it does

• Rules: chase, flee, flock (align, cohere, separate), wander, and straight-flying projectiles with a lifetime.
• Separation between entities, and circle hit tests. The hit radius comes from the entity size, or you set it per entity.
• Health and damage: hurt one entity, or everything inside a circle. Signals tell you when an entity dies (its id, position and a "kind" number you choose) and which entities touch your target.
• Bullets against enemies in one call: collide_with lets every entity of one node damage the entities of another it touches, and either removes the bullet or lets it pierce.
• Queries for the entities inside a circle or a rectangle.
• Ids are 64-bit handles. The id of a dead entity stays dead, even after its slot is reused.

Earlier headless comparison

The supplied benchmark records are from the earlier build, headless (no drawing) on a busy, shared 4-core Linux server. They are not a new benchmark of 0.1.2. The scene: enemies chase a moving target, a turret fires four bullets a frame, bullets die on their first hit, enemies have three hit points. We compared the simulation time of one frame, with Swarm Kit as 1. Roughly how many times as long the alternatives took:

• One Area2D per entity: 12 to 23 times (5,000 and 20,000 enemies; Godot 4.3, 4.5.2 and 4.7.2).
• A packed-array GDScript version with a grid, written by our AI coding agents: 11 to 31 times (same enemy counts and versions).
• A plain one-node-per-enemy loop with no bullets or hit tests: about 2 to 6 times (4.5.2 only). It does no separation.
• 50,000 enemies against 20,000 in Swarm Kit: roughly 3 to 7 times the simulation time (4.5.2 only). Time per frame grows faster than the enemy count.

These are ratios, not frame rates. Drawing is not included, the server is noisy, and a better GDScript version than ours could narrow the gap. Apart from the one reading under Frame rate below, we give no frames per second; the scripts and result files are in the zip so you can measure on your own hardware.

What is in the zip

• The add-on (addons/swarm_kit): the Swarm2D node and its libraries for Linux x86_64, Windows x86_64, macOS arm64 and macOS x86_64 (a debug build for the editor and a release build for exported games, for each).
• A demo scene: a horde of up to 20,000 chasers and a player that fires by itself. The HUD shows pool usage, mode and player touches as a round total. Changing count or mode restarts the round and resets the total. Controls:

WASD / arrows / gamepad: move
1-5: enemy count (500 to 20,000)
F: toggle flocking
B: fire a ring of bullets
R: reset

• A README with a five-minute start and the full list of properties, methods and signals.
• A test suite (87 checks), a fuzz test for bad numbers, a memory soak test, four scenes taken from the proposal (bullet hell, survivors, flock, debris), and the benchmark scripts with their result files.
• The C++ source of the extension with a BUILDING.md, and the MIT licence.

macOS

macOS will block the libraries at first. They are not signed with an Apple Developer certificate or notarised, so the first time Godot loads one from the downloaded zip, macOS says it "could not verify" the file is free of malware and does not open it. Two ways to clear it (alternatives, pick one). To clear every library at once, run this in Terminal, where PATH is the path to the addons/swarm_kit folder in your project:

xattr -dr com.apple.quarantine PATH

Or open System Settings, Privacy & Security, and press Allow Anyway (or Open Anyway, depending on your macOS version) next to the file's name; this route asks once per library. The README has both steps.

Limits

• 2D only. One texture per node, no animation frames (use several nodes).
• Hits are circles: there is no physics-engine collision, no pathfinding and no obstacles.
• No web or mobile builds.
• Separation is a soft push, not a hard collision. When a crowd chases one point, the entities still pack closer than the separation radius.
• Version 0.1.2 is an early release. Coverage includes tests, the demo, the four scenes above and an independent AI audience review using real third-party sprites; no shipped-game validation is claimed.
• macOS blocks the libraries at first (see macOS above).

Where it has run

• Linux: the 87-check suite passed headless on Godot 4.3, 4.4.1, 4.5.2, 4.6.3 and 4.7.2, with both debug and release libraries. Independent AI audience reviewers used the 0.1.2 demo, editor help and a real third-party-sprite integration through the GUI with software OpenGL. This is workflow and drawing coverage, not a frame-rate measurement.
• Earlier Mac observation: the owner ran the 0.1.0 demo in Godot 4.7.2 on one Apple Silicon Mac. It ran and drew. That observation does not test the new libraries.
• Windows/macOS: the 0.1.2 libraries have not been run on those systems; their file formats were checked. If a library fails to load, comment here with your Godot version and console output.

Frame rate

We do not know its frame rate on your machine or with your art. The one reading we have is the owner's: with 20,000 enemies in the 0.1.0 demo on his Apple Silicon Mac, the frame counter stood at about 120 fps most of the time (most likely his display's refresh limit) and dipped to 90 to 100 fps about 2 to 3 seconds in; that is one person's reading on one machine, not a measurement.

Details

• The add-on is aimed at the cases named in Godot's open proposal for a swarm system (godot-proposals#2380): hordes of enemies, bullets, flocks and debris.
• Each node has a fixed capacity, max_count, that you set. A spawn into a full node is refused, and you are told: spawn returns 0, a spawn_refused signal gives the number refused, Godot prints one warning per node, and get_free_count() tells you the room left before you spawn.
• Bad numbers are handled: NaN, infinity and coordinates beyond 1e15 are refused or ignored (spawn returns 0, a bad target keeps its old value), and a negative or NaN time step moves nothing. A fuzz test in the zip covers this.
• Runs on one thread. Two identical runs of the same calls and time steps gave identical positions in our check.
• Some behaviour is easy to trip over, and the README lists it: entity_died fires only for damage (not for kill, clear, expiry or leaving the bounds), piercing bullets hit again on every step while they overlap, negative damage heals, lowering max_count removes the extra entities, and a pattern spawned into a nearly full node loses its last entities (the demo spreads its ring over the room left instead).
• The debug libraries include an in-editor class reference; the README also lists properties, methods and signals. Release libraries omit editor help.
• Rebuilding the libraries needs godot-cpp (not in the zip) and a C++ compiler; BUILDING.md explains it. We did not try rebuilding from the zip.
• If Godot adds a swarm system of its own, it may replace this add-on.

Free alternatives

BlastBullets2D (bullets) and Boids (flocking) are free, MIT-licensed add-ons on the Godot Asset Library. We have not compared speed with them. If you only need bullets, start with BlastBullets2D.

Licence

MIT for the add-on code and the demo. The libraries contain godot-cpp (MIT).

---

Made by Madrasco. AI coding agents wrote the code, tests, README and this page, and scripts ran the tests and benchmarks. The three images are software renders of the swarm's own entity positions from real headless runs, not Godot screenshots and not generative-AI images.

Questions or problems: comment below or email support@madrasco.dev. Platform replies may be AI-assisted; ask to reach the human owner. Not happy with it? Request a full refund within 30 days of purchase.

Not made by or affiliated with the Godot project.