control a swarm of boids 🪰 in a vampire survivors-like arena battle

Swarm Roguelike Prototype

A reverse-horde-survival game where you control a swarm of units as a collective. Think Vampire Survivors meets RTS—you position and manage formations while your units auto-attack.

Core Concept

The Hook: You ARE the swarm. Not one hero getting stronger, but an emergent collective that grows, splits, reforms. The identity is the flock itself.

Genre Blend: Survivors-like progression loop (XP → level → pick upgrades) with RTS-style unit composition and formation control. 15-30 minute runs.

Controls

Movement is RTS-style: click to set destination, swarm navigates via boids flocking. Units auto-target and auto-fire at enemies in range.

Player Units

All units use boids flocking (separation, alignment, cohesion). Formation modifies these weights.

Shooter (Blue)

• Role: Balanced DPS
• Stats: Size 6, Speed 1.0, Range 200, Fire Rate 8, Damage 1, Health 2
• Position Bias: Center
• Formation Bonus: Normal → 30% faster fire rate

Tank (Green)

• Role: Frontline, damage sponge
• Stats: Size 9, Speed 0.7, Range 80, Fire Rate 20, Damage 2, Health 5
• Position Bias: Front/edge of swarm
• Formation Bonus:
  • Cluster → 50% damage resistance
  • Disperse → Takes 50% MORE damage (penalty)

Sniper (Pink)

• Role: Long-range glass cannon
• Stats: Size 5, Speed 1.1, Range 350, Fire Rate 25, Damage 3, Health 1
• Position Bias: Back/center of swarm
• Formation Bonus:
  • Disperse → +40% range, +50% damage
  • Cluster → -40% range, -30% damage (penalty)

Visual Feedback

• Green glow: Unit is getting formation bonus
• Red glow: Unit is penalized in current formation
• Health bar: Appears when damaged
• Flash white: Taking damage

Enemy Types

Enemies spawn from edges, frequency increases with difficulty.

Chaser (Red) - Basic

• Behavior: Beelines toward swarm center
• Stats: Size 14, Speed 1.2, Health 5, Damage 1, XP 10
• Unlock: Always available

Spitter (Purple) - Ranged

• Behavior: Maintains distance, shoots projectiles at swarm
• Stats: Size 12, Speed 0.8, Health 4, Range 200, Fire Rate 60
• XP: 15
• Unlock: Difficulty > 1.5

Coward (Yellow) - Runner

• Behavior: Approaches slowly, flees when below 50% health
• Stats: Size 10, Speed 2.0, Health 3, Damage 0, XP 25
• Special: No corpse drop (no new unit spawned)
• Unlock: Difficulty > 1.2

Brute (Dark Red) - Elite

• Behavior: Slow chase, hits HARD
• Stats: Size 24, Speed 0.6, Health 20, Damage 3, XP 40
• Unlock: Difficulty > 2.0

Nest (Brown Hexagon) - Spawner

• Behavior: Stationary, spawns Chasers periodically
• Stats: Size 30, Speed 0, Health 15, Spawn Rate 180 frames, Max Spawns 5
• XP: 50
• Priority Target: Kill before it floods you
• Unlock: Difficulty > 2.5

Formations

Formations modify boids flocking weights AND provide unit-specific bonuses.

Tactical Flow:

• Cluster when enemies close in (protect tanks, shield wall)
• Disperse at range (let snipers do work)
• Normal for general combat (shooter fire rate)

Progression System

XP & Leveling

• Enemies drop blue Energy Orbs on death
• Orbs collected when any boid gets close (radius upgradeable)
• XP fills bar → Level up → Pick 1 of 3 random upgrades
• XP requirement scales: xpToNext = floor(xpToNext * 1.4)
• Difficulty increases by 0.15 per level

Upgrades (Current Pool)

Corpse Consumption

• Dead enemies (except Cowards) leave green Corpses
• Any boid touching corpse consumes it → spawns new random unit
• Corpses fade after ~6 seconds
• Unit type weighted: 60% shooter, 20% tank, 20% sniper

World & Obstacles

• Size: 3000 x 3000 pixels
• Camera: Smoothly follows swarm center
• Obstacles: Perlin noise-generated "coral reef" rocks
  • Scale: 0.012, Threshold: 0.25
  • Hard collision (units pushed out if clipping)
  • Soft avoidance zone around edges
  • Block projectiles (both player and enemy)

Technical Implementation

Stack

• Pixi.js 8.x - Rendering
• Vanilla JS - Game logic
• Single HTML file - No build step

Architecture

State object holds all game data
├── boids[] - Player units (Boid class)
├── enemies[] - Enemy units (Enemy class)  
├── projectiles[] - Player shots
├── enemyProjectiles[] - Enemy shots
├── corpses[] - Consumable remains
├── energyOrbs[] - XP pickups
├── particles[] - Visual effects
├── obstacles[] - Collision geometry
├── camera - Viewport position
└── upgrade state - Multipliers, bonuses

Boids Flocking

Standard separation/alignment/cohesion with:

• Formation modifies weights dynamically
• positionBias offsets target position (tanks front, snipers back)
• Obstacle avoidance as additional steering force
• Hard collision resolution (push out of obstacles)

Performance Notes

• Units rendered as PIXI.Graphics (redrawn each frame for effects)
• Particle pooling would help at scale
• Obstacle collision is O(n*m) - spatial hash would help
• Currently comfortable with ~100 boids + 50 enemies

Future Ideas / TODOs

Enemies

• Boss enemies (every 5 levels?)
• Exploder - suicide bomber, AoE on death
• Shielder - protects nearby enemies
• Splitter - breaks into smaller units on death

Units

• Healer unit type - restores nearby unit health
• Bomber - slow, AoE damage
• Scout - fast, reveals area, no damage

Upgrades

• Formation-specific upgrades (cluster bonus+, disperse bonus+)
• Ability upgrades (dash, AoE burst, temporary shield)
• Evolution system (combine unit types?)
• Weapon variety (piercing, homing, spread shot)

Meta

• Run timer / score
• Death → show stats
• Persistent unlocks between runs
• Different starting loadouts

Polish

• Sound effects
• Music
• Minimap
• Better visual distinction between unit types
• Proper sprite art (replace Graphics)
• Enemy health bars optional/toggle

Technical

• Migrate to Godot for native performance
• Spatial partitioning for collision
• Object pooling
• Mobile touch controls (virtual joystick?)

File Structure

swarm/
├── swarm.html      # Current playable prototype (single file)
├── SPEC.md         # This document
└── assets/         # Future: sprites, sounds

Running Locally

Just open swarm.html in a browser. No server required (loads Pixi from CDN).

For development with hot reload:

npx serve .
# or
python -m http.server 8000

Design Principles

1. The swarm is the character - Never feel like controlling individuals
2. Positioning over aiming - You decide where, they decide how
3. Formation = tactical stance - Meaningful tradeoffs, not just stat boosts
4. Readable chaos - Lots happening, but you can parse it
5. Short sessions - 15-30 minute runs, quick restart
6. Grow or die - Must consume to sustain, risk/reward for corpse collection