d47a176 · 8cc8a81
@@ -108,11 +108,14 @@
from the angle it subtends, and you turn on the spot.
  knows nothing about de_forge's alphabet), `mesh` (a box builder), `texture`
  (hashed value noise, fbm and an atlas painter), `sound` (a lazy `AudioContext`
  with noise bursts and tones), `loop` (a fixed step with a clamp on a long
  frame), `controls` (a bindings table in, held actions out) and `overlay` (the
  frame), `controls` (a bindings table in, held actions out), `overlay` (the
  2D over the scene: a scale and a pad off the canvas width, scaled fonts,
  panels, aligned and faded text, a crosshair, a bar, right-aligned columns and
  a `m:ss` clock, drawn onto the seventeen members of a 2D context it uses and
  holding no colour a game chose).
  holding no colour a game chose) and `renderer` (the WebGL2: two programs, an
  atlas and named meshes uploaded once at construction, and one `Scene` of
  instances and lines drawn per frame — it knows no game, no world and no
  model, and a canvas and a GL context are named in it only as types).
  Three rules keep it a package, and a test holds each: the engine imports
  nothing outside itself, it needs nothing from a browser to load, and
  everything outside it comes in through one door.
@@ -126,8 +129,10 @@
from the angle it subtends, and you turn on the spot.
  module a bench or a server-rendered page cannot import. (The second process is
  `purity.probe.ts`: a dynamic import is cached per process, so the first load
  of each module has to happen somewhere the engine's own tests have not been.)
  The last two take their clock, their canvas and their window as parameters, so
  the tests drive them with a stub instead of a browser, and `sound` opens its
  `loop`, `controls` and `renderer` take their clock, their canvas, their window
  and their pixel ratio as parameters, so the tests drive them with a stub
  instead of a browser — `renderer.test.ts` uploads meshes and draws frames into
  a context that only writes down what it was asked for — and `sound` opens its
  `AudioContext` on the first sound rather than on load.
- `src/engine/index.ts` — the door, and the rule is that a second game imports
  `src/engine/index.ts` and nothing deeper; inside the engine, modules import
@@ -143,8 +148,10 @@
from the angle it subtends, and you turn on the spot.
  `sound` `attenuate`, `createSoundDevice`, `Burst`, `Tone`, `SoundDevice` and
  `Ctor`; from `loop` `createLoop`, `Frames`, `Loop` and `LoopOptions`; from
  `controls` `createControls`, `attachButtons` and the event and option types
  they are driven with; and from `overlay` `overlay`, `Overlay` and the `Paint`
  a 2D game draws onto. `boundary.test.ts` fails a deep import from outside, a
  they are driven with; from `overlay` `overlay`, `Overlay` and the `Paint`
  a 2D game draws onto; and from `renderer` `createRenderer` with `Renderer`,
  `RendererAssets` and the frame it draws — `Scene`, `Camera` and `Instance`.
  `boundary.test.ts` fails a deep import from outside, a
  module that is not behind the door, and any change to that list of names that
  is not also a change to the list written out in the test. One exception, and
  it is written down there too: a `.test.ts` may import another `.test.ts`, which
@@ -160,16 +167,17 @@
from the angle it subtends, and you turn on the spot.
  over the engine's grid), `physics`, `weapons`, `combat`, `match` (the rules),
  `world` (the simulation),
  `bots`, `observe`, `action`, `policy`, `weights`, `models`, `materials`,
  `binding`, `scene`, `renderer`, `hud`, `audio`, `main`. Everything is headless
  and tested but `renderer`, which is the one module that needs a real WebGL2
  context; `models`, `materials` and `audio` are this game's recipes for the
  engine's three asset tools, and `binding` is its key table and the one
  `binding`, `scene`, `hud`, `audio`, `main`. Everything in here is headless and
  tested: the WebGL2 is the engine's now, and this game has no renderer of its
  own. `models`, `materials` and `audio` are this game's recipes for the
  engine's three asset tools — `main` builds the atlas and all eight meshes at
  start-up and hands them to `createRenderer`, which keeps them by name — and
  `binding` is its key table and the one
  function from a held action to an `Input`. `scene` is the frame as data —
  `buildScene(world, camera, into)` fills one scene object with the camera, the
  sky, the instances to draw in the order to draw them, the line vertices every
  tracer and spark and beam comes to, and the gun in your hands — and `renderer`
  draws that and nothing else: it names no world, no physics and no weapons, so
  a second game can hand it a scene of its own. Which is why every decision
  tracer and spark and beam comes to, and the gun in your hands — and the
  engine's renderer draws that and nothing else. Which is why every decision
  about a frame — who is drawn, how far a duck squashes them, how long a tracer
  lives, how far the last shot kicked the view model — is checked in
  `scene.test.ts` with no canvas in the room. Nothing is allocated per frame:
@@ -36,7 +36,12 @@
export type Entry = { name: string; entry: string; ceiling: Ceiling };
 * this ceiling raised, and #18 takes the same bytes back out of the shooter.
 * The app grew 1,254 bytes for #47, which moved every decision about a frame
 * into `src/client/scene.ts`; it fits under today's ceiling, so no ceiling moved
 * with it. The range's ceiling was raised for #41, which gave it a game: the targets,
 * with it. It grew another 830 raw / 701 gzipped for #48, which moved the
 * renderer behind the door: the game now builds all eight of its meshes and
 * hands them in at construction rather than uploading each on the frame that
 * first asks for it. Measured after #48: app 70,558 raw / 32,850 gzipped,
 * range 12,548 raw / 5,729 gzipped — the range is unchanged in size, which is
 * the tree-shaking working: it imports the door and none of the WebGL2 behind it. The range's ceiling was raised for #41, which gave it a game: the targets,
 * the clock and the score, the shot traced through the engine's `rayBox`, and
 * the blips the horizon draws them as.
 * Raising a ceiling is allowed, and it is a line in the pull that says what was
@@ -13,7 +13,8 @@
 */
import { expect, test } from "bun:test";
import { boot, type Frame } from "./main.ts";
import { boot, gameMeshes, type Frame } from "./main.ts";
import { WEAPONS } from "./weapons.ts";
import { parseResult } from "../result.ts";
import { fakeStage, type FakeStage } from "./stage.test-helper.ts";
import type { World } from "./world.ts";
@@ -298,3 +299,21 @@
test("no WebGL2 is a sentence on the page, not an exception", () => {
  expect(stage.document.listening.size).toBe(0);
  expect(stage.draws.length).toBe(0);
});
test("every mesh name a scene of this game can place is handed in at construction", () => {
  // The renderer keeps what it is given and resolves nothing, so a name this
  // table misses is an exception on the frame a player first holds that gun.
  const meshes = gameMeshes();
  expect(Object.keys(meshes).sort()).toEqual([
    "bomb", "knife", "level", "pistol", "player", "rifle", "smg", "sniper",
  ]);
  // Every kind a weapon can be, and the kind `scene.ts` falls back to.
  for (const weapon of Object.values(WEAPONS)) expect(meshes[weapon.kind]).toBeDefined();
  expect(meshes["rifle"]).toBeDefined();
  // And each one is geometry, not an empty buffer.
  for (const [name, mesh] of Object.entries(meshes)) {
    expect(mesh.index.length).toBeGreaterThan(0);
    expect(mesh.position.length).toBe((mesh.index.length / 6) * 4 * 3);
    expect(name).toMatch(/^[a-z]+$/);
  }
});
@@ -2,7 +2,8 @@
 * The frame. The engine's loop says how many 64 Hz steps this frame is worth
 * and the engine's controls say which actions are held; `binding` turns those
 * names into the `Input` the world takes. `scene.ts` then turns the world into
 * the frame's data and the renderer draws that, and the HUD is painted on top. The page's overlays — menu, buy, pause — are plain DOM, so they are
 * the frame's data and the engine's renderer draws that — built here, from this
 * game's atlas and this game's meshes — and the HUD is painted on top. The page's overlays — menu, buy, pause — are plain DOM, so they are
 * reachable with a keyboard and big enough for a thumb.
 *
 * Nothing in here is a browser. `boot(host)` takes everything it reaches for —
@@ -18,12 +19,14 @@
import { createAudio, type Audio } from "./audio.ts";
import { CS_KEYS, CS_MOUSE, CS_TAP, readIntent } from "./binding.ts";
import { drawHud, type Paint } from "./hud.ts";
import {
  attachButtons, clamp, createControls, createLoop, type Button, type Listens,
  attachButtons, clamp, createControls, createLoop, createRenderer, type Button, type Camera,
  type Listens, type Mesh,
} from "../engine/index.ts";
import { COMPETITIVE, SHORT, type Rules } from "./match.ts";
import { createRenderer } from "./renderer.ts";
import { buildScene, createScene, type Camera, type Scene } from "./scene.ts";
import { buyable } from "./weapons.ts";
import { LAYERS, TEX_SIZE, materialTextures } from "./materials.ts";
import { meshFor } from "./models.ts";
import { buildScene, createScene, SKY, type Scene } from "./scene.ts";
import { buyable, WEAPONS } from "./weapons.ts";
import {
  buy, canBuy, createWorld, eyePos, priceOf, update, type BuyItem, type Player, type World,
} from "./world.ts";
@@ -355,11 +358,32 @@
export function boot(host: Host): Frame {
  return { world: () => world };
}
/**
 * Every mesh a scene of this game can name, built once and handed to the
 * renderer at construction: the level, a player, the bomb, and one view model
 * per weapon kind. The renderer keeps what it is given by name and resolves
 * nothing itself, so this table and `models.meshFor` are the whole of what the
 * engine would otherwise have had to know about this game's geometry.
 *
 * Exported because a name this misses is a crash mid-match — the first frame a
 * player picks that gun up — and `main.test.ts` holds it against every name
 * `scene.ts` can place.
 */
export function gameMeshes(): Record<string, Mesh> {
  const kinds = new Set(Object.values(WEAPONS).map((weapon) => weapon.kind));
  const names = ["level", "player", "bomb", ...kinds];
  return Object.fromEntries(names.map((name) => [name, meshFor(name)]));
}
/**
 * The browser, and the only place in this file where one is named: the real
 * document, window, store, network, ids and factories, handed in as a host.
 * The cast is the seam — `createRenderer` wants a real canvas, and a `Stage` is
 * the smaller shape this file and a test can both satisfy.
 * The cast is the seam — the engine's `createRenderer` wants a real canvas, and
 * a `Stage` is the smaller shape this file and a test can both satisfy — and
 * the assets beside it are this game's, which is why they are passed in here
 * rather than reached for behind the door: the atlas `materials.ts` paints, the
 * size and layer count it painted at, the meshes above, the horizon a frame
 * that named none would get, and the pixel ratio of the screen we are on.
 */
const browser = (): Host => ({
  document,
@@ -367,7 +391,13 @@
const browser = (): Host => ({
  storage: localStorage,
  fetch: (url, init) => fetch(url, init),
  randomUUID: () => crypto.randomUUID(),
  createRenderer: (canvas) => createRenderer(canvas as unknown as HTMLCanvasElement),
  createRenderer: (canvas) =>
    createRenderer(canvas as unknown as HTMLCanvasElement, {
      atlas: { bytes: materialTextures(), size: TEX_SIZE, layers: LAYERS },
      meshes: gameMeshes(),
      sky: SKY,
      devicePixelRatio: () => window.devicePixelRatio,
    }),
  createAudio: () => createAudio(),
});
@@ -66,9 +66,10 @@
export function viewModelMesh(kind: string): Mesh {
/**
 * A mesh by the name a scene calls it: `level`, `player`, `bomb`, or a weapon
 * kind for the gun in your hands. The renderer keeps one upload per name and
 * never learns what a name is made of — that is this file, and this is the one
 * line a second game's model table would replace.
 * kind for the gun in your hands. `main.ts` builds one of each at start-up and
 * hands them to the engine's renderer, which keeps them by name and never
 * learns what a name is made of — that is this file, and this is the one line a
 * second game's model table would replace.
 */
export function meshFor(name: string): Mesh {
  if (name === "level") return levelMesh(boxes);
@@ -5,16 +5,17 @@
 * squashes a player, how long a tracer lives, which gun is in your hands and
 * how far the last shot kicked it — is a number a test can read.
 *
 * The last test is the boundary itself: the renderer may not name the world,
 * the physics or the weapons again, because a second game that hands it a scene
 * would have neither.
 * The last test is the boundary itself: the drawing is `src/engine/renderer.ts`
 * now and the `Scene` it reads is the door's type, so what this file decides is
 * exactly what any game's renderer is handed.
 */
import { expect, test } from "bun:test";
import { readFileSync } from "node:fs";
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import type { Camera } from "../engine/index.ts";
import { HULL } from "./physics.ts";
import { buildScene, createScene, LINE_CAPACITY, SKY, type Camera } from "./scene.ts";
import { buildScene, createScene, LINE_CAPACITY, SKY } from "./scene.ts";
import { SHORT } from "./match.ts";
import { createWorld, type Effect, type World } from "./world.ts";
@@ -223,11 +224,14 @@
test("a frame allocates nothing: the same scene, the same buffer, the same insta
  expect(scene.viewModel).toBe(held);
});
test("the renderer names no world, no physics and no weapons", () => {
  const source = readFileSync(join(import.meta.dir, "renderer.ts"), "utf8");
  for (const forbidden of ["./world.ts", "./physics.ts", "./weapons.ts", "./map.ts"])
    expect(source).not.toContain(forbidden);
  expect(source).toContain('from "./scene.ts"');
  expect(source).toContain('from "./models.ts"');
  expect(source).toContain('from "./materials.ts"');
test("this game has no renderer of its own: the frame is the door's type", () => {
  // The WebGL2 is `src/engine/renderer.ts` now, and `boundary.test.ts` holds it
  // to importing nothing but the engine. What is left here is the scene, whose
  // type comes through the door — so what this game decides about a frame and
  // what any game's renderer reads of it are the same thing by construction.
  expect(existsSync(join(import.meta.dir, "renderer.ts"))).toBe(false);
  const source = readFileSync(join(import.meta.dir, "scene.ts"), "utf8");
  expect(source).toContain("type Scene as Frame");
  expect(source).toContain('from "../engine/index.ts"');
  expect(source).toContain("export type Scene = Frame &");
});
@@ -2,9 +2,10 @@
 * The frame, as data. Everything a draw has to decide about this game — which
 * mesh stands where, what a team is tinted, how far a tracer has faded, which
 * gun is in your hands and how far the last shot kicked it — is decided here,
 * in plain numbers a test can read without a canvas. `renderer.ts` then draws
 * exactly this and knows nothing else, which is what lets a second game hand it
 * a scene of its own.
 * in plain numbers a test can read without a canvas. The engine's renderer then
 * draws exactly this and knows nothing else, which is what lets a second game
 * hand it a scene of its own: `Scene`, `Camera` and `Instance` are the door's
 * types, and what is added below is only what this game keeps between frames.
 *
 * Nothing is allocated in a frame. `createScene()` makes the one scene and the
 * one line buffer a game ever needs, and `buildScene(world, camera, into)`
@@ -13,37 +14,24 @@
 * and the view model object is kept even on the frames where there is none.
 */
import { clamp, type Vec3 } from "../engine/index.ts";
import { clamp, type Camera, type Scene as Frame, type Vec3 } from "../engine/index.ts";
import { HULL, hullHeight } from "./physics.ts";
import { WEAPONS } from "./weapons.ts";
import type { World } from "./world.ts";
/** Where the eye is and what it can see. A horizontal field of view, as CS reports it. */
export type Camera = { pos: Vec3; yaw: number; pitch: number; fov: number };
export type Tint = [number, number, number];
/**
 * One mesh, placed. `mesh` is the name the renderer resolves — `level`,
 * `player`, `bomb`, or a weapon kind for a view model — and `scale` is the
 * vertical squash a duck applies, the only scaling this game asks for.
 */
export type Instance = { mesh: string; pos: Vec3; yaw: number; scale: number; tint: Tint };
/** The gun in your hands: which one, and where it sits in view space. */
export type ViewModel = { mesh: string; offset: Vec3 };
export type Scene = {
  camera: Camera;
/**
 * The engine's frame, plus this game's memory of the last one. The mesh names
 * placed below — `level`, `player`, `bomb`, and a weapon kind for a view model
 * — are the names `main.ts` hands the renderer at construction.
 */
export type Scene = Frame & {
  /** This game's horizon is never not named: `SKY`, written in every frame. */
  sky: Tint;
  /** The pool. Only the first `instanceCount` of these are this frame's. */
  instances: Instance[];
  instanceCount: number;
  /** Line vertices, six floats each: x, y, z, r, g, b. */
  lines: Float32Array;
  /** Vertices written this frame — `lineCount * 6` floats of `lines` are live. */
  lineCount: number;
  viewModel: ViewModel | null;
  /**
   * What the scene remembers between frames so a frame allocates nothing: the
   * walk cycle the view model bobs on, the world time it last saw, and the one
@@ -273,6 +273,54 @@
o.panel(pad, pad, width - pad * 2, step * lines.length + pad, "rgba(11,13,17,.72
o.crosshair(Math.round(width / 2), Math.round(height / 2), 0, Math.max(6, Math.round(width / 90)), "#8ea");
```
### renderer
The 3D under the scene, and the largest thing behind the door. `createRenderer`
takes the canvas and the assets and hands back a `Renderer` — or nothing at all,
when the browser has no WebGL2, which is a sentence to show the player rather
than an error — with three members: `Renderer.draw` for one frame,
`Renderer.resize` for the canvas in device pixels, and `Renderer.gl` for the
context itself, if a game ever wants a pass of its own.
What a game brings is `RendererAssets`, and every byte of it is uploaded once,
at construction. `RendererAssets.atlas` is the `TEXTURE_2D_ARRAY` every mesh's
layer indexes into: a size, a layer count, and exactly what `paintAtlas`
returns at that size. Neither number is assumed — a game that paints 64-pixel
tiles says 64 — so bytes of any other length are refused with both numbers in
the message. `RendererAssets.meshes` is every `Mesh` a scene of this game can
name, under the name its instances will ask for.
`RendererAssets.sky` is the horizon for a frame that names none, and
`RendererAssets.devicePixelRatio` is `window.devicePixelRatio` handed in as a
function, because the engine reads no global and a test drives a whole frame
with no window in the room.
```ts
// src/client/main.ts
createRenderer(canvas as unknown as HTMLCanvasElement, {
  atlas: { bytes: materialTextures(), size: TEX_SIZE, layers: LAYERS },
  meshes: gameMeshes(),
  sky: SKY,
  devicePixelRatio: () => window.devicePixelRatio,
}),
```
Then every frame is a `Scene`: a `Camera` — a position, a yaw, a pitch and a
horizontal field of view — the sky this frame clears to and fades into, a pool
of `Instance` values of which the first `Scene.instanceCount` are live, each a
mesh name with a place, a yaw, a vertical squash and a tint; one
`Float32Array` of line vertices of which the first `Scene.lineCount` are live,
six floats each for a tracer or a spark; and `Scene.viewModel`, when there is a
gun in your hands. Fill one scene object every frame rather than making one —
`src/client/scene.ts` allocates nothing per frame and is worth copying — name a
mesh that was never handed in and the draw throws with that name in the
message, and remember that nothing in a draw animates itself: a bob, a fade or
a tint is a decision, and decisions are the game's.
```ts
// src/client/main.ts
renderer.draw(buildScene(world, camera, frameScene), elapsed);
```
## The seam, named as pairs
Two games exist here, and every place they differ is a place the engine chose to
@@ -288,7 +336,7 @@
split.
| mesh recipes | `src/client/models.ts` | none: it draws no geometry yet |
| texture recipes | `src/client/materials.ts` | none: the readout paints its own 2D |
| sound recipes | `src/client/audio.ts` | none yet |
| a renderer | WebGL2, `src/client/renderer.ts` | a 2D horizon, `src/range/readout.ts` |
| renderer assets | an atlas and eight meshes, from `src/client/main.ts` | none: it draws a 2D horizon in `src/range/readout.ts` |
| the tuning | `src/client/physics.ts`, `src/client/weapons.ts` | `targets.STANDARD` in `src/range/targets.ts` |
## What the engine deliberately does not know
@@ -220,12 +220,13 @@
test("no module in the engine goes through the engine's own door", () => {
 * copy of the surface, read twice, rather than two that drift.
 */
export const SURFACE = [
  "Box", "Builder", "Burst", "Button", "ButtonOptions", "Controls", "Ctor", "Frames", "Grid",
  "Hit", "Host", "KeyEventish", "Listens", "LockOwner", "Loop", "LoopOptions", "Mat4", "Mesh",
  "MouseEventish", "Options", "Overlay", "Paint", "Shader", "SoundDevice", "Stick", "Surface", "Tone",
  "Box", "Builder", "Burst", "Button", "ButtonOptions", "Camera", "Controls", "Ctor", "Frames",
  "Grid", "Hit", "Host", "Instance", "KeyEventish", "Listens", "LockOwner", "Loop", "LoopOptions",
  "Mat4", "Mesh", "MouseEventish", "Options", "Overlay", "Paint", "Renderer", "RendererAssets",
  "Scene", "Shader", "SoundDevice", "Stick", "Surface", "Tone",
  "TouchEventish", "Touchish", "Vec3", "add", "addBox", "angleDelta", "angleVectors",
  "attachButtons", "attenuate", "builder", "cellAt", "clamp", "colOf", "createControls",
  "createLoop", "createSoundDevice", "cross", "deg", "dist", "dist2d", "dot", "fbm",
  "createLoop", "createRenderer", "createSoundDevice", "cross", "deg", "dist", "dist2d", "dot", "fbm",
  "findPath", "finish", "hash", "inside", "length", "length2d", "lerp", "mat4", "mergeSolid",
  "modelMatrix", "mul", "multiply", "noise", "normalize", "overlay", "paintAtlas", "perspective",
  "quadMesh", "rad", "rayBox", "rng", "rowOf", "scale", "segmentLength", "sub", "traceWorld",
@@ -48,8 +48,9 @@
const BARE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 * this file ignores without needing to be told about it.
 */
const NOT_THE_ENGINES = new Set([
  "AudioContext", "Float32Array", "addEventListener", "cancelAnimationFrame", "de_forge",
  "pointerLockElement", "removeEventListener", "requestAnimationFrame", "uniformMatrix4fv",
  "AudioContext", "Float32Array", "TEXTURE_2D_ARRAY", "addEventListener", "cancelAnimationFrame",
  "de_forge", "pointerLockElement", "removeEventListener", "requestAnimationFrame",
  "uniformMatrix4fv",
]);
const guide = (): string => readFileSync(GUIDE, "utf8");
@@ -52,3 +52,7 @@
export type {
/** The 2D over the scene: panels, scaled text, a crosshair, a bar and a clock. */
export { overlay } from "./overlay.ts";
export type { Overlay, Paint } from "./overlay.ts";
/** The WebGL2 draw: an atlas and named meshes in, a frame of instances out. */
export { createRenderer } from "./renderer.ts";
export type { Camera, Instance, Renderer, RendererAssets, Scene } from "./renderer.ts";
@@ -0,0 +1,303 @@
/**
 * The renderer, driven with no GPU and no browser. A stub context writes down
 * every call it was asked to make — the same trick `overlay.test.ts` plays with
 * a `Paint` for 2D — so what is uploaded, what is bound and what is drawn is
 * checked by reading a list instead of a screen.
 *
 * The stub is deliberately only as wide as this module: the enums it names and
 * the functions it calls, each recording its arguments and handing back a plain
 * object where GL would hand back a resource. It is not a fake GPU and must not
 * grow into one — nothing here checks what a pixel came out, only that the
 * right work was asked for once.
 */
import { expect, test } from "bun:test";
import { createRenderer, type Scene } from "./renderer.ts";
import { addBox, builder, finish, type Mesh } from "./mesh.ts";
type Call = [string, ...unknown[]];
/** Every GL enum this module names. Numbered so a recorded call reads back. */
const ENUMS = [
  "ARRAY_BUFFER", "BACK", "COLOR_BUFFER_BIT", "COMPILE_STATUS", "CULL_FACE", "DEPTH_BUFFER_BIT",
  "DEPTH_TEST", "DYNAMIC_DRAW", "ELEMENT_ARRAY_BUFFER", "FLOAT", "FRAGMENT_SHADER", "LINEAR",
  "LINEAR_MIPMAP_LINEAR", "LINES", "LINK_STATUS", "REPEAT", "RGBA", "RGBA8", "STATIC_DRAW",
  "TEXTURE0", "TEXTURE_2D_ARRAY", "TEXTURE_MAG_FILTER", "TEXTURE_MIN_FILTER", "TEXTURE_WRAP_S",
  "TEXTURE_WRAP_T", "TRIANGLES", "UNSIGNED_BYTE", "UNSIGNED_INT", "VERTEX_SHADER",
] as const;
/** A resource the stub handed out, in the order it handed them out. */
type Resource = { kind: string; id: number };
type StubGl = Record<string, unknown> & { calls: Call[]; resources: Resource[] };
/** A `WebGL2RenderingContext` that records what it was told to do, and nothing else. */
function stubGl(): StubGl {
  const calls: Call[] = [];
  const resources: Resource[] = [];
  const note = (name: string) => (...args: unknown[]): void => void calls.push([name, ...args]);
  const hand = (kind: string) => (...args: unknown[]): Resource => {
    calls.push([kind === "shader" ? "createShader" : `create${kind}`, ...args]);
    const made = { kind, id: resources.length + 1 };
    resources.push(made);
    return made;
  };
  const gl: StubGl = {
    calls,
    resources,
    ...Object.fromEntries(ENUMS.map((name, i) => [name, i + 1])),
    createShader: hand("shader"),
    createProgram: hand("Program"),
    createTexture: hand("Texture"),
    createBuffer: hand("Buffer"),
    createVertexArray: hand("VertexArray"),
    getUniformLocation: (_program: unknown, name: string): Resource => ({ kind: name, id: 0 }),
    getShaderParameter: (): boolean => true,
    getProgramParameter: (): boolean => true,
    getShaderInfoLog: (): string => "",
    getProgramInfoLog: (): string => "",
  };
  for (const name of [
    "shaderSource", "compileShader", "attachShader", "linkProgram", "bindTexture", "texImage3D",
    "generateMipmap", "texParameteri", "bindVertexArray", "bindBuffer", "bufferData",
    "bufferSubData", "enableVertexAttribArray", "vertexAttribPointer", "enable", "cullFace",
    "viewport", "clearColor", "clear", "useProgram", "activeTexture", "uniform1i", "uniform3f",
    "uniform3fv", "uniformMatrix4fv", "drawElements", "drawArrays",
  ]) gl[name] = note(name);
  return gl;
}
/** A canvas as far as the renderer is concerned: a size, and one context. */
function stubCanvas(gl: StubGl | null) {
  return {
    clientWidth: 800,
    clientHeight: 600,
    width: 0,
    height: 0,
    getContext(kind: string): unknown {
      return kind === "webgl2" ? gl : null;
    },
  };
}
/** One box, which is a real `Mesh` with nothing invented about it. */
function box(size = 10): Mesh {
  const b = builder();
  addBox(b, [0, 0, 0], [size, size, size], 0);
  return finish(b);
}
const TILE = 4;
/** An atlas of the smallest honest shape: two layers of 4x4 RGBA. */
const atlas = (size = TILE, layers = 2) => ({
  bytes: new Uint8Array(size * size * 4 * layers),
  size,
  layers,
});
/** A renderer on a stub context, with the meshes a test wants by name. */
function renderer(meshes: Record<string, Mesh> = { level: box(), player: box(6) }) {
  const gl = stubGl();
  const canvas = stubCanvas(gl);
  const r = createRenderer(canvas as unknown as HTMLCanvasElement, {
    atlas: atlas(),
    meshes,
    sky: [0.1, 0.2, 0.3],
    devicePixelRatio: () => 1,
  });
  if (r === null) throw new Error("the stub context should have made a renderer");
  return { gl, canvas, r, made: gl.calls.length };
}
/** The one scene the draw tests use: two instances of one mesh, no lines, no gun. */
function scene(mesh = "level"): Scene {
  const instance = (): Scene["instances"][number] => ({
    mesh, pos: [0, 0, 0], yaw: 0, scale: 1, tint: [1, 1, 1],
  });
  return {
    camera: { pos: [0, 0, 64], yaw: 0, pitch: 0, fov: 90 },
    instances: [instance(), instance()],
    instanceCount: 2,
    lines: new Float32Array(12),
    lineCount: 0,
    viewModel: null,
  };
}
/** Every recorded call of this name, arguments and all. */
const of = (gl: StubGl, name: string): Call[] => gl.calls.filter((c) => c[0] === name);
/** Only the calls made after construction: what one frame asked for. */
const frameCalls = (r: ReturnType<typeof renderer>, name: string): Call[] =>
  r.gl.calls.slice(r.made).filter((c) => c[0] === name);
test("a browser with no webgl2 is no renderer, and not an error", () => {
  const made = createRenderer(stubCanvas(null) as unknown as HTMLCanvasElement, {
    atlas: atlas(),
    meshes: { level: box() },
  });
  expect(made).toBeNull();
});
test("construction uploads the atlas once, at the size and layer count it was handed", () => {
  const { gl } = renderer();
  expect(of(gl, "createTexture").length).toBe(1);
  const upload = of(gl, "texImage3D")[0] as Call;
  expect(upload.slice(1, 8)).toEqual([
    gl.TEXTURE_2D_ARRAY, 0, gl.RGBA8, TILE, TILE, 2, 0,
  ]);
  expect(upload[8]).toBe(gl.RGBA);
  expect(upload[9]).toBe(gl.UNSIGNED_BYTE);
  expect((upload[10] as Uint8Array).length).toBe(TILE * TILE * 4 * 2);
  // Mipmaps, and the filtering that reads them, are set once and never per frame.
  expect(of(gl, "generateMipmap").length).toBe(1);
  expect(of(gl, "texParameteri").length).toBe(4);
});
test("construction uploads one buffer set per mesh handed in, and nothing later", () => {
  const two = renderer({ level: box(), player: box(6) });
  // Five buffers a mesh — position, normal, uv, layer, index — plus the one the
  // lines share, and a vertex array each plus the lines'.
  expect(of(two.gl, "createBuffer").length).toBe(2 * 5 + 1);
  expect(of(two.gl, "createVertexArray").length).toBe(2 + 1);
  expect(of(two.gl, "bufferData").length).toBe(2 * 5);
  const three = renderer({ level: box(), player: box(6), bomb: box(2) });
  expect(of(three.gl, "createBuffer").length).toBe(3 * 5 + 1);
  expect(of(three.gl, "createVertexArray").length).toBe(3 + 1);
  // A frame uploads nothing: the whole point of taking the meshes at construction.
  two.r.draw(scene(), 1 / 60);
  two.r.draw(scene(), 1 / 60);
  expect(frameCalls(two, "createBuffer")).toEqual([]);
  expect(frameCalls(two, "bufferData")).toEqual([]);
  expect(frameCalls(two, "texImage3D")).toEqual([]);
});
test("two instances of one mesh bind that mesh's vertex array once", () => {
  const r = renderer();
  r.r.draw(scene("level"), 1 / 60);
  const bound = frameCalls(r, "bindVertexArray").map((c) => c[1]);
  const vaos = bound.filter((v) => v !== null);
  expect(vaos.length).toBe(1);
  // Two instances, two draws, one bind — and the array is left unbound.
  expect(frameCalls(r, "drawElements").length).toBe(2);
  expect(bound[bound.length - 1]).toBeNull();
  // And it is that mesh's own vertex array: the first one construction made.
  const arrays = r.gl.resources.filter((made) => made.kind === "VertexArray");
  expect(vaos[0]).toBe(arrays[0] as Resource);
});
test("a scene of two different meshes binds each of them once", () => {
  const r = renderer();
  const two = scene("level");
  (two.instances[1] as { mesh: string }).mesh = "player";
  r.r.draw(two, 1 / 60);
  const vaos = frameCalls(r, "bindVertexArray").map((c) => c[1]).filter((v) => v !== null);
  expect(vaos.length).toBe(2);
  expect(vaos[0]).not.toEqual(vaos[1]);
});
test("a mesh name nobody handed in throws, and says which name", () => {
  const r = renderer({ level: box() });
  expect(() => r.r.draw(scene("player"), 1 / 60)).toThrow(/no mesh named "player"/);
  // And it names what it does have, because the mistake is usually a typo.
  expect(() => r.r.draw(scene("player"), 1 / 60)).toThrow(/level/);
});
test("an atlas whose bytes are the wrong length is refused at construction", () => {
  const short = { bytes: new Uint8Array(10), size: TILE, layers: 2 };
  const gl = stubGl();
  expect(() =>
    createRenderer(stubCanvas(gl) as unknown as HTMLCanvasElement, {
      atlas: short,
      meshes: { level: box() },
    }),
  ).toThrow(/128 bytes, not 10/);
  // Refused before a context was even asked for: nothing was uploaded.
  expect(gl.calls).toEqual([]);
  for (const bad of [
    { bytes: new Uint8Array(0), size: 0, layers: 2 },
    { bytes: new Uint8Array(64), size: 4, layers: 0 },
    { bytes: new Uint8Array(64), size: 4.5, layers: 1 },
  ])
    expect(() =>
      createRenderer(stubCanvas(stubGl()) as unknown as HTMLCanvasElement, {
        atlas: bad,
        meshes: { level: box() },
      }),
    ).toThrow(/whole numbers above zero/);
});
test("the frame clears to the scene's sky, or the renderer's when it names none", () => {
  const r = renderer();
  const named = scene();
  named.sky = [0.66, 0.73, 0.82];
  r.r.draw(named, 1 / 60);
  expect(frameCalls(r, "clearColor")).toEqual([["clearColor", 0.66, 0.73, 0.82, 1]]);
  const bare = renderer();
  bare.r.draw(scene(), 1 / 60);
  expect(frameCalls(bare, "clearColor")).toEqual([["clearColor", 0.1, 0.2, 0.3, 1]]);
});
test("the canvas is sized in device pixels, and the viewport with it", () => {
  const gl = stubGl();
  const canvas = stubCanvas(gl);
  let ratio = 2;
  const r = createRenderer(canvas as unknown as HTMLCanvasElement, {
    atlas: atlas(),
    meshes: { level: box() },
    devicePixelRatio: () => ratio,
  });
  r?.resize();
  expect([canvas.width, canvas.height]).toEqual([1600, 1200]);
  // Past 2x the pixels cost more than they show, so the ratio is clamped.
  ratio = 3;
  r?.resize();
  expect([canvas.width, canvas.height]).toEqual([1600, 1200]);
  ratio = 1;
  r?.draw(scene(), 1 / 60);
  expect([canvas.width, canvas.height]).toEqual([800, 600]);
  expect(of(gl, "viewport").at(-1)).toEqual(["viewport", 0, 0, 800, 600]);
});
test("the lines grow their buffer once and are drawn in pairs", () => {
  const r = renderer();
  const lit = scene();
  lit.lineCount = 3;
  r.r.draw(lit, 1 / 60);
  expect(frameCalls(r, "bufferData").length).toBe(1);
  expect(frameCalls(r, "bufferSubData").length).toBe(1);
  // Three vertices is one line: an odd vertex has nothing to be a line with.
  expect(frameCalls(r, "drawArrays")).toEqual([["drawArrays", r.gl.LINES, 0, 2]]);
  // A second frame of the same buffer reuses it rather than growing it again.
  const before = r.gl.calls.length;
  r.r.draw(lit, 1 / 60);
  expect(r.gl.calls.slice(before).filter((c) => c[0] === "bufferData")).toEqual([]);
});
test("the gun in your hands is drawn last, on its own depth", () => {
  const r = renderer();
  const held = scene();
  held.viewModel = { mesh: "player", offset: [0, 0, 0] };
  r.r.draw(held, 1 / 60);
  const calls = r.gl.calls.slice(r.made).map((c) => c[0]);
  // Two clears: the frame, then the depth buffer alone before the view model.
  expect(calls.filter((name) => name === "clear").length).toBe(2);
  expect(calls.lastIndexOf("clear")).toBeLessThan(calls.lastIndexOf("drawElements"));
  expect(frameCalls(r, "drawElements").length).toBe(3);
});
test("nothing is drawn for a scene with nothing in it", () => {
  const r = renderer();
  const empty = scene();
  empty.instanceCount = 0;
  r.r.draw(empty, 1 / 60);
  expect(frameCalls(r, "drawElements")).toEqual([]);
  expect(frameCalls(r, "drawArrays")).toEqual([]);
  // The frame is still cleared: an empty scene is a sky, not a stale screen.
  expect(frameCalls(r, "clear").length).toBe(1);
});
@@ -1,18 +1,24 @@
/**
 * The WebGL2 renderer. Two programs and a handful of buffers: one upload per
 * mesh name, one draw per instance the scene lists, and tracers and sparks
 * share the single line buffer the scene brings with it.
 * mesh at construction, one draw per instance the scene lists, and tracers and
 * sparks share the single line buffer the scene brings with it.
 *
 * It decides nothing. A `Scene` from `scene.ts` says where every mesh stands,
 * what it is tinted, which lines to stroke and which gun is in your hands; this
 * file turns that into GL calls and knows no game — no world, no physics, no
 * weapons. What a mesh name is made of is `models.ts`'s business.
 * It decides nothing and it owns no asset. A game hands it `RendererAssets` —
 * the array texture its meshes' layers index into, and every mesh a scene of
 * that game can name — and then hands it a `Scene` per frame: where every mesh
 * stands, what it is tinted, which lines to stroke and which gun is in your
 * hands. What a mesh is made of, how many materials there are and how big a
 * tile is are all the game's; this file turns numbers into GL calls and knows
 * no game at all.
 *
 * A canvas and a `WebGL2RenderingContext` are named here as *types*, which cost
 * nothing to import: the only browser object this module ever touches is the
 * surface it is handed, and the device pixel ratio arrives as a function so a
 * test can drive a whole frame with no window in the room.
 */
import { multiply, perspective, viewMatrix, modelMatrix, type Mesh } from "../engine/index.ts";
import { meshFor } from "./models.ts";
import { LAYERS, TEX_SIZE, materialTextures } from "./materials.ts";
import type { Scene } from "./scene.ts";
import { multiply, perspective, viewMatrix, modelMatrix, type Vec3 } from "./math.ts";
import type { Mesh } from "./mesh.ts";
const SCENE_VS = `#version 300 es
precision highp float;
@@ -79,8 +85,91 @@
in vec3 vColor;
out vec4 outColor;
void main() { outColor = vec4(vColor, 1.0); }`;
/** A colour: r, g, b, written in place by a scene rather than replaced. */
type Tint = [number, number, number];
/** The gun in your hands: which mesh, and where it sits in view space. */
type ViewModel = { mesh: string; offset: Vec3 };
/** Where the eye is and what it can see. A horizontal field of view, as CS reports it. */
export type Camera = { pos: Vec3; yaw: number; pitch: number; fov: number };
/**
 * One mesh, placed. `mesh` is the name the game handed that mesh in under, and
 * `scale` squashes it vertically — a duck, in the shooter — which is the only
 * scaling this renderer applies.
 */
export type Instance = { mesh: string; pos: Vec3; yaw: number; scale: number; tint: Tint };
/**
 * One frame, as plain data. A game fills one of these per frame and allocates
 * nothing doing it: `instances` is a pool of which the first `instanceCount`
 * are live, and `lines` is one buffer of which the first `lineCount * 6` floats
 * are. Anything else a game wants to remember between frames it hangs off its
 * own type; this is only what a draw reads.
 */
export type Scene = {
  camera: Camera;
  /**
   * What this frame clears to and what distance fades into. Left out, it is the
   * `sky` the renderer was built with: a game whose horizon never changes says
   * so once rather than every frame.
   */
  sky?: Tint;
  /** The pool. Only the first `instanceCount` of these are this frame's. */
  instances: Instance[];
  instanceCount: number;
  /** Line vertices, six floats each: x, y, z, r, g, b. */
  lines: Float32Array;
  /** Vertices written this frame — `lineCount * 6` floats of `lines` are live. */
  lineCount: number;
  viewModel: ViewModel | null;
};
/**
 * What a game brings to a renderer, all of it uploaded once at construction.
 *
 * The atlas is a `TEXTURE_2D_ARRAY`: `layers` layers of `size` × `size` RGBA8
 * pixels, tightly packed, which is exactly what `paintAtlas` returns. Neither
 * number is the engine's to assume — a game that paints 64-pixel tiles hands 64
 * — and `bytes` that are not `size * size * 4 * layers` long is a mistake this
 * says so about rather than uploading garbage.
 */
export type RendererAssets = {
  atlas: { bytes: Uint8Array; size: number; layers: number };
  /**
   * Every mesh a scene of this game can name, by that name. Each is uploaded
   * once, here; a scene that asks for a name that is not in this table throws,
   * because that is a bug in the game and not a frame to quietly skip.
   */
  meshes: Record<string, Mesh>;
  /** The horizon a frame that names no sky is cleared to and fades into. Black when left out. */
  sky?: Tint;
  /**
   * How many device pixels a CSS pixel is: `() => window.devicePixelRatio` in a
   * browser, 1 when left out. It is a function because it changes when a window
   * moves between screens, and a parameter because the engine reads no global.
   */
  devicePixelRatio?: () => number;
};
export type Renderer = {
  draw(scene: Scene, dt: number): void;
  resize(): void;
  readonly gl: WebGL2RenderingContext;
};
type Buffers = { vao: WebGLVertexArrayObject; count: number };
/** The bytes an atlas of this shape must be: RGBA8, every layer, tightly packed. */
const atlasBytes = (size: number, layers: number): number => size * size * 4 * layers;
/** Past this the pixels cost more than they show, on a phone especially. */
const MAX_PIXEL_RATIO = 2;
const BLACK: Tint = [0, 0, 0];
const ORIGIN: Vec3 = [0, 0, 0];
function compile(gl: WebGL2RenderingContext, type: number, source: string): WebGLShader {
  const shader = gl.createShader(type) as WebGLShader;
  gl.shaderSource(shader, source);
@@ -121,13 +210,31 @@
function upload(gl: WebGL2RenderingContext, mesh: Mesh): Buffers {
  return { vao, count: mesh.index.length };
}
export type Renderer = {
  draw(scene: Scene, dt: number): void;
  resize(): void;
  readonly gl: WebGL2RenderingContext;
};
/**
 * Why these assets are not assets, or null when they are. Checked before a
 * context is asked for, because an atlas of the wrong length is a mistake in
 * the game whether or not this browser can draw at all.
 */
function wrongAssets(assets: RendererAssets): string | null {
  const { size, layers, bytes } = assets.atlas;
  if (!Number.isInteger(size) || size <= 0 || !Number.isInteger(layers) || layers <= 0)
    return `atlas: size and layers must be whole numbers above zero, not ${size} and ${layers}`;
  const want = atlasBytes(size, layers);
  if (bytes.length !== want)
    return `atlas: ${layers} layers of ${size}x${size} RGBA is ${want} bytes, not ${bytes.length}`;
  return null;
}
/**
 * A renderer on this surface, or null when the browser has no WebGL2 — which is
 * a browser to tell the player about, not an error. Everything else that is
 * wrong here throws: the assets are checked once, the meshes are uploaded once,
 * and after that a frame is arithmetic and GL calls.
 */
export function createRenderer(canvas: HTMLCanvasElement, assets: RendererAssets): Renderer | null {
  const wrong = wrongAssets(assets);
  if (wrong !== null) throw new Error(wrong);
export function createRenderer(canvas: HTMLCanvasElement): Renderer | null {
  const gl = canvas.getContext("webgl2", { antialias: true, alpha: false, depth: true });
  if (gl === null) return null;
@@ -145,11 +252,12 @@
export function createRenderer(canvas: HTMLCanvasElement): Renderer | null {
    lineViewProj: uniform(strokes, "uViewProj"),
  };
  const atlas = assets.atlas;
  const texture = gl.createTexture();
  gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
  gl.texImage3D(
    gl.TEXTURE_2D_ARRAY, 0, gl.RGBA8, TEX_SIZE, TEX_SIZE, LAYERS, 0, gl.RGBA, gl.UNSIGNED_BYTE,
    materialTextures(),
    gl.TEXTURE_2D_ARRAY, 0, gl.RGBA8, atlas.size, atlas.size, atlas.layers, 0, gl.RGBA,
    gl.UNSIGNED_BYTE, atlas.bytes,
  );
  gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
  gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
@@ -157,14 +265,15 @@
export function createRenderer(canvas: HTMLCanvasElement): Renderer | null {
  gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.REPEAT);
  gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.REPEAT);
  // One upload per mesh name the scene asks for, the first time it asks.
  // One upload per mesh the game handed in, all of them here and none in a frame.
  const uploaded = new Map<string, Buffers>();
  for (const [name, mesh] of Object.entries(assets.meshes)) uploaded.set(name, upload(gl, mesh));
  const buffersFor = (name: string): Buffers => {
    let buffers = uploaded.get(name);
    if (buffers === undefined) {
      buffers = upload(gl, meshFor(name));
      uploaded.set(name, buffers);
    }
    const buffers = uploaded.get(name);
    if (buffers === undefined)
      throw new Error(
        `no mesh named "${name}": the renderer was handed ${[...uploaded.keys()].join(", ") || "none"}`,
      );
    return buffers;
  };
@@ -185,8 +294,11 @@
export function createRenderer(canvas: HTMLCanvasElement): Renderer | null {
  gl.enable(gl.CULL_FACE);
  gl.cullFace(gl.BACK);
  const pixelRatio = assets.devicePixelRatio;
  const ownSky = assets.sky ?? BLACK;
  const resize = (): void => {
    const dpr = Math.min(window.devicePixelRatio || 1, 2);
    const dpr = Math.min((pixelRatio === undefined ? 1 : pixelRatio()) || 1, MAX_PIXEL_RATIO);
    const width = Math.round(canvas.clientWidth * dpr);
    const height = Math.round(canvas.clientHeight * dpr);
    if (canvas.width !== width || canvas.height !== height) {
@@ -195,19 +307,18 @@
export function createRenderer(canvas: HTMLCanvasElement): Renderer | null {
    }
  };
  const ORIGIN: [number, number, number] = [0, 0, 0];
  /**
   * One frame of the scene handed in. `dt` is the frame's seconds: nothing in
   * the draw animates itself any more — the walk bob went to `scene.ts` with
   * every other decision — and it stays in the signature because a renderer's
   * own time (a fade, an exposure) would belong here rather than in a scene.
   * the draw animates itself — a walk bob is a decision and decisions are the
   * game's — and it stays in the signature because a renderer's own time (a
   * fade, an exposure) would belong here rather than in a scene.
   */
  const draw = (scene: Scene, dt: number): void => {
    resize();
    const width = canvas.width, height = canvas.height;
    const sky = scene.sky ?? ownSky;
    gl.viewport(0, 0, width, height);
    gl.clearColor(scene.sky[0], scene.sky[1], scene.sky[2], 1);
    gl.clearColor(sky[0], sky[1], sky[2], 1);
    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
    gl.enable(gl.DEPTH_TEST);
@@ -225,7 +336,7 @@
export function createRenderer(canvas: HTMLCanvasElement): Renderer | null {
    gl.uniform1i(u.atlas, 0);
    gl.uniformMatrix4fv(u.viewProj, false, viewProj);
    gl.uniform3fv(u.eye, camera.pos);
    gl.uniform3fv(u.fog, scene.sky);
    gl.uniform3fv(u.fog, sky);
    // --- every mesh the scene placed, in the order it placed them
    let bound: Buffers | null = null;
		@@ -108,11 +108,14 @@ from the angle it subtends, and you turn on the spot.
108	108	knows nothing about de_forge's alphabet), `mesh` (a box builder), `texture`
109	109	(hashed value noise, fbm and an atlas painter), `sound` (a lazy `AudioContext`
110	110	with noise bursts and tones), `loop` (a fixed step with a clamp on a long
111		frame), `controls` (a bindings table in, held actions out) and `overlay` (the
	111	frame), `controls` (a bindings table in, held actions out), `overlay` (the
112	112	2D over the scene: a scale and a pad off the canvas width, scaled fonts,
113	113	panels, aligned and faded text, a crosshair, a bar, right-aligned columns and
114	114	a `m:ss` clock, drawn onto the seventeen members of a 2D context it uses and
115		holding no colour a game chose).
	115	holding no colour a game chose) and `renderer` (the WebGL2: two programs, an
	116	atlas and named meshes uploaded once at construction, and one `Scene` of
	117	instances and lines drawn per frame — it knows no game, no world and no
	118	model, and a canvas and a GL context are named in it only as types).
116	119	Three rules keep it a package, and a test holds each: the engine imports
117	120	nothing outside itself, it needs nothing from a browser to load, and
118	121	everything outside it comes in through one door.
		@@ -126,8 +129,10 @@ from the angle it subtends, and you turn on the spot.
126	129	module a bench or a server-rendered page cannot import. (The second process is
127	130	`purity.probe.ts`: a dynamic import is cached per process, so the first load
128	131	of each module has to happen somewhere the engine's own tests have not been.)
129		The last two take their clock, their canvas and their window as parameters, so
130		the tests drive them with a stub instead of a browser, and `sound` opens its
	132	`loop`, `controls` and `renderer` take their clock, their canvas, their window
	133	and their pixel ratio as parameters, so the tests drive them with a stub
	134	instead of a browser — `renderer.test.ts` uploads meshes and draws frames into
	135	a context that only writes down what it was asked for — and `sound` opens its
131	136	`AudioContext` on the first sound rather than on load.
132	137	- `src/engine/index.ts` — the door, and the rule is that a second game imports
133	138	`src/engine/index.ts` and nothing deeper; inside the engine, modules import
		@@ -143,8 +148,10 @@ from the angle it subtends, and you turn on the spot.
143	148	`sound` `attenuate`, `createSoundDevice`, `Burst`, `Tone`, `SoundDevice` and
144	149	`Ctor`; from `loop` `createLoop`, `Frames`, `Loop` and `LoopOptions`; from
145	150	`controls` `createControls`, `attachButtons` and the event and option types
146		they are driven with; and from `overlay` `overlay`, `Overlay` and the `Paint`
147		a 2D game draws onto. `boundary.test.ts` fails a deep import from outside, a
	151	they are driven with; from `overlay` `overlay`, `Overlay` and the `Paint`
	152	a 2D game draws onto; and from `renderer` `createRenderer` with `Renderer`,
	153	`RendererAssets` and the frame it draws — `Scene`, `Camera` and `Instance`.
	154	`boundary.test.ts` fails a deep import from outside, a
148	155	module that is not behind the door, and any change to that list of names that
149	156	is not also a change to the list written out in the test. One exception, and
150	157	it is written down there too: a `.test.ts` may import another `.test.ts`, which
		@@ -160,16 +167,17 @@ from the angle it subtends, and you turn on the spot.
160	167	over the engine's grid), `physics`, `weapons`, `combat`, `match` (the rules),
161	168	`world` (the simulation),
162	169	`bots`, `observe`, `action`, `policy`, `weights`, `models`, `materials`,
163		`binding`, `scene`, `renderer`, `hud`, `audio`, `main`. Everything is headless
164		and tested but `renderer`, which is the one module that needs a real WebGL2
165		context; `models`, `materials` and `audio` are this game's recipes for the
166		engine's three asset tools, and `binding` is its key table and the one
	170	`binding`, `scene`, `hud`, `audio`, `main`. Everything in here is headless and
	171	tested: the WebGL2 is the engine's now, and this game has no renderer of its
	172	own. `models`, `materials` and `audio` are this game's recipes for the
	173	engine's three asset tools — `main` builds the atlas and all eight meshes at
	174	start-up and hands them to `createRenderer`, which keeps them by name — and
	175	`binding` is its key table and the one
167	176	function from a held action to an `Input`. `scene` is the frame as data —
168	177	`buildScene(world, camera, into)` fills one scene object with the camera, the
169	178	sky, the instances to draw in the order to draw them, the line vertices every
170		tracer and spark and beam comes to, and the gun in your hands — and `renderer`
171		draws that and nothing else: it names no world, no physics and no weapons, so
172		a second game can hand it a scene of its own. Which is why every decision
	179	tracer and spark and beam comes to, and the gun in your hands — and the
	180	engine's renderer draws that and nothing else. Which is why every decision
173	181	about a frame — who is drawn, how far a duck squashes them, how long a tracer
174	182	lives, how far the last shot kicked the view model — is checked in
175	183	`scene.test.ts` with no canvas in the room. Nothing is allocated per frame:
		@@ -36,7 +36,12 @@ export type Entry = { name: string; entry: string; ceiling: Ceiling };
36	36	* this ceiling raised, and #18 takes the same bytes back out of the shooter.
37	37	* The app grew 1,254 bytes for #47, which moved every decision about a frame
38	38	* into `src/client/scene.ts`; it fits under today's ceiling, so no ceiling moved
39		* with it. The range's ceiling was raised for #41, which gave it a game: the targets,
	39	* with it. It grew another 830 raw / 701 gzipped for #48, which moved the
	40	* renderer behind the door: the game now builds all eight of its meshes and
	41	* hands them in at construction rather than uploading each on the frame that
	42	* first asks for it. Measured after #48: app 70,558 raw / 32,850 gzipped,
	43	* range 12,548 raw / 5,729 gzipped — the range is unchanged in size, which is
	44	* the tree-shaking working: it imports the door and none of the WebGL2 behind it. The range's ceiling was raised for #41, which gave it a game: the targets,
40	45	* the clock and the score, the shot traced through the engine's `rayBox`, and
41	46	* the blips the horizon draws them as.
42	47	* Raising a ceiling is allowed, and it is a line in the pull that says what was
		@@ -13,7 +13,8 @@
13	13	*/
14	14
15	15	import { expect, test } from "bun:test";
16		import { boot, type Frame } from "./main.ts";
	16	import { boot, gameMeshes, type Frame } from "./main.ts";
	17	import { WEAPONS } from "./weapons.ts";
17	18	import { parseResult } from "../result.ts";
18	19	import { fakeStage, type FakeStage } from "./stage.test-helper.ts";
19	20	import type { World } from "./world.ts";
		@@ -298,3 +299,21 @@ test("no WebGL2 is a sentence on the page, not an exception", () => {
298	299	expect(stage.document.listening.size).toBe(0);
299	300	expect(stage.draws.length).toBe(0);
300	301	});
	302
	303	test("every mesh name a scene of this game can place is handed in at construction", () => {
	304	// The renderer keeps what it is given and resolves nothing, so a name this
	305	// table misses is an exception on the frame a player first holds that gun.
	306	const meshes = gameMeshes();
	307	expect(Object.keys(meshes).sort()).toEqual([
	308	"bomb", "knife", "level", "pistol", "player", "rifle", "smg", "sniper",
	309	]);
	310	// Every kind a weapon can be, and the kind `scene.ts` falls back to.
	311	for (const weapon of Object.values(WEAPONS)) expect(meshes[weapon.kind]).toBeDefined();
	312	expect(meshes["rifle"]).toBeDefined();
	313	// And each one is geometry, not an empty buffer.
	314	for (const [name, mesh] of Object.entries(meshes)) {
	315	expect(mesh.index.length).toBeGreaterThan(0);
	316	expect(mesh.position.length).toBe((mesh.index.length / 6) * 4 * 3);
	317	expect(name).toMatch(/^[a-z]+$/);
	318	}
	319	});
		@@ -2,7 +2,8 @@
2	2	* The frame. The engine's loop says how many 64 Hz steps this frame is worth
3	3	* and the engine's controls say which actions are held; `binding` turns those
4	4	* names into the `Input` the world takes. `scene.ts` then turns the world into
5		* the frame's data and the renderer draws that, and the HUD is painted on top. The page's overlays — menu, buy, pause — are plain DOM, so they are
	5	* the frame's data and the engine's renderer draws that — built here, from this
	6	* game's atlas and this game's meshes — and the HUD is painted on top. The page's overlays — menu, buy, pause — are plain DOM, so they are
6	7	* reachable with a keyboard and big enough for a thumb.
7	8	*
8	9	* Nothing in here is a browser. `boot(host)` takes everything it reaches for —
		@@ -18,12 +19,14 @@ import { createAudio, type Audio } from "./audio.ts";
18	19	import { CS_KEYS, CS_MOUSE, CS_TAP, readIntent } from "./binding.ts";
19	20	import { drawHud, type Paint } from "./hud.ts";
20	21	import {
21		attachButtons, clamp, createControls, createLoop, type Button, type Listens,
	22	attachButtons, clamp, createControls, createLoop, createRenderer, type Button, type Camera,
	23	type Listens, type Mesh,
22	24	} from "../engine/index.ts";
23	25	import { COMPETITIVE, SHORT, type Rules } from "./match.ts";
24		import { createRenderer } from "./renderer.ts";
25		import { buildScene, createScene, type Camera, type Scene } from "./scene.ts";
26		import { buyable } from "./weapons.ts";
	26	import { LAYERS, TEX_SIZE, materialTextures } from "./materials.ts";
	27	import { meshFor } from "./models.ts";
	28	import { buildScene, createScene, SKY, type Scene } from "./scene.ts";
	29	import { buyable, WEAPONS } from "./weapons.ts";
27	30	import {
28	31	buy, canBuy, createWorld, eyePos, priceOf, update, type BuyItem, type Player, type World,
29	32	} from "./world.ts";
		@@ -355,11 +358,32 @@ export function boot(host: Host): Frame {
355	358	return { world: () => world };
356	359	}
357	360
	361	/**
	362	* Every mesh a scene of this game can name, built once and handed to the
	363	* renderer at construction: the level, a player, the bomb, and one view model
	364	* per weapon kind. The renderer keeps what it is given by name and resolves
	365	* nothing itself, so this table and `models.meshFor` are the whole of what the
	366	* engine would otherwise have had to know about this game's geometry.
	367	*
	368	* Exported because a name this misses is a crash mid-match — the first frame a
	369	* player picks that gun up — and `main.test.ts` holds it against every name
	370	* `scene.ts` can place.
	371	*/
	372	export function gameMeshes(): Record<string, Mesh> {
	373	const kinds = new Set(Object.values(WEAPONS).map((weapon) => weapon.kind));
	374	const names = ["level", "player", "bomb", ...kinds];
	375	return Object.fromEntries(names.map((name) => [name, meshFor(name)]));
	376	}
	377
358	378	/**
359	379	* The browser, and the only place in this file where one is named: the real
360	380	* document, window, store, network, ids and factories, handed in as a host.
361		* The cast is the seam — `createRenderer` wants a real canvas, and a `Stage` is
362		* the smaller shape this file and a test can both satisfy.
	381	* The cast is the seam — the engine's `createRenderer` wants a real canvas, and
	382	* a `Stage` is the smaller shape this file and a test can both satisfy — and
	383	* the assets beside it are this game's, which is why they are passed in here
	384	* rather than reached for behind the door: the atlas `materials.ts` paints, the
	385	* size and layer count it painted at, the meshes above, the horizon a frame
	386	* that named none would get, and the pixel ratio of the screen we are on.
363	387	*/
364	388	const browser = (): Host => ({
365	389	document,
		@@ -367,7 +391,13 @@ const browser = (): Host => ({
367	391	storage: localStorage,
368	392	fetch: (url, init) => fetch(url, init),
369	393	randomUUID: () => crypto.randomUUID(),
370		createRenderer: (canvas) => createRenderer(canvas as unknown as HTMLCanvasElement),
	394	createRenderer: (canvas) =>
	395	createRenderer(canvas as unknown as HTMLCanvasElement, {
	396	atlas: { bytes: materialTextures(), size: TEX_SIZE, layers: LAYERS },
	397	meshes: gameMeshes(),
	398	sky: SKY,
	399	devicePixelRatio: () => window.devicePixelRatio,
	400	}),
371	401	createAudio: () => createAudio(),
372	402	});
373	403
		@@ -66,9 +66,10 @@ export function viewModelMesh(kind: string): Mesh {
66	66
67	67	/**
68	68	* A mesh by the name a scene calls it: `level`, `player`, `bomb`, or a weapon
69		* kind for the gun in your hands. The renderer keeps one upload per name and
70		* never learns what a name is made of — that is this file, and this is the one
71		* line a second game's model table would replace.
	69	* kind for the gun in your hands. `main.ts` builds one of each at start-up and
	70	* hands them to the engine's renderer, which keeps them by name and never
	71	* learns what a name is made of — that is this file, and this is the one line a
	72	* second game's model table would replace.
72	73	*/
73	74	export function meshFor(name: string): Mesh {
74	75	if (name === "level") return levelMesh(boxes);
		@@ -5,16 +5,17 @@
5	5	* squashes a player, how long a tracer lives, which gun is in your hands and
6	6	* how far the last shot kicked it — is a number a test can read.
7	7	*
8		* The last test is the boundary itself: the renderer may not name the world,
9		* the physics or the weapons again, because a second game that hands it a scene
10		* would have neither.
	8	* The last test is the boundary itself: the drawing is `src/engine/renderer.ts`
	9	* now and the `Scene` it reads is the door's type, so what this file decides is
	10	* exactly what any game's renderer is handed.
11	11	*/
12	12
13	13	import { expect, test } from "bun:test";
14		import { readFileSync } from "node:fs";
	14	import { existsSync, readFileSync } from "node:fs";
15	15	import { join } from "node:path";
	16	import type { Camera } from "../engine/index.ts";
16	17	import { HULL } from "./physics.ts";
17		import { buildScene, createScene, LINE_CAPACITY, SKY, type Camera } from "./scene.ts";
	18	import { buildScene, createScene, LINE_CAPACITY, SKY } from "./scene.ts";
18	19	import { SHORT } from "./match.ts";
19	20	import { createWorld, type Effect, type World } from "./world.ts";
20	21
		@@ -223,11 +224,14 @@ test("a frame allocates nothing: the same scene, the same buffer, the same insta
223	224	expect(scene.viewModel).toBe(held);
224	225	});
225	226
226		test("the renderer names no world, no physics and no weapons", () => {
227		const source = readFileSync(join(import.meta.dir, "renderer.ts"), "utf8");
228		for (const forbidden of ["./world.ts", "./physics.ts", "./weapons.ts", "./map.ts"])
229		expect(source).not.toContain(forbidden);
230		expect(source).toContain('from "./scene.ts"');
231		expect(source).toContain('from "./models.ts"');
232		expect(source).toContain('from "./materials.ts"');
	227	test("this game has no renderer of its own: the frame is the door's type", () => {
	228	// The WebGL2 is `src/engine/renderer.ts` now, and `boundary.test.ts` holds it
	229	// to importing nothing but the engine. What is left here is the scene, whose
	230	// type comes through the door — so what this game decides about a frame and
	231	// what any game's renderer reads of it are the same thing by construction.
	232	expect(existsSync(join(import.meta.dir, "renderer.ts"))).toBe(false);
	233	const source = readFileSync(join(import.meta.dir, "scene.ts"), "utf8");
	234	expect(source).toContain("type Scene as Frame");
	235	expect(source).toContain('from "../engine/index.ts"');
	236	expect(source).toContain("export type Scene = Frame &");
233	237	});
		@@ -2,9 +2,10 @@
2	2	* The frame, as data. Everything a draw has to decide about this game — which
3	3	* mesh stands where, what a team is tinted, how far a tracer has faded, which
4	4	* gun is in your hands and how far the last shot kicked it — is decided here,
5		* in plain numbers a test can read without a canvas. `renderer.ts` then draws
6		* exactly this and knows nothing else, which is what lets a second game hand it
7		* a scene of its own.
	5	* in plain numbers a test can read without a canvas. The engine's renderer then
	6	* draws exactly this and knows nothing else, which is what lets a second game
	7	* hand it a scene of its own: `Scene`, `Camera` and `Instance` are the door's
	8	* types, and what is added below is only what this game keeps between frames.
8	9	*
9	10	* Nothing is allocated in a frame. `createScene()` makes the one scene and the
10	11	* one line buffer a game ever needs, and `buildScene(world, camera, into)`
		@@ -13,37 +14,24 @@
13	14	* and the view model object is kept even on the frames where there is none.
14	15	*/
15	16
16		import { clamp, type Vec3 } from "../engine/index.ts";
	17	import { clamp, type Camera, type Scene as Frame, type Vec3 } from "../engine/index.ts";
17	18	import { HULL, hullHeight } from "./physics.ts";
18	19	import { WEAPONS } from "./weapons.ts";
19	20	import type { World } from "./world.ts";
20	21
21		/** Where the eye is and what it can see. A horizontal field of view, as CS reports it. */
22		export type Camera = { pos: Vec3; yaw: number; pitch: number; fov: number };
23
24	22	export type Tint = [number, number, number];
25	23
26		/**
27		* One mesh, placed. `mesh` is the name the renderer resolves — `level`,
28		* `player`, `bomb`, or a weapon kind for a view model — and `scale` is the
29		* vertical squash a duck applies, the only scaling this game asks for.
30		*/
31		export type Instance = { mesh: string; pos: Vec3; yaw: number; scale: number; tint: Tint };
32
33	24	/** The gun in your hands: which one, and where it sits in view space. */
34	25	export type ViewModel = { mesh: string; offset: Vec3 };
35	26
36		export type Scene = {
37		camera: Camera;
	27	/**
	28	* The engine's frame, plus this game's memory of the last one. The mesh names
	29	* placed below — `level`, `player`, `bomb`, and a weapon kind for a view model
	30	* — are the names `main.ts` hands the renderer at construction.
	31	*/
	32	export type Scene = Frame & {
	33	/** This game's horizon is never not named: `SKY`, written in every frame. */
38	34	sky: Tint;
39		/** The pool. Only the first `instanceCount` of these are this frame's. */
40		instances: Instance[];
41		instanceCount: number;
42		/** Line vertices, six floats each: x, y, z, r, g, b. */
43		lines: Float32Array;
44		/** Vertices written this frame — `lineCount * 6` floats of `lines` are live. */
45		lineCount: number;
46		viewModel: ViewModel \| null;
47	35	/**
48	36	* What the scene remembers between frames so a frame allocates nothing: the
49	37	* walk cycle the view model bobs on, the world time it last saw, and the one
		@@ -273,6 +273,54 @@ o.panel(pad, pad, width - pad * 2, step * lines.length + pad, "rgba(11,13,17,.72
273	273	o.crosshair(Math.round(width / 2), Math.round(height / 2), 0, Math.max(6, Math.round(width / 90)), "#8ea");
274	274	```
275	275
	276	### renderer
	277
	278	The 3D under the scene, and the largest thing behind the door. `createRenderer`
	279	takes the canvas and the assets and hands back a `Renderer` — or nothing at all,
	280	when the browser has no WebGL2, which is a sentence to show the player rather
	281	than an error — with three members: `Renderer.draw` for one frame,
	282	`Renderer.resize` for the canvas in device pixels, and `Renderer.gl` for the
	283	context itself, if a game ever wants a pass of its own.
	284
	285	What a game brings is `RendererAssets`, and every byte of it is uploaded once,
	286	at construction. `RendererAssets.atlas` is the `TEXTURE_2D_ARRAY` every mesh's
	287	layer indexes into: a size, a layer count, and exactly what `paintAtlas`
	288	returns at that size. Neither number is assumed — a game that paints 64-pixel
	289	tiles says 64 — so bytes of any other length are refused with both numbers in
	290	the message. `RendererAssets.meshes` is every `Mesh` a scene of this game can
	291	name, under the name its instances will ask for.
	292	`RendererAssets.sky` is the horizon for a frame that names none, and
	293	`RendererAssets.devicePixelRatio` is `window.devicePixelRatio` handed in as a
	294	function, because the engine reads no global and a test drives a whole frame
	295	with no window in the room.
	296
	297	```ts
	298	// src/client/main.ts
	299	createRenderer(canvas as unknown as HTMLCanvasElement, {
	300	atlas: { bytes: materialTextures(), size: TEX_SIZE, layers: LAYERS },
	301	meshes: gameMeshes(),
	302	sky: SKY,
	303	devicePixelRatio: () => window.devicePixelRatio,
	304	}),
	305	```
	306
	307	Then every frame is a `Scene`: a `Camera` — a position, a yaw, a pitch and a
	308	horizontal field of view — the sky this frame clears to and fades into, a pool
	309	of `Instance` values of which the first `Scene.instanceCount` are live, each a
	310	mesh name with a place, a yaw, a vertical squash and a tint; one
	311	`Float32Array` of line vertices of which the first `Scene.lineCount` are live,
	312	six floats each for a tracer or a spark; and `Scene.viewModel`, when there is a
	313	gun in your hands. Fill one scene object every frame rather than making one —
	314	`src/client/scene.ts` allocates nothing per frame and is worth copying — name a
	315	mesh that was never handed in and the draw throws with that name in the
	316	message, and remember that nothing in a draw animates itself: a bob, a fade or
	317	a tint is a decision, and decisions are the game's.
	318
	319	```ts
	320	// src/client/main.ts
	321	renderer.draw(buildScene(world, camera, frameScene), elapsed);
	322	```
	323
276	324	## The seam, named as pairs
277	325
278	326	Two games exist here, and every place they differ is a place the engine chose to
		@@ -288,7 +336,7 @@ split.
288	336	\| mesh recipes \| `src/client/models.ts` \| none: it draws no geometry yet \|
289	337	\| texture recipes \| `src/client/materials.ts` \| none: the readout paints its own 2D \|
290	338	\| sound recipes \| `src/client/audio.ts` \| none yet \|
291		\| a renderer \| WebGL2, `src/client/renderer.ts` \| a 2D horizon, `src/range/readout.ts` \|
	339	\| renderer assets \| an atlas and eight meshes, from `src/client/main.ts` \| none: it draws a 2D horizon in `src/range/readout.ts` \|
292	340	\| the tuning \| `src/client/physics.ts`, `src/client/weapons.ts` \| `targets.STANDARD` in `src/range/targets.ts` \|
293	341
294	342	## What the engine deliberately does not know
		@@ -220,12 +220,13 @@ test("no module in the engine goes through the engine's own door", () => {
220	220	* copy of the surface, read twice, rather than two that drift.
221	221	*/
222	222	export const SURFACE = [
223		"Box", "Builder", "Burst", "Button", "ButtonOptions", "Controls", "Ctor", "Frames", "Grid",
224		"Hit", "Host", "KeyEventish", "Listens", "LockOwner", "Loop", "LoopOptions", "Mat4", "Mesh",
225		"MouseEventish", "Options", "Overlay", "Paint", "Shader", "SoundDevice", "Stick", "Surface", "Tone",
	223	"Box", "Builder", "Burst", "Button", "ButtonOptions", "Camera", "Controls", "Ctor", "Frames",
	224	"Grid", "Hit", "Host", "Instance", "KeyEventish", "Listens", "LockOwner", "Loop", "LoopOptions",
	225	"Mat4", "Mesh", "MouseEventish", "Options", "Overlay", "Paint", "Renderer", "RendererAssets",
	226	"Scene", "Shader", "SoundDevice", "Stick", "Surface", "Tone",
226	227	"TouchEventish", "Touchish", "Vec3", "add", "addBox", "angleDelta", "angleVectors",
227	228	"attachButtons", "attenuate", "builder", "cellAt", "clamp", "colOf", "createControls",
228		"createLoop", "createSoundDevice", "cross", "deg", "dist", "dist2d", "dot", "fbm",
	229	"createLoop", "createRenderer", "createSoundDevice", "cross", "deg", "dist", "dist2d", "dot", "fbm",
229	230	"findPath", "finish", "hash", "inside", "length", "length2d", "lerp", "mat4", "mergeSolid",
230	231	"modelMatrix", "mul", "multiply", "noise", "normalize", "overlay", "paintAtlas", "perspective",
231	232	"quadMesh", "rad", "rayBox", "rng", "rowOf", "scale", "segmentLength", "sub", "traceWorld",
		@@ -48,8 +48,9 @@ const BARE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
48	48	* this file ignores without needing to be told about it.
49	49	*/
50	50	const NOT_THE_ENGINES = new Set([
51		"AudioContext", "Float32Array", "addEventListener", "cancelAnimationFrame", "de_forge",
52		"pointerLockElement", "removeEventListener", "requestAnimationFrame", "uniformMatrix4fv",
	51	"AudioContext", "Float32Array", "TEXTURE_2D_ARRAY", "addEventListener", "cancelAnimationFrame",
	52	"de_forge", "pointerLockElement", "removeEventListener", "requestAnimationFrame",
	53	"uniformMatrix4fv",
53	54	]);
54	55
55	56	const guide = (): string => readFileSync(GUIDE, "utf8");