A swarm should do more than fill the screen
godot-swarm explores large populations of moving agents in Godot, with a path toward reusable gameplay systems. Its custom GPUSwarm3D node exposes behavior, target, population, movement, and presentation controls, while demo scenes make the simulation easy to exercise.
The behavior set includes orbiting, following a target, exploding outward, forming a vortex, and regrouping. The broader interest is what those populations can do in a game: pressure a player, form around an objective, react to obstacles, or return to a gathering point.
Follow the data from simulation to drawing
The project starts with a CPU-driven MultiMesh baseline and adds a GPU compute path. The distinction matters because moving simulation math to a shader is only part of the job. Bringing every agent back to the CPU to prepare its visible transform can reintroduce the bottleneck at the next step.
The current compute architecture keeps agent state and draw data on the GPU, then copies the draw buffer into the MultiMesh rendering buffer. Initialization and rebuilds can still require CPU staging, but the intended steady-state path avoids per-tick agent readback and transform uploads.
Keeping a selectable CPU baseline makes that architecture easier to compare. The project also retains fallback behavior for environments where compute is unavailable.
Local rules, shared motion
The compute work includes spatial neighbor bins, letting agents look at nearby agents rather than relying only on random samples or broad averages. Reusable obstacle helper nodes supply a first approach to avoidance without returning the simulation to a per-agent CPU loop.
These are foundations for richer flocking and steering. They also establish a useful constraint: new behavior should deepen the compute pipeline instead of quietly rebuilding the swarm as thousands of individual scene nodes or physics bodies.
Measure the simulation you actually ran
The benchmark tooling exposes the requested and active backend, agent count, frame rate, effective simulation rate, and upload/dispatch counters. It supports adaptive timing and fixed 60, 30, and 15 Hz targets, with stress presets ranging from 100,000 agents to an experimental one million.
The important comparison is more specific than “how many agents fit on screen?” A run that simulates less often has changed the workload. A GPU request that falls back to CPU has changed the backend. Reporting those conditions makes the measurements useful instead of letting a headline frame rate hide the tradeoff.
The population presets are test scenarios, not a claim that full interactive flocking has been validated at every scale or on every GPU.
What remains experimental
The MultiMesh buffer connection still needs broader renderer and hardware validation. More complete steering, richer obstacle geometry, and a polished reusable addon remain development goals. The million-agent full-behavior target is a research direction rather than a finished capability.
godot-swarm brings together graphics experimentation, behavioral simulation, and diagnostic tooling. The result is a concrete environment for asking where the costs are—and whether moving work onto the GPU actually removes them from the whole simulation-to-drawing path.
UNDER THE HOOD
Architecture & loops
Keep agent data on the GPU
The compute path connects simulation to the visible MultiMesh without per-tick agent readback.
GPUSwarm3D controls
The scene supplies target, behavior, population, movement settings, and obstacle helper data.
GPU agent state + spatial bins
Compute infrastructure groups nearby agents to support local neighbor queries.
Compute update
Update agent state using behavior parameters, local relationships, and obstacle inputs.
GPU draw buffer
Produce the instance data needed to draw the updated swarm.
MultiMesh buffer copy
RenderingDevice copies the draw buffer directly into the MultiMesh GPU buffer.
Visible swarm
Godot draws the instances; the next simulation tick uses GPU-resident agent state again.
Repeat the compute update at the selected simulation rate.
Initial creation and rebuilds can use CPU staging. The CPU fallback is a separate path, and the GPU bridge remains experimental across renderers and hardware.
A benchmark must expose its workload
Backend choice and actual simulation rate are part of the result.
Choose the scenario
Select population, behavior, and requested CPU or GPU backend.
Choose the rate
Use adaptive timing or a fixed 60, 30, or 15 Hz target.
Inspect what actually ran
Record the active backend, effective simulation rate, frame timing, and upload / dispatch counters.
Export and compare
Compare equivalent workloads on the same hardware before attributing a change to the GPU path.
A one-million-agent preset is a stress workload, not proof of full flocking performance at that scale.