Elevator pitch

Blessed is a top-down 2D co-operative roguelike wave shooter for 2–4 players. Fight escalating waves of elemental enemies across four planets, collect Zingthons, and reforge your build every wave in a shared card-selection phase — until the run ends in Purgatory or glory.

🚧 TBD — refine the pitch into one marketing-ready sentence.

Genre & inspirations

• Genre: co-op roguelike arena / wave shooter (“horde survival with builds”).
• Primary inspiration for build variety and item breadth: Brotato; co-op session structure closer to Deep Rock Galactic’s “short runs with friends” cadence.

🚧 TBD — competitive analysis: what Blessed does that the inspirations don’t.

Design pillars

1. Co-op first. Every system must work for 2–4 players online — shared card phase, revives, shared economy decisions. Solo is supported but not the design target.
2. Build variety. 70+ weapons in 19 classes, 160+ perks, tiered upgrades — two runs should never feel the same. See Weapons & Tiers and Perks & the Card Phase.
3. Escalating chaos. Waves scale, planets add disasters, and difficulty compounds across a run (see Mechanics for the scaling math).
4. Readable combat. Telegraphed enemy attacks, clear rarity/element color language, pixel-crisp silhouettes.

🚧 TBD — confirm pillars with the team; cut or add.

Platform & audience

• Platforms: Windows and macOS, distributed on Steam (lobbies, achievements) with Discord integration.
• Players: 2–4 online co-op via Steam lobbies; playable solo.
• Session length target: one planet per sitting.

🚧 TBD — target audience definition, age rating, pricing, release window.

The loop

1. Fight a wave — enemies spawn in escalating numbers and strength.
2. Collect Zingthons — currency drops from kills; a magnet radius pulls pickups.
3. Card phase — between waves, each player picks from 3 suggested cards (perks, weapons, upgrades). See Perks & the Card Phase.
4. Repeat with a harder wave. Clear all waves to finish the planet, vote on what’s next, and carry your build forward.

Death sends the run to Purgatory — the end-of-run results flow handled by the Reaper.

Game states

The session state machine (server-authoritative, synced to all clients):

State	Meaning
SetUp	Loading/preparing the wave
Wave	Active combat
ClearUp	Wave over — sweep remaining pickups, reconcile Zingthon counts
Break	Between waves — card phase runs here
PlanetCleared	All waves done; permanent difficulty +1
Voting	Players vote on the next step
Finish / GameOver	Run conclusion paths

Scene flow

MainMenu (shop, character select) → Lobby (Steam matchmaking) → Gameplay ⇄ CardSystem (between waves) → Purgatory (death / results). A PersistentManagers scene stays loaded throughout and hosts the singleton managers.

Pacing

🚧 TBD — target wave duration, break duration, waves per planet, intended run length. (These live in the timer config; document the tuned values once locked.)

Stat system

Every entity (player or enemy) carries the same runtime stat container. Stats cover offense (Damage, Melee/Ranged/Magical Damage, Attack Speed, Critical Chance/Damage), defense (Max HP, HP Regeneration, Armor, Dodge, Knockback Resistance), utility (Speed, Range, Pickup Range, Luck, XP Gain), economy (Allegiance, Loot) and the aura resource (Max Aura, Aura Regeneration, Aura Gain). Buffs and debuffs apply as stat modifiers; perk categories exist as pure tags with no numeric backing.

All formulas — damage composition, crit, armor curve, dodge, caps — are documented with exact numbers on the Mechanics page, which is kept in sync with the code.

Damage model (summary)

• Weapons scale with their wielder’s stats via per-weapon percentage modifiers (e.g. +90% Ranged Damage) — the Brotato model. Details: Mechanics.
• Mitigation order: dodge roll → armor curve → vulnerability multiplier.
• Life steal heals the attacker for a percentage of damage actually dealt.

Aura & abilities

Aura is the ability resource: abilities cost aura and run on cooldowns. Abilities are one universal layer used by both players and enemies:

• Active abilities are driver-fired (player input, or the enemy AI’s intent loop).
• Passive abilities are server-side traits for the owner’s lifetime — the standard telegraphed melee strike, contact damage, on-death loot bursts.

Player ability kits are per-character (bombs, flares, mines, turrets, revives, deployables). Enemy attacks are authored as the same ability assets.

Readability rules

• Every dangerous enemy action has a telegraph: the sprite ramps to a tint over the windup, on every client.
• Rarity tiers and planets each have a fixed color language used across UI, cards and this wiki.

