benjivers/val Public Public: anyone can read this; the crew can change it.

# val

Five attackers with the spike, five defenders, abilities on cooldown. First to 13.

A 5v5 played in a browser, from inside the player's head — the map is a tile

grid and the view is a raycaster over it, so there is no 3D library and no

dependency at all. One match is always running on the server: open the page

and you are given a seat in the round that is happening, taken from a bot

where it stands. When a match ends it shows the result for a few seconds and

starts a new one, so nobody ever arrives at a frozen board.

## What is real

Everything that decides a round is computed on the server and only the

server:

- **Movement, shooting and hit detection.** The client sends intent — a

  direction, an angle, a held key — never a position. Damage is by hit

  location (how close the ray passes the target) with falloff and armour:

  a Vandal head shot kills through full armour at any range, a Phantom's

  does not past fifteen metres.

- **Line of sight.** A snapshot only carries the enemies that viewer can

  see. A wall of the map blocks the sight line, a smoke blocks it, a flash

  blinds by the angle you were facing, and a blinded player is sent no

  enemies at all. A dead player watches through their living team mates'

  eyes rather than through walls, so dying is not a wallhack to call out.

  No spawn can see the other spawn: mid is staggered on purpose. A patched

  client learns nothing a plain one does not.

- **The spike.** 100s round, 4s plant, 45s fuse, 7s defuse with a

  checkpoint at 3.5s — a defender killed past half way leaves the defuse

  half done for the next one.

- **Credits.** 800 to start, 9,000 cap, +200 a kill, +300 to the team on a

  plant, loss bonus 1,900 / 2,400 / 2,900. A buy you cannot afford is

  refused server-side.

- **Who is alive.** The roster under the view lists your five with their

  health from the snapshot's own team data, and the kill feed is derived in

  `src/arena.ts` by comparing the players either side of a tick — it carries

  names, the gun and an age, and never a position.

- **Bots** fill every empty seat and use their kit: smokes on the way in,

  flashes before the entry, a recon dart, a molly on the planted spike. They

  shoot through the same spread everyone does, and they aim like something

  with hands: 200–350ms to react to a target they have just seen, an aim

  cone that opens several degrees on the swing and only settles while they

  hold the same target, and more of both when you are crossing their view

  (`src/aim.ts`). Every roll of it comes from the match's seeded random, so

  a seed replays the same round.

Agents: Ember, Veil, Sable, Mender, Rook — two basics bought with credits

(charges last the round), a free signature on a cooldown, and an ultimate

paid for with ult points from kills, plants and the two orbs on the map.

Guns: Classic, Ghost, Sheriff, Spectre, Phantom, Vandal, Operator.

## What is not

- Your own body is *drawn* from a guess — the browser runs your own movement

  forward from your own keys between snapshots, through the same

  step-and-slide the server uses (`src/glide.ts`), and carries the last

  snapshot forward by up to a quarter second of held input. It is a drawing

  optimisation only: nothing is sent, every snapshot leans the drawn body

  back onto the server's answer, and a real disagreement is taken outright.

  The lag your own keys take to reach the server (a send every 50ms, a hop,

  a tick — `LEAD_SLACK` in `static/predict.js`) is not a disagreement: the

  drawn body may lead the answer by that much along the way it is going and

  is left alone there, so a start is not yanked back and a stop is not

  dragged on. Anywhere the server would refuse — a wall, the spawn pen in

  the buy phase, a barrier an ability put up — the drawing holds its last

  good place rather than snapping to the server's. The gun kicks the moment

  the trigger is pulled, and the server's word about the same shot is not a

  second kick; whether it landed is still only the server's to say.

  Where you are *looking* is the browser's too: the mouse moves it at frame

  rate, and the server's angle is taken back only when it is telling you

  something you did not say (`static/yaw.js`).

- Everybody else is drawn by entity interpolation (`static/interp.js`): each

  body keeps the last few snapshots, and the frame is drawn about one

  snapshot interval in the past, between the two that bracket that moment.

  So they move at the speed the server moved them and arrive where it put

  them, one interval late. A missed snapshot is carried one interval further

  and then held. Snapshots are filed under an even clock — one interval

  after the last, nudged a tenth of the way toward when each really landed —

  rather than the moment they happened to arrive, because a rate is not a

  rhythm: thirty a second delivered a few milliseconds early and late is a

  body drawn slow, then fast. The moment being drawn advances at real time

  and creeps toward its delay at no more than two percent of it, so the

  delay adapting never shows as a short frame. Snapshots go out every tick

  (30Hz, some 3.4 KiB a seat) while two or fewer seats are filled, and every

  other tick above that.

