AstroSwarm is a 2D pixel-art tower-defense game (in development) built in Godot 4. It also includes a full swarm-behaviour simulator sandbox: design species, program their behaviour with a drag-and-drop block editor, then record, replay, and export sessions to video. The pixel-art game shell is themed separately from the simulator.
- Player base & progression. A procedurally generated home planet, moons that orbit it and unlock as you level up, an XP bar, and AstroCoin currency — all saved to a local profile.
- Timed Local battles. Deploy a squad from your base to destroy the swarm guarding a central star, then program your ship's flight logic in the Workspace Moon's block editor.
- Benchmarked levels. Three FARP levels: program the defenders for levels 1 and 2 and have your algorithm graded headlessly on the dedicated server, or fly the evader yourself in level 3 against the best algorithm other players have submitted. Every entry is published to the companion website and browsable in-game from My Entries.
- Visual block editor. Build per-species behaviour by stacking condition and action blocks — no coding required.
- Custom species. Tune speed, turn rate, vision range, and field of view, or start from the Hunter, Scout, and Worker presets.
- Resizable arena. Simulate swarms on custom-sized maps with free camera pan and zoom, plus walls and obstacles.
- Save, record & replay. Save setups, record live runs, and scrub them back on an interactive timeline.
- Take-over control. Drive any robot mid-simulation with the keyboard or a gamepad, including a 2-player multiplayer mode.
- Pixel-art game shell. An animated home screen and menus themed independently from the simulator.
- Video export. Render recorded runs to H.264 MP4 via a bundled ffmpeg binary, with one-click reveal in the file manager.
- Open the project in Godot 4.6 (or newer) and press F5.
- From the home screen, choose Play for your base (enter a callsign on first launch), or Simulator for the sandbox.
- In the simulator, pick a species, left-drag to place robots, press Start, then save/replay/export from Manage Setups.
Reached from Play — your home planet sits centre-screen with unlocked moons orbiting it, over the animated starfield:
- Home planet & moons. A procedural Terran-Wet planet plus No-Atmosphere moons, each generated from a saved seed so they look identical every run. Moons revolve on their own random orbits, passing in front of and behind the planet.
- Progression. Earn XP to level up; moons unlock with level (up to 5). AstroCoin is the in-game currency. Username, level, XP, coins, and all seeds persist to a local config file.
- First launch. A modal asks for your callsign before you claim your planet.
The top-right buttons open Moons, Shop (currently disabled), and the ship Workspace; choose a game mode (Timed Local) and press Find Match to play. Online matchmaking isn't wired up yet.
Deploy up to five ships (left-click + drag in your deploy zone) to wipe out the protector swarm orbiting the star before time runs out. Middle-drag to pan, scroll to zoom. Lose your whole fleet and it's game over.
Raiders. A squad of enemy ships defends the protectors. Rather than orbiting, they run a block program of their own: wander the arena, turn away from the star/planet and the outer rim to stay in play, and face-and-fire on any of your ships they spot — so they roam in to intercept your attack.
The Levels screen lists three FARP levels. All three defend (or attack) the same central planet, and all three measure the same three events:
| Event | Definition |
|---|---|
| Detected | The first time any defender sees the evader inside its vision cone. |
| Captured | The first time any defender physically touches (collides with) the evader. |
| Goal time | The time the evader reaches the centre planet. |
Seeing the evader is not enough to stop it — a defender has to reach out and touch it. A run ends on capture (the defenders win) or when the evader reaches the planet (the evader wins).
- Level 1 — Defense · Place. Drag inside the blue ring to place between one and six defenders, aiming each one's vision cone with the drag direction; right-click one to remove it. Program how they all move and scan in the Workspace, then press Launch Evader. Your layout is saved between sessions.
- Level 2 — Defense · Ring. Five defenders are scattered at random positions and orientations inside the ring, spaced apart so they never clump, and you cannot move them — only the algorithm decides the outcome. Reroll scatters them again. The layout on screen when you submit is the one the server benchmarks and the one Level 3 pilots will face, so it is saved between sessions and only Reroll changes it.
- Level 3 — Evasion · Pilot. You fly the evader yourself against the best Level 2 algorithm submitted by another player, standing exactly where that player placed their defenders; their name is shown in the top bar. (With no entries on the server yet, you face a house algorithm on a fixed ring.) Drag on the red ring to pick your start point, then drive with the movement keys from your Settings (WASD or the arrow keys by default). A three-minute countdown runs in the top right. Reaching the planet wins; reaching it without ever being seen is a clean run. Either way the run can be submitted, and reaching the planet is worth a large XP payout.
Each level has a ? Guide button with a step-by-step walkthrough and a list of hints, and it opens automatically the first time you play that level. Ship-to-ship collisions are off by default and can be toggled from the top bar.
| Key | Action |
|---|---|
S |
Start the run |
P |
Replay — reset and try again |
R |
Reroll the defender scatter (Level 2 only) |
They are inert while a run is in progress, since Level 3 steers the evader with the same keys.
Submitting a Level 1 or Level 2 entry uploads your algorithm and placements, and the dedicated server benchmarks them headlessly: the placement runs grade the layout you submitted against many enemy approach angles, then a ring-sweep measures detection and capture rates against defender count. Submitting a Level 3 entry uploads the recorded flight itself — every defender and evader movement — which the server renders into a watchable replay rather than re-simulating.
My Entries lists every entry you've submitted across all three levels, each with a Claim XP button right in the list — it reads Pending until the server finishes processing the entry, and shows the amount once claimed. View opens an info screen pulled live from the server: capture and detection rates plus the outcome breakdown for a benchmarked level, or the result and the detected / captured / reached-planet times for a piloted run. XP is awarded from your best result on a level, so re-claiming a worse entry pays nothing; reaching the planet in level 3 is worth far more than a benchmark run.
- Place robots / deploy ships — left-click + drag (Place Robots tool in the simulator, or inside the deploy zone in Timed Local); the drag direction sets the facing.
- Robot menu — right-click a robot to take over, release, remove, toggle its trail, or pin its coordinates.
- Camera — middle-mouse drag to pan, scroll wheel to zoom.
- Drive a taken-over robot — WASD / arrow keys, or a gamepad's left stick.
Behaviour is built from four block types:
- Config — set a physical parameter (speed, turn rate, vision range, FOV, size).
- Condition — start a rule (On start; Always; When I see anyone / nobody; When I touch or see a wall). The simulator adds When I see / don't see a [species]; the ship workspace instead adds When I see an enemy / ally.
- Logic — branch inside a rule (If I see anyone / an enemy / an ally / an object / a wall / a [species]; If target within / beyond a distance; Else).
- Action — run while the condition holds (move, stop, random walk, turn, face target, flee, throttle, and — in the ship workspace — fire).
Actions placed before any condition run under Always. Random walk steers on a Lévy-flight pattern: mostly short hops with the occasional long straight run. For branching, place an Else block directly after its If at the same level — the Else runs when that If's condition was false.
The FARP ship workspace shares the simulator's block set (minus the variable blocks): it swaps the species conditions for enemy/ally detection, and hides the Fire, Throttle, and Set size blocks, since a FARP defender stops the evader by intercepting it rather than shooting it. Sliders also accept keyboard arrow keys once focused.
| Species | Speed | Turn rate | Vision | FOV | Default behaviour |
|---|---|---|---|---|---|
| Hunter | 5.25 m/s | 3.0 rad/s | 5.5 m | 55° | Face anyone it sees |
| Scout | 3.75 m/s | 2.0 rad/s | 4.5 m | 110° | Random walk |
| Worker | 2.4 m/s | 1.4 rad/s | 3.25 m | 180° | Flee anyone it sees |
All move forward by default; add your own species with the + button.
Starting a run records every robot's position and rotation in the background; on Stop or Clear it's saved as a .run file. Load one from Manage Setups to scrub it back and forth on an interactive timeline.
Right-click a robot and choose Take Over to drive it manually. Control is keyboard-based by default; enable Controller Mode (and Multiplayer for two controllers) in Arena Settings. Controlled robots show a P1/P2 badge — press Esc or the gamepad's B to release. Stopping or clearing the arena releases all of them.
From Manage Setups, Export to Video renders a recorded run to an H.264 MP4 through a bundled ffmpeg binary, then offers a one-click reveal of the output folder.
Display (window mode, resolution, with Apply buttons), graphics (V-Sync, FPS cap, anti-aliasing), rebindable keybinds, audio volumes, and a Player tab to reset your profile — all persisted between sessions.
The project targets Godot 4.6. Clone the repository, open project.godot, and use Project -> Export to build for Linux, Windows, or macOS. See bin/README.md for bundling the ffmpeg binaries used by video export.
Each level ships its own headless benchmarker under simulations/farp/, all sharing BenchBase.gd (argument parsing, the match loop, event tracking, the ring sweep, and the JSON output). The BenchRunner autoload only dispatches: it reads --level-id off the command line and hands the job to the right one.
| Benchmarker | Level | What it does |
|---|---|---|
Level1Bench.gd |
1 | Simulates the submitted placements over many trials. |
Level2Bench.gd |
2 | Simulates the scatter the player submitted, so the score and the layout describe the same thing. |
Level3Bench.gd |
3 | Runs no simulation — it renders the player's recorded flight into a replay. |
The dedicated-server build is what the web worker downloads and runs; see web/worker/README.md.