🚧 TBD — friendly fire policy, i-frames/revive rules, status effect roster (stun, plague/vulnerability exist — formalize the full list and stacking rules).

Roster

Five playable classes, each defined by a starting weapon, a signature perk and two special abilities:

Class	Role	Starting weapon	Abilities
Medic	Sustain / revives	Needle	Revive, Medical Crate
Assault	Frontline DPS	Assault Rifle	Bomb, Assault Crate
Sniper	Long-range pick-off	Sniper Rifle	Flare, Scout Crate
Support	Control / utility	Push Gun	Turret, Support Crate
Tank	Anchor / aggro	Giant Hammer	Turret, Support Crate

All classes currently share the same base statline (100 HP, 10 Damage, 5 Speed, 5 Range, 100 Max Aura); identity comes from loadout, not stats.

🚧 TBD — differentiate base statlines per class (e.g. Tank more HP/armor, Sniper more range) and give Tank a unique ability kit (it currently shares Support’s).

Design intent

• A class should be recognizable from its silhouette and its job in the first five seconds of a wave.
• Classes are a starting point, not a straitjacket — the card phase can take any class anywhere.
• Unlock model: characters can carry a price and unlock condition (shop + meta-progression).

🚧 TBD — per-class fantasy blurbs, backstories (see Story & Narrative), planned future classes.

Archetypes

Three weapon archetypes with distinct handling:

• Ranged — projectile or hitscan-style guns; projectiles can pierce, bounce or explode.
• Melee — telegraphed arcs/thrusts with attack type, arc and reach per weapon.
• Throwable — thrown projectiles with explosion stats.

The live roster (currently ~70 weapons) with full per-tier stats is on the weapons index. Examples: Bowrep, Giant Hammer.

Weapon classes

Every weapon belongs to one of 19 classes (Gun, Bow, Medieval, Tech, Wizard, …). Classes group weapons thematically and are the hook for future class-synergy bonuses.

🚧 TBD — class set bonuses (e.g. “3 Medieval weapons → +X%”) are not designed yet; decide whether classes stay cosmetic or become a build axis.

Tier progression

Weapons exist in Tiers 1–5 (the rarity color language). Each tier is a full stat row — damage, cooldown, crit, range, scaling modifiers — authored per weapon. A weapon’s minimum tier gates when it can appear. In-run, higher tiers arrive through the card phase.

• Weapon damage scales with wielder stats via per-weapon percentage modifiers — see Mechanics and any weapon page’s stat table.
• Players hold multiple weapons (slot count is itself a stat) and switch between them.

Weapon traits

Behaviour a stat line can’t express (absorb shots, on-kill effects, cooldown manipulation, replacing the fire action entirely) is authored as trait assets attached to a weapon — server-side hooks around equip, fire, hit, kill and wave events. This is the extension point for “weird” weapons.

🚧 TBD — trait roster per weapon; document each shipped trait on its weapon’s wiki page as they land.

Special placements

Some weapons place objects in the world (e.g. the Ice Wall’s timed obstacle that blocks both allies and enemies).

The card phase

During every Break state, the run switches to the card scene and each player is offered 3 procedurally suggested cards. Cards are the run’s only build lever — weapons, perks and upgrades all arrive through them.

The suggestion system weighs rarity, price, the player’s Zingthons, unlock state and stack limits.

🚧 TBD — document the exact suggestion weighting (luck influence, tag synergy bias, duplicate protection) once tuned.

Perk design space

The perk pool (160+, full list on the perks index) spans three shapes:

1. Stat trades — most perks: plus one stat, minus another (e.g. Quick Feet: +Speed, −Damage). Pure stat modifiers.
2. Custom behaviours — event-driven effects that stats can’t express (e.g. Vampiric Touch: heal on kill), authored as custom effect definitions.
3. Economy / meta perks — shop discounts via Allegiance (e.g. Police Badge), XP gain, pickup radius.

Perk metadata: rarity (Tier 1–5 color language), base price, stack limit, tags (Armor, Speed, LifeSteal… — used for filtering and future synergies), and optional unlock conditions.

Design rules

• Every perk must read in one line on a card. If it needs a paragraph, it’s a trait or an ability, not a perk.
• Trades beat pure buffs: the interesting choice is what you give up.
• Stack limits protect the sim (and the balance) from degenerate stacking.

