# Swarm MMO — Complete Reference

> A free, persistent browser-based space strategy MMO. Players own planets, grow probe
> swarms, capture suns and black holes, and collapse a galaxy to win it.

## Overview

Swarm MMO is a real-time multiplayer strategy game that runs entirely in the browser.
The universe is persistent: planets keep producing and can be attacked while players
are offline.

**URL**: https://www.swarm-mmo.com (the game itself: https://www.swarm-mmo.com/play)
**Price**: Free. Optional cosmetics only — not pay-to-win.
**Platforms**: Any modern web browser (desktop and mobile), installable as a PWA
**Account**: Optional — play instantly as a guest, link an email to keep progress

---

## World Structure

- The world is a 2D plane on a grid, populated by **galaxies**: procedurally generated
  spiral disks with a dense core thinning into 3-7 arms toward the rim.
- A galaxy disk has a radius of 256 grid units, and galaxies are spaced far enough
  apart that their disks never touch.
- New players spawn only in a galaxy's **outer spawn ring** — beyond 1/√2 of the
  radius, which is exactly the outer half of the disk by area.
- Galaxies are not on a reset timer. New ones are generated as existing ones fill up,
  and a collapsed galaxy frees its space for a new one.
- Zooming far out enters a galaxy-cluster view, where only suns and black holes are
  drawn (planets would be sub-pixel and are not streamed at that scale).

## Planets

- Drawn as circles; size scales with level (1-10). The number on a planet is its
  current probe count.
- Neutral planets are grey; owned planets take their owner's colour.
- **Production**: a level-L planet produces **L probes per minute** (level 1 → 1/min,
  level 10 → 10/min). A clock-like arc around the planet shows progress to the next tick.
- **No capacity and no decay.** Probe counts grow without bound, so holding a large
  stockpile is safe.
- **Upgrading**: costs **100 × level² probes** for the next level — 100 to reach L2,
  400 for L3, 900 for L4, up to L10. Open the planet's menu to upgrade, or turn on
  upgrade automation.

## Combat

- **Launching**: drag from a planet you own to a target and release, then drag the ring
  to choose how many probes to send. Hold 1-9 while dragging to quick-send 10-90%, or 0
  for 100%. The cursor shows travel time while dragging.
- **No attrition in transit.** Every probe launched arrives, and any target anywhere is
  reachable.
- **Intergalactic launches lose more, the younger the target.** The one exception to the
  rule above: if the target lies in a different galaxy than the source, part of the swarm
  is destroyed crossing the border. A galaxy is unreachable for its first 3 days; after
  that the loss falls 10 percentage points a day until it reaches 0% at day 13. The source
  is still debited the full amount, so only what survives the toll ever flies. This
  applies to every tier — probes, super-probes and megaprobes — and to automated relays on
  every firing. The attack dial warns you before you commit.
- **Speed is the cost of distance**, and it depends on **where the swarm launches from**,
  not on how large it is. Swarms launched near a galaxy's rim travel up to **4×** base
  speed; swarms from deep in the core as slow as **¼×**, scaling with distance from the
  galaxy centre.
- **Capture**: arriving probes fight the defending garrison. Finish with more probes
  than the defender and the body changes hands. Probes sent to your own planets, or to a
  clan ally's, **reinforce** them instead.

## Suns

- Suns are objectives with an influence radius of 8 grid units, drawn as a dashed circle.
- **Capture with super-probes**: drag from one of your planets to a sun. On arrival every
  **100 probes becomes 1 super-probe** and any remainder is lost, so an attack must field
  at least 100 probes.
- Suns produce **no** garrison of their own — their super-probes come only from combat and
  reinforcement, so a contested sun changes hands through repeated assaults.
- Each sun you own pays **1 energy per minute**.
- **Sun swarms**: relay super-probes from one sun you own to another. They behave like
  normal swarms (no loss, speed set by the source sun's position in its galaxy).

## Black Holes and Winning

- Every galaxy has one black hole at its core. It starts neutral, holds a garrison of
  **megaprobes**, and stays visible at any zoom level.
- **Attack from a sun you own.** On arrival every **100 super-probes becomes 1 megaprobe**
  (remainder lost), so an attack must field at least 100 super-probes. You can attack a
  black hole in any galaxy, including from a different one.
- **Collapse to win**: own the black hole, build its garrison to **1,000 megaprobes**, then
  choose Collapse.
- Collapsing wipes that entire galaxy — planets, suns, and everyone based there, who
  respawn in another galaxy. The win pays **10,000 energy**; a solo winner takes it all,
  and in a clan win **every member** receives the full 10,000. Energy survives the
  respawn, so a win is a head start on tech.

## Energy and Tech Upgrades

- Energy is a **personal** research currency (never shared within a clan). Sources: 1 per
  minute per sun owned, plus 10,000 for collapsing a galaxy.
- Five upgrades, each up to **level 100**, costing **100 × the next level** in energy
  (100 for L1, 200 for L2, 300 for L3, …).
- Upgrades apply **only** to planets and swarms inside the radius of a sun owned by you or
  a clan ally. Outside a friendly sun's radius, nothing is boosted.
  - **Velocity** (+1%/level): swarms from boosted planets travel faster
  - **Construction** (+0.5%/level): boosted planets produce faster
  - **Defense** (+1%/level): a boosted planet's garrison counts for more when attacked
  - **Toughness** (0.5%/level): that share of probes a boosted planet would have lost in a
    successful defence survives instead
  - **Conversion** (0.5%/level): super-probes cost less to convert when the swarm launched
    from near a friendly sun

## Automation

- **Attack automation**: a planet sends its whole stockpile at a target whenever it
  reaches a threshold you choose (100-10,000). Set it by holding SPACE while dragging, or
  via the radial menu.
- **Sun attack automation**: a source sun forwards super-probes to another sun as soon as
  it has any — useful for relaying reinforcements toward a front. Aimed at a black hole
  instead, it fires at a threshold you pick (100-10,000 super-probes).
- **Upgrade automation**: a planet upgrades itself as soon as it can afford to.

## Commanding Many Bodies

- **Multi-select**: add planets via the Select action in a planet's menu, or Ctrl/Cmd-drag
  a box over the map to select every planet you own inside it. Attacking then launches from
  all selected planets at once, each sending the chosen percentage. Suns have their own
  selection; planets and suns cannot be selected together.
- **Maps** (all free, available when zoomed out):
  - **Strategic**: recolours entities by relation (self / ally / enemy), draws attack
    lines, and blinks any planet or sun under attack
  - **Logistics**: draws your supply lines and blinks your planets missing automations
  - **Default**: normal owner-coloured view

## Clans and Social

- Create a clan or accept an invite. Members are **allies**: swarms sent to their planets
  reinforce rather than attack. The leader manages invites and can kick members.
- A clan win pays every member the full 10,000-energy reward.
- In-game chat, plus a live leaderboard of the top players and clans (also published at
  /leaderboard as a crawlable page).
- Web push notifications for events such as incoming attacks.

## Controls

| Input | Action |
| --- | --- |
| Drag planet | Launch swarm |
| Drag planet → sun | Attack sun (100 probes = 1 super-probe) |
| Hold 1-9 + drag | Quick-send 10%-90% |
| Hold 0 + drag | Quick-send 100% |
| Hold SPACE + drag | Set attack automation |
| Click own planet | Planet menu (upgrade / auto / select) |
| Ctrl / Cmd + drag | Box-select your planets |
| Drag sun | Launch sun swarm |
| Drag sun → black hole | Attack black hole (100 super-probes = 1 megaprobe) |
| Click own black hole | Black hole menu (collapse at 1,000 megaprobes) |
| WASD / Arrows | Pan camera |
| Scroll / + / - | Zoom in / out |
| Drag empty space | Pan camera |

## Credits and Cosmetics

- **Credits** are an optional premium currency bought in the Customize panel. Swarm MMO is
  **not pay-to-win** — credits buy cosmetics and convenience only, never combat power.
- Spend them on animated **skins** for your planets, suns and swarms (visible to everyone),
  an empire **recolour** (50 credits), or a **tech-upgrade reset** that refunds all energy
  spent on tech (500 credits).
- Buying credits and cosmetics requires a verified (email-linked) account.

## Accounts and Sessions

- **Guest play**: starts immediately with a temporary identity, no sign-up.
- **Email linking**: enter an email and receive a magic link — no password. This keeps
  progress across devices and unlocks premium content.
- **Sessions** do not expire; the identity token is kept in local storage.
- **Losing everything**: losing your last planet does not delete your account. You can
  restart from the user panel to respawn with a fresh home planet.
- **Guest cleanup**: guest accounts that never interacted are recycled after 1 hour, and
  idle ones after 7 days. Verified accounts and anyone who bought credits are never
  recycled.

## User Interface

The design is deliberately minimal — the game world *is* the interface.

- Full-viewport canvas, no persistent HUD
- Direct manipulation: drag to launch, scroll/pinch to zoom, drag empty space to pan
- Contextual radial menus and a probe-count ring instead of dialogs
- Two onboarding quests (conquer a planet, upgrade a planet) guide the first minutes
- Installable as a PWA with push notifications

## Frequently Asked Questions

### What is Swarm MMO?
A free, persistent browser-based space strategy MMO. You own planets, produce probes,
launch swarms to conquer enemy territory, capture suns and black holes, and compete for
galactic domination in real time.

### Is Swarm MMO free to play?
Yes, completely free — no download, no installation, no credit card. Optional credits buy
cosmetics only and never affect combat.

### How do I start playing?
Open https://www.swarm-mmo.com and press Play, or go straight to
https://www.swarm-mmo.com/play. You spawn immediately as a guest with a
home planet. No account creation needed.

### What platforms does it support?
Any modern browser on desktop or mobile (Chrome, Firefox, Safari, Edge). It installs as a
PWA to your home screen.

### Do I need an account?
No. Guest play is instant. Linking an email (magic link, no password) keeps your progress
across devices and is required for premium cosmetics.

### What happens while I'm offline?
Your planets keep producing probes, your automations keep running, and other players can
attack you. The world runs 24/7.

### How does combat work?
Drag from your planet to a target and choose how many probes to send. Inside your galaxy
every probe arrives — there is no attrition. On arrival they fight the defending garrison,
and whoever has more left holds the body. Probes sent to your own or an ally's planets
reinforce them.

### Does distance cost me probes?
Inside a galaxy, no — distance costs **time**, not probes. Swarm speed depends on where the
swarm launched from: rim launches are up to 4× base speed, core launches as slow as ¼×.
Crossing into **another galaxy** is the exception: the toll starts at 100% (unreachable)
for the first 3 days a galaxy exists, then falls 10 percentage points a day to 0%.

### How do I win?
Capture the black hole at a galaxy's core, build its garrison to 1,000 megaprobes, and
collapse it. That wipes the galaxy and pays 10,000 energy — the full amount to every clan
member if you are in a clan.

### Can I play with friends?
Yes. Form or join a clan. Clan members are allies whose planets you reinforce instead of
attacking, and a clan win rewards everyone.

### What makes Swarm MMO different from other space strategy games?
- A real win condition (collapse a galaxy) instead of an endless grind
- Zero-friction start: no account, no download, playable in seconds
- No in-galaxy attrition and no capacity caps — the strategic lever is swarm *speed*, set
  by where you launch from. Leaving your galaxy is the one real toll: it costs half the
  swarm, which is what makes a home galaxy worth holding
- Persistent world with automation, so progress continues while you are away
- Minimalist direct-manipulation interface; the map is the whole UI

## Technical Architecture

- **Backend**: SpacetimeDB — persistence, game logic (reducers), and real-time sync
- **Frontend**: React with HTML5 Canvas rendering
- **Networking**: SpacetimeDB subscriptions push state changes; spatial chunking keeps
  subscriptions scoped to the viewport
- **PWA**: service worker plus web push notifications
- **Crawlable pages**: server-rendered wiki (/wiki) and leaderboard (/leaderboard)