# Designing a great game

Voxel Party is a playground of voxel games, every one played in sessions (`vp docs sessions`): a
link, and a friend is playing within a minute. Anything from a 2-player duel to a 16-player
shooter, an obby, an RPG or a tower defense, untimed, people dropping in and out.

The best ones are understood instantly, grab you in the first minute whatever their mood, and give
you a reason to come back: a world worth exploring, something to work towards, a look that feels
finished. Section 0 is the bar for every game; sections 1–7 are the craft behind it.

## Contents
0. The bar
1. The design paragraph
2. Principles
3. Shapes that work
4. Scoring
5. Drama and comebacks
6. Bots that feel human
7. Anti-patterns
8. Idea starters

---

## 0. The bar

The bar: **someone sends a link, and their friend is having fun within 30 seconds.**
- **Drop-in.** Opening the link puts you in the game. No waiting room inside the game, no "wait
  for the next round" if you can avoid it: spawn joiners into the action (safely), and make the
  goal obvious from the first frame. A match-based game may open with a setup menu (options,
  picks, teams: `vp docs menus`), as long as joiners drop into a running match with the defaults
  and a solo player isn't kept waiting.
- **Fun alone, better together.** 1 player should have something to do (targets, waves, a CPU
  rival, a personal best, kept in `storage`: `vp docs api` §16); 2 should be a real match; the
  max should still be readable.
- **Short loops inside a long session.** A round, a life, a wave: something ends and restarts
  every 1–3 minutes, with a scoreboard that shows who's ahead. Either rounds inside one endless
  run, or `flow.end` per match (`vp docs sessions` §5).
- **Controls people already know.** WASD + mouse look + click for a shooter, WASD + pointer for a
  top-down game, Space to jump, Shift to sprint, R to reload. List them on the title card. More
  controls are fine, but each one must earn its place.
- **A clear goal and a clear winner.** "First to 10 kills", "hold the flag for 60 s",
  "survive the wave": on screen, in the blurb, and in the HUD.
- **Juice and feedback on every hit.** Hit markers, a sound for your hits that differs from being
  hit, screen shake, knockback, a kill feed (`flow.hud.banner` for big moments).