- The view is a raycaster: walls are one tile tall and flat-shaded, there is

  no looking up or down, and everything that is not a wall — bodies, the

  spike, ability zones — is a flat billboard scaled by distance and clipped

  against the walls. It is drawn into an offscreen canvas 960 columns wide

  (`static/resolution.js`, never more than the canvas has pixels), one ray

  every other column, and scaled onto the visible one, so the frame costs the

  same on a retina screen as on any other; the crosshair, the HUD and the

  minimap are drawn on top at full device resolution. Columns that would draw

  the same rectangle are batched into one fill (`static/slices.js`), the

  map's tiles are drawn once a size and blitted after that, and if the frame

  still runs over 20ms the render width drops a rung until it fits

  (`static/budget.js`). Fidelity is cheap here and frame rate is not.

  All of it is presentation: the simulation and the snapshots are untouched.

- A body you have only just been shown is faded and grown into sight over a

  tenth of a second, and slid in from the direction it came if it was seen

  near there before; where somebody was last seen alive leaves an outline

  that dims away over a second (`static/presence.js`). The server still sends

  only what you can see — that is the rule, and nothing here bends it. This

  is a drawing about information you already had: an enemy who steps into a

  sightline has no history, and without it they appear mid-stride rather than

  walking into the room.

- One map, one match at a time, ten seats. There is no matchmaking, no

  ranking and no account: your seat belongs to a session cookie, and a

  playing seat is capped one per client address so a cookie — free to mint

  again — cannot buy a second one on the other team. A second machine on a

  second network is still a second person as far as the server can tell,

  the same as any anonymous game without accounts; a socket that does not

  get a seat is sent a spectator view with no position in it, never a side:

  the page draws the score, the round, the clock and the kill feed, says

  which of the two reasons it is watching for, and draws no map and no

  bodies, because it is never told where anybody is.

- No overtime — first to 13 ends it at 12–12 too.

- Sight is a full circle rather than a view cone — you are drawn what is in

  front of you, but the server reveals anything you have line of sight to,

  so a team mate behind you still appears on the minimap. The world has no

  vertical, so the hit location comes from how precisely the shot passes

  the target.

- Assists are counted as a field but never awarded.

- The live match lives in memory and is gone if the process restarts; only

  finished match results are written to SQLite under `FORGE_APP_DATA`.

## Playing

Click the view to capture the mouse, then WASD move and the mouse looks;

**Esc** gives the pointer back. Click fires, **R** reloads, **F** plants and

defuses (hold it), **C / Q / E / X** cast, **B** opens the buy, **Tab**

holds the big map open, **V** swaps to the top-down view, **H** or **?**

brings back the how-to-play card, and **F3** or **`** prints the frame

readout: frame rate, mean frame, snapshots a second, the interpolation delay

in force, the width the world is being drawn at, and how many times the

drawing has taken the server's word outright (your body anchored, somebody

else started again, the view re-pointed) — every one of those is a jump, and

the number a minute is what "it stutters" should be argued with. On a phone

it stays top-down: the left thumb walks and the right thumb aims and fires.

```sh

PORT=8080 FORGE_APP_DATA=./data bun run src/server.ts   # run it here

bun test                                                # the check every pull runs

VAL_URL=http://127.0.0.1:8080 bun run src/tty.ts        # the terminal interface

```

The terminal plays the same match over the same socket: it draws the grid,

the scoreboard and the round, and takes a seat. The exact command that

reaches it is in `FORGE_APP_SSH` when the app runs, and the page prints it.

The forge sets `PORT`, `FORGE_APP_DATA`, `FORGE_APP_ENV`, `FORGE_APP_URL`,

`FORGE_APP_SSH` and `FORGE_APP_COMMIT` when it starts the app; `forge.json`

says how.

## Shape

`src/map.ts` the grid and its geometry · `src/weapons.ts` the damage table ·

`src/economy.ts` credits · `src/abilities.ts` the agent kits ·

`src/match.ts` the round loop (`tick(state, dt)` is the whole game and takes

no clock) · `src/bots.ts` the seats nobody is in · `src/arena.ts` the one

live match and its sockets · `src/server.ts` the door · `static/` the browser client —

`val.js` wires the socket, the keys and the HUD, `raycast.js` is the ray

maths, `scene.js` the first-person view, `slices.js` batches its wall

columns, `resolution.js` and `budget.js` decide how wide to draw it,

`presence.js` fades bodies into sight and marks where they left it,

`topdown.js` the minimap,

`gun.js`, `beep.js`, `steer.js`, `roster.js`, `yaw.js`, `interp.js` and `prompt.js` the rest; the server bundles

them into one content-named file at start-up. The rules are pure functions and the tests play whole matches

headlessly.

## It only runs while somebody is there

The match is not a daemon playing to an empty room. One beat of the clock

happens per tick **while at least one connection is open** — a seat or a

watcher — and freezes otherwise, resuming exactly where it stopped. So the

score you find is the score you left, nothing burns CPU on the box overnight,

and no round is ever decided with nobody watching it.