🚧 TBD — rarity distribution targets per wave band; reroll/banish mechanics (do they exist?); duplicate-pick rules in co-op (can two players take the same card?).

One brain, data-driven

There are no per-enemy AI scripts. Every enemy runs the same generic intent brain; an archetype is authored purely as data — a statline, a movement profile, and a set of granted abilities. Scripted brains exist only as an escape hatch for bosses.

The intent loop: the highest-priority ready active ability drives behaviour — seek its firing range, fire when ready, follow its gated movement (flee, keep distance, hold still) while it cools down; otherwise fall back to the archetype’s default movement profile.

Movement profiles

Approach, Kite, Flee, Pursue, Orbit, Stationary (plus None for inert bodies). Steering is faction-aware with separation, so packs spread instead of stacking.

Enemy attacks are abilities

Melee strikes, ranged weapon bursts, charges, summons (egg-style hatchers), contact damage and death-loot bursts are all the same ability assets players use — telegraphs included. An enemy that fires a weapon literally holds a weapon from the weapon table (e.g. Mud Slinger firing a Sniper Rifle).

Scaling & spawning

• Per-wave growth and the spawn-weight lottery are documented with formulas on Mechanics; each enemy page shows its own scaling projection table.
• Enemies are gated by first appearing wave and grouped by planet — rosters live on the planet pages (Earth, Fire, Water, Wood).
• Spawns use indicators before the enemy appears; co-op lobbies scale enemy HP, damage, speed and wave time through the difficulty multipliers.

Archetype design guidelines

• Every roster needs its melee chaff (e.g. Pebble), a ranged kiter (e.g. Mud Slinger), and at least one special per planet that forces movement.
• An enemy’s danger must be readable from silhouette + telegraph, never from memorized stats.

🚧 TBD — boss design per planet; elite/champion variants; enemy density targets per wave band.

Planets

Runs progress across four elemental planets, each with its own enemy roster, backgrounds and color identity:

Planet	Element / palette	Roster & disasters
Earth	Soil / brown-green	see planet page
Fire	Ember / red-orange	see planet page
Water	Deep blue	see planet page
Wood	Forest green	see planet page

Clearing a planet raises permanent difficulty for the rest of the run (see Mechanics), and triggers the Voting state for what comes next.

Disasters

Each planet has signature disasters — map-level hazards that strike during waves and force repositioning: Vortex pulls everything toward its center, Sandstorm blinds a moving region, Lava Pools cycle open and closed. Full list on the disasters index.

Design intent: disasters attack the space, not the player — they invalidate camping spots and reshape the arena mid-wave.

Maps

🚧 TBD — arena sizes and layouts per planet, obstacle density rules, spawn-point placement rules, trees/destructibles (a perk references tree spawns — formalize the system).

Run structure

🚧 TBD — planet order (fixed or voted?), waves per planet, what carries between planets, run length target, win condition after the final planet.

Currencies & drops

• Zingthons — the run currency. Drops from kills, spent in the card phase. Pickups are collected locally per client during the wave and reconciled at wave end (see Multiplayer & Networking for why).
• Aura — the ability resource, dropped by enemies and regenerated.
• XP — per-enemy XP drops feed player leveling; XP Gain is a stat.
• Consumables & healing — enemies roll a consumable drop rate; healing shards heal a percentage of the picker’s max HP.
• A magnet radius on each player auto-collects nearby drops (Pickup Range stat).

Prices & the Allegiance economy

Cards and shop entries carry base prices per rarity tier. The Allegiance stat moves shop prices (positive = discounts) — several perks trade combat power against economy (e.g. Police Badge, Spray Can). Weapons also carry negative Allegiance modifiers, making strong weapons an economic commitment.

🚧 TBD — price curves per rarity/tier, Zingthon income targets per wave, and the intended economy arc (when should a player afford their first Tier 3?).

In-run progression

Card phase picks: new weapons, weapon tier-ups, perks. Weapon slots are a stat and can grow (e.g. Extra Arm).

Permanent progression (meta)

• Upgrades — permanent purchases (stat effects, rarity, price) bought in the MainMenu shop.
• Unlocks — characters, weapons and perks can carry unlock conditions; achievements and unlock state persist in the global save slot.
• Saves — a global slot (unlocks, achievements, settings) plus a local slot (active run state), JSON on disk.

🚧 TBD — full upgrade tree contents, achievement list, and whether runs are resumable mid-planet.

Model