- **Respawns, not eliminations**, in drop-in games: nobody should wait more than ~3 s to play.
- **Fair to latecomers:** rounds short enough that joining mid-round doesn't matter, or a
  catch-up (the leader is a target, pickups favour whoever's behind).

The design paragraph (section 1) still comes first. It also names the player range, the controls
(mouse or not), the world and its look, and how a round or match ends.

## 1. The design paragraph

Write this before any code and show it to the user. Example:

> **Counting Sheep** (per-player, 45 s). Sheep leap a fence one after another, some in quick
> bunches and some doubling back. Press **Space** each time a sheep clears the fence; your count
> shows only at the end. After 3 waves, the closest count to the real number wins (score = -|error|,
> ties share). Bots count with a reaction delay and a 10–25% chance of missing a sheep in a bunch.
> 3-second test: a fence, a sheep in the air, a big "COUNT!" sign and a clicker in your hand.

It names the goal, the controls, the length and ending, the scoring, the bots and the first
impression. If you can't write it in one paragraph, the game is too complicated.

**Your version of a game you love** ("my take on that horde-survival hit", "a level in the style
of a classic platformer") is always fair: genres, rules, mechanics, feel and structure are free for
anyone, and remixing them is how games are made. Build it. Make the name and the creative work your
own: an original title, your own characters, art, sounds and level layouts, and genre words (never
the other game's name) in the paragraph, the title card and the listing (`vp docs sharing` §4).

Another example:

> **Snowball Siege** (1–8 players, mouse + keyboard, host-authoritative). A snowy
> fort on a floating island. WASD to run, the mouse to aim, click to throw, Space to jump.
> A hit knocks you back and scores a point; three hits and you pop back at your fort. First to
> 15 wins the round (a banner, confetti, scores reset), and a new round starts at once. Joiners
> spawn at the emptiest fort. CPUs strafe, lead their throws with 150–400 ms reactions and miss
> about a third. 3-second test: snowballs in flight, a big "FIRST TO 15" sign, a crosshair.

## 2. Principles

- **Readable in 3 seconds.** From the title card's blurb and the first frame of play, a new
  player knows what to do. One verb, one goal. The screen shows the goal (a coin, a flag, a sign).
- **Few controls.** Move and one action covers a lot; the mouse and a few more keys (section 0)
  are fine when the game needs them, but the fewer the better.
- **Instant response.** Your character reacts on the frame you press, even online. Netcode never
  gets to make the controls feel slow.
- **Short loops.** Rounds, lives and waves inside a long session. A round that runs long feels
  twice as long when you're losing.
- **Everyone is busy all the time.** No waiting for your turn; if players get knocked out, the
  game should end soon after, or give them something to watch.
- **Interaction beats solitaire.** Bumping, stealing, blocking and racing side by side make
  moments to laugh at. When the game is per-player, show the others (ghosts, a live board) so it
  still feels like a race.
- **Chaos, but fair.** Randomness makes it lively; skill decides it. Everyone faces the same
  seeded layout and the same schedule.
- **Juice.** Every event has a visual, a sound and a little motion. The world reacts: coins
  bounce, crates splinter, the camera shakes.

## 3. Shapes that work

| Shape | How it ends | Examples |
|---|---|---|
| Collect the most | the timer | Coin Cascade, Paint Rush (cover the floor), Fishing Frenzy (heaviest haul) |
| Last one standing | one left (or the timer as a backstop) | Bomb Blitz, Hot Potato, Crumble Tumble, Balloon Bash, Quick Draw |
| Hold the spot | the timer | King of the Hill |
| Race | everyone home, or the timer | Sky Hopper, Mine Cart Rush |
| Rounds of choices or memory | the last round | Treasure Doors, Memory Match, Quick Draw |

## 4. Scoring

Higher is better; tied scores share a place: the session ranks the run.
- Collect: the count.
- Race: `-finishMs`; unfinished runners below every finisher, ranked by how far they got.
- Last one standing: `scoresFromKnockouts(n, groups)` (that is, `-rank`), or the time survived in ms. Players
  knocked out together share a place.
- Rounds: a total over the rounds, or knockout order with a tiebreak (Quick Draw: going out later
  beats going out sooner; within a round the faster shot wins).
- Closest guess: `-|error|`.
Avoid scores that often tie at zero: a round where nobody scores is a flat ending.

## 5. Drama and comebacks

- **A finale.** Something changes in the last 10 seconds: Coin Cascade's COIN FRENZY (coins rain
  three times faster, more big blocks) with `flow.hud.banner` and `flow.intensify()`. The music
  speeds up by itself.
- **Steal and spill.** Bumping a rival makes them drop coins you can grab (Coin Cascade), so the
  leader is a target.
- **Show the leader.** A crown on the leader, a live board, a HUD stat per player.
- **Hidden timers.** Hot Potato's fuse length is secret, so every pass is tense.
- **Fake-outs.** Quick Draw flashes FISH! and FIRM! before FIRE!, so jumping the gun is a real risk.
- **Sudden death** when tied at the end.
- **A last-second swing is possible**, but not a coin flip that erases the whole round.

## 6. Bots that feel human

Every seat must be playable by a CPU, and good bots are what make the game fun offline.
- **A spread of skills**, handed out round-robin (`skillFor`): one sloppy, one steady, one sharp.
  Human-level, not perfect: humans should win often enough to enjoy it.
- **Reaction time**: `Reaction(rand, 0.18, 0.45)` before acting on a cue; think a few times a
  second (`ThinkTimer`), not every frame.
- **Mistakes on purpose**: Quick Draw's bots fall for a fake-out 14% of the time and jump the gun
  3% of the time; Treasure Doors' bots guess at random but shy away from crowded doors.
- **Commitment**: `StickyTarget` keeps a target until something clearly better turns up, so bots
  don't dither between two coins.
- **Weave**: `Wobble` + `steerTo({ weave })` so they don't move like rulers.
- **Manners**: Coin Cascade's bots hold a grudge timer after a bump so they don't stun-lock anyone.
- **Read the game like a human**: a bot sees the landing marker, not the hidden spawn table.
- Test: bots alone must finish a round with varied scores, and the best bot shouldn't win every seed.

## 7. Anti-patterns

- Rules that need a paragraph. If the blurb needs "and" twice, cut a rule.
- Precision or dexterity only a keyboard expert has (fast combos, pixel-perfect jumps).
- A joiner who has to wait, read, or configure anything before playing.
- A game that only works at one player count.
- Long silences: nothing to do for more than ~3 seconds.
- Runaway leaders with no way to catch up.
- Eliminated players staring at nothing for 40 seconds.
- Anything that depends on reading small text mid-game.
- A camera that loses players at the edges, or players too small to tell apart.
- One world object per player that others can't touch: then it's four solo games side by side.

## 8. Idea starters

- **Sky Charge** (host, 2–10, FPS): two teams on floating islands, one plants a charge at one of two sites and the other defends; rounds of 90 s.
- **Block Royale** (host, 1–16, top-down + mouse): the island shrinks; last one on it wins the round.
- **Sky Racers** (per-player, 1–8): laps around a cloud circuit, ghosts of everyone, best lap on the board.
- **Build Off** (discrete, 2–8, mouse): build to a theme in 90 s, everyone votes.
- **Zombie Night** (host, 1–6, FPS co-op): waves of voxel zombies; survive to dawn.
- **Lantern Peak** (host, 1–12, obby): a tall voxel mountain of jumps, swinging logs and crumbling
  bridges, checkpoints as lit lanterns, a best time kept in `storage`.
- **Deep Hollow** (host, 1–4, top-down + mouse, co-op RPG): a dungeon of rooms carved into a hill,
  loot, levels and a boss at the bottom; the next floor deeper every run.
- **Harbour Town** (per-player, 1–16): fish, sell, upgrade your boat and unlock new waters, with
  everyone's catches on a dock board.
- **Lane Siege** (host, 2–8, mouse): build towers along your lane and send creeps down theirs.