• 2–4 players online co-op, host-based via Mirror; matchmaking and invites through Steam lobbies. Discord integration alongside.
• The server (host) is authoritative for combat: firing, damage, ability execution and enemy AI all run server-side; clients see synced results.

Authority rules (the important ones)

1. All game state syncs through the standard channels — session state, wave number and player state are server-owned synced values with client hooks.
2. Anything with a real gameplay effect must be a networked object. One object, one pickup — otherwise four clients would each collect their own copy and the effect would fire four times.
3. Cosmetic-or-reconciled things may be client-local. Zingthon pickups deliberately spawn a local copy per client for feel, and counts are reconciled at wave end (ClearUp).
4. Audio that matters is synced through the networked audio path; scene changes go through network-aware loading.

Co-op design consequences

• Difficulty multipliers scale enemy HP/damage/speed and wave time with the lobby (see Mechanics).
• Revives are a class ability (Medic) — death is not necessarily the end of a wave for the team.
• The card phase is shared: all players pick simultaneously during the Break.

🚧 TBD — reconnect/host-migration policy, latency targets, max supported ping, spectating after death, and pause rules in co-op.

Interface stack

• UI Toolkit is the primary UI technology; legacy UGUI remains where Toolkit falls short. All text renders through TextMesh Pro; animated text (cutscenes, flourishes) uses a text-animator layer.

Screens

• Main menu — play, shop (permanent upgrades), character selection, settings.
• Lobby — Steam lobby browser/invites, ready-up.
• HUD (gameplay) — health, aura, weapons, wave timer, Zingthon count.
• Card screen — the 3-card suggestion layout each Break.
• Purgatory — end-of-run results.

🚧 TBD — wireframes/mockups per screen; final HUD layout.

Feedback language

• Popup text — floating damage/loot numbers at the point of impact.
• Notifications — typed system (popup, slide, input prompts) for meta events.
• Telegraphs — enemy windups tint the sprite (see Enemies & AI).
• Color language — rarity Tier 1–5 and the four planet palettes are used consistently across cards, badges and this wiki.

Accessibility

🚧 TBD — colorblind-safe palette check for rarity/planet colors, input remapping, screen-shake/flash toggles, text scaling.

Architecture

• All playback goes through a central audio manager; gameplay-relevant sounds are synchronized across clients through the networked audio path.
• Every clip is referenced through an audio-clip asset wrapper — never a raw clip — so sounds are swappable data.
• Enemies carry per-archetype born/damage/death sound sets, themed per planet (e.g. Earth enemies share an Earth voice set).

Direction

🚧 TBD — music style and per-planet themes, combat mix rules (how many simultaneous hits may sound), wave-start/wave-end stingers, card phase ambience, and the audio identity of Purgatory.

🚧 TBD — this chapter is intentionally empty. The game’s fiction is not in the project yet. The structure below is ready to fill in; names that already exist in the game (Blessed, Purgatory, the Reaper, Zingthons, the four elemental planets) are anchors the fiction should explain.

Premise

Who are the players? Why are they “Blessed”? What are they fighting for?

The world

What are the four planets (Earth, Fire, Water, Wood)? Why are they overrun?

Purgatory & the Reaper

Death takes the run to Purgatory and the Reaper presides. What is this place in the fiction? Why do runs restart?

Zingthons

The currency has a name — give it a story. What is a Zingthon?

Character backstories

One short paragraph each: Medic, Assault, Sniper, Support, Tank.

Tone & delivery

Comedy? Grim? How is story delivered — cutscenes (a cutscene event system exists), item flavor text, environmental?

What exists today

• Top-down 2D with pixel sprites rendered crisp (point filtering / pixelated rendering).
• Sprite pipeline: individual PNGs organized by category (weapons icons + world sprites, enemies per planet, characters with large portrait variants, abilities, per-planet backgrounds).
• Rendering: Unity 6 URP (2D).
• VFX: third-party cartoon/magic effect packs for muzzle flashes, trails, explosions and telegraph flourishes.

🚧 TBD — art direction is otherwise undefined. To write:

• Style guide: resolution/PPU standard, palette (tie into the rarity Tier 1–5 and planet color languages already used by UI), outline rules, animation frame budgets.
• Character/enemy silhouette rules (readability is a design pillar — see Vision & Overview).
• Per-planet environment identity beyond backgrounds.
• VFX language: what color/shape means danger vs. reward; how much screen can effects occupy in 4-player chaos.
• Missing assets: perk icons (perks currently share a default icon) and several weapon/world sprites.