@lampdotdev/lamp 0.0.0-stage → 0.35.0

package/Resources/skills/2d-game/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: 2d-game
+description: 2D games - choosing 2D or 3D, and Phaser (a game of Lamp's game kind, played on the Mac, iPhone and iPad, Android, TVs and the Xbox) or SpriteKit (a Mac or iPhone app); scenes, the frame step, cameras, tilemaps, sprite sheets, physics, controls on every input, pixel art, TV safe areas, sound, saves, drawing the art, and keeping it smooth on the slowest place. Read before writing or changing a 2D game; a new web game on the Mac starts from the web-game guide instead, which says when to open this.
+---
+
+# 2D games
+
+A 2D game is drawn flat: a platformer, a shooter seen from above or the side, a racer seen from above, a puzzle or
+arcade game played in real time. Read the game skill too: what every game needs (moving by the time since the last
+frame, controls, sound, saves, the look) is there, and this skill is how to do it in 2D.
+
+## 2D or 3D
+
+2D when the person describes something flat (a platformer, "like Mario", "like Pac-Man", a top-down shooter, a pixel-art
+game, a puzzle with falling pieces) or a game whose look is drawings rather than a world to look around. 3D when they
+want depth to move through (driving through a city, flying, a first-person view, a ball rolling over hills): the
+3d-game skill. When nothing says, a game whose play is flat is better flat: it's cheaper on every device and drawings
+read better than simple 3D shapes. Don't ask; choose, and say in a sentence which.
+
+## Phaser or SpriteKit
+
+- **Phaser**, in a game of Lamp's game kind: the page in Web/ on Lamp's game runtime. It's played on the Mac and goes,
+  unchanged, to an iPhone or iPad, an Android phone, tablet or TV, a Samsung or LG TV, the Xbox and a page on the web,
+  whenever the person asks for one of those later. This is the default for a 2D game.
+- **SpriteKit**, in a Mac or iPhone app written in Swift: when the game belongs with Apple's own things (Game Center,
+  a widget, iCloud, the Apple Watch), sits inside an app of theirs (a game in a menu of their Mac app), or is for an
+  Apple TV, which runs no pages. A SpriteKit game can never go to Android, the Xbox, a Samsung or LG TV or the web: it
+  would have to be written again. Say so plainly when choosing it, and choose it only for what needs it.
+
+The kind of app is chosen before your first turn: a game is of the game kind, and a Mac or iPhone app whose request is
+a game is written with SpriteKit. When the choice doesn't fit (a game of the game kind that needs Game Center, or a Mac
+app that should be playable on the person's Xbox), say why in a sentence and change it with make_app_for.
+
+## Phaser on Lamp's runtime
+
+Lamp's game kind runs Phaser 3 (3.90) through `Web/lamp-phaser.js`, over the runtime in `Web/lamp-game.js`. Read both,
+all of them, before writing the game: their comments are the interface (a new game at home on the Mac has the
+web-game guide instead). Lamp puts Phaser in `Web/phaser` once the page
+imports it.
+
+index.html keeps the scaffold's head (lamp.js, then the import map, whose `phaser` entry is
+`./phaser/phaser.esm.min.js`), then `<script type="module" src="game.js">`. game.js:
+
+```js
+import * as Phaser from 'phaser';
+import { phaser, pad } from './lamp-phaser.js';
+import { BUTTON, STICK, sound, save, load, random, log, label, glyph, onInput, hot } from './lamp-game.js';
+
+const CONTROLS = { move: STICK.LEFT, jump: BUTTON.A, back: BUTTON.B, pause: BUTTON.MENU };
+
+class Play extends Phaser.Scene {
+    constructor() { super('play'); }
+    preload() { this.load.image('hero', 'art/hero.png'); }
+    create() { … }
+    update(time, delta) {
+        const p = pad(), dt = delta / 1000;
+        if (p.pressed & CONTROLS.jump) …
+    }
+}
+
+phaser({ scenes: [Boot, Play], physics: { default: 'arcade', arcade: { gravity: { y: 2400 } } }, touch: BUTTON.A | BUTTON.B | BUTTON.MENU });
+```
+
+As the game grows, each scene goes in a module of its own (`play.js` exporting `Play`, imported by game.js) that ends
+with `hot(import.meta).accept()` from lamp-game.js, so a change to it goes into the running scene (the game skill,
+"Changes while it's played"): the scene keeps its sprites and fields and runs the new `update` and the methods it
+calls. What `create` built stays until the scene starts again, so a change to `create` or `preload` returns false from
+`accept((next, { changed }) => !changed.some(n => /\.(create|preload|init)$/.test(n)))` and the game's code runs again
+in place from the snapshot, with a new Phaser game that loads its pictures again.
+
+What Lamp has changed in Phaser, so its usual code works here:
+
+- **One frame loop, Lamp's.** Phaser's own loop is asleep; each of the runtime's frames steps Phaser once. Use a
+  scene's `update(time, delta)` (ms) and Phaser's timers and tweens freely: they all run on that one clock. Never requestAnimationFrame, setTimeout, Date or Math.random of your own:
+  `random()` from lamp-game.js, or `Phaser.Math.RND`, which Lamp seeds from it.
+- **Input is the runtime's pad.** `pad()` is the first controller with the keyboard and the touch controls merged in
+  (lx, ly, rx, ry with up positive; buttons as BUTTON bits in down, pressed and released). Phaser's keyboard and
+  gamepad are off: `this.input.keyboard` and `this.input.gamepad` are null, so never `createCursorKeys` or
+  `addKey`. Phaser's pointer input works with the mouse on the Mac; on a touch screen Lamp's touch controls lie over
+  the canvas, so a game played by tapping the screen itself passes `touch: false` and reads `this.input.on('pointerdown')`.
+- **Sound is the runtime's.** Phaser's sound is off: `this.load.audio` and `this.sound` play nothing. Load files from the
+  `assets` tool (the game skill, "Sound") with `await sound.load('assets/…')`, once, at the top of game.js; `sound.tone`
+  makes an effect in code where nothing there fits, in a scene's `create` or at the top of game.js.
+- **The stage is 1920x1080**, fitted to the window or screen with black around it. Lay everything out in those units.
+  The page is never resized to the window: don't listen for resize.
+- **Loading.** Load each scene's files in its `preload`, best all in a first Boot scene, and start play from `create`.
+  A scene that loads mid-game takes what it takes while the game goes on, so it shows a loading line rather than nothing.
+
+### Structure
+
+- **Scenes**: Boot, which loads, then one for each screen of the flow the game picked (the game-ui skill), which is Play
+  alone for a game that opens on play. A pause menu is a scene launched over
+  play (`this.scene.launch('pause'); this.scene.pause()`), which reads the pad itself and resumes play
+  (`this.scene.resume('play'); this.scene.stop()`). Keep the game's state (score, lives, level) in a plain object
+  passed in `this.scene.start('play', state)`, not spread over scenes.
+- **A map as a menu**, where the game-ui skill's example suits: the stops in an array, one sprite tweened between them
+  with `this.tweens.add` as the choice changes, `this.cameras.main.pan` or `zoomTo` from the view before it, and input
+  ignored only for the tween's few frames so a fast press can go on to the next stop. The registered state keeps the stop and the
+  camera's position, and `create` sets them directly from it.
+- **The step**: move by `delta`, and give Arcade physics the work of falling, sliding and colliding. Arcade steps its
+  world at a fixed 60 times a second whatever the screen's rate (its `fps`, the default), so jumps reach the same
+  height on a 120 Hz Mac and a 50 Hz TV. Game logic that must be exact (a puzzle's grid, a rhythm) counts in its own
+  fixed steps from `delta`.
+- **Cameras**: `this.cameras.main.setBounds(0, 0, worldWidth, worldHeight)` and `startFollow(hero, true, 0.12, 0.12)`
+  with a deadzone (`setDeadzone(300, 200)`), so the screen doesn't jerk with every step. Shake and flash
+  (`shake(120, 0.006)`, `flash(150)`) for hits, briefly. The HUD is a second camera's, or HTML over the canvas, never
+  moved by the world's camera (`setScrollFactor(0)` on what's drawn in the scene).
+- **Tilemaps**: write each level as rows of characters in code (`'..........#####....'`), each a tile, and build it with
+  `this.make.tilemap({ data, tileWidth: 64, tileHeight: 64 })`, `map.addTilesetImage('tiles')` and `map.createLayer(0,
+  tileset)`, with `layer.setCollision([...])` and `this.physics.add.collider(hero, layer)`. Rows in code are easy to
+  read and change; there's no level editor here. Make the tileset image in code (below) so every tile is the same size.
+- **Sprite sheets and atlases**: frames of one character or thing in one image, `this.load.spritesheet('hero',
+  'art/hero.png', { frameWidth: 64, frameHeight: 64 })`, played with `this.anims.create({ key: 'run', frames:
+  this.anims.generateFrameNumbers('hero', { start: 0, end: 5 }), frameRate: 12, repeat: -1 })`. Many small pictures in
+  one texture draw in one batch: that's what keeps a busy screen cheap. Pictures made in code are drawn into one
+  texture too (`this.textures.createCanvas`, then `texture.add(name, 0, x, y, w, h)` for each frame).
+- **Physics**: Arcade for nearly every game: boxes and circles, gravity, velocity, `collider` and `overlap` with a
+  callback. A platformer's player is `this.physics.add.sprite` with `setCollideWorldBounds(true)`; it may jump while
+  `body.blocked.down`, with a few frames' grace after leaving a ledge and a jump pressed just before landing still
+  taken. Matter (`physics: { default: 'matter' }`) only when things must tumble, stack, swing on joints or have real
+  shapes (a physics puzzle, a pile of crates): it costs far more a body and its bodies don't stand still as simply.
+- **Many of a thing** (bullets, coins, enemies, sparks): a group made once with `maxSize` and taken from with
+  `group.get(x, y)`. A physics group's member is put back with `disableBody(true, true)` and taken out again with
+  `enableBody(true, x, y, true, true)`: hidden and inactive alone, its body still collides and overlaps, so a
+  collected coin is collected again and a spent bullet still hits. Sprites without bodies are put back with
+  `setActive(false).setVisible(false)`. Particles come from one emitter (`this.add.particles`) with a modest
+  `maxParticles`.
+
+### Controls on every input
+
+Write the controls once as actions on the pad (CONTROLS above) and read the pad through them. The runtime gives a
+controller, the keyboard and the touch controls as that one pad, so the game needs nothing else. Show how to play, and
+every prompt, from the actions: as HTML over the canvas inside `onInput(draw)`, with `glyph(CONTROLS.jump)` in the
+text ("Press [A] to jump", a badge as the player's input draws it), or in a Phaser Text with `label(CONTROLS.jump)`
+("A", "✕", "Space"), redrawn from `onInput`. Leave a line out where `label` is null. When the person asked for the arrow
+keys, `phaser({ keyboardHints: { leftStick: 'arrows' }, … })` makes the hints name them (the game skill, "Controls"). On a phone the touch controls show
+a left stick and the buttons `touch` names: give a platformer jump on A and perhaps one more, and keep the game whole
+with those few. Menus move with the stick or the d-pad, choose with A and go back with B; Menu pauses.
+
+### Pixel art or smooth
+
+- **Pixel art**: `phaser({ pixelArt: true, … })` keeps every pixel sharp, and the camera zooms by a whole number so
+  each art pixel is the same number of screen pixels: `this.cameras.main.setZoom(4)` shows a 480x270 world on the
+  1920x1080 stage (`setZoom(6)` 320x180). Draw the art at that small size, and place things on whole pixels. Never
+  scale pixel art by a fraction, or some pixels come out wider than others.
+- **Smooth** (drawings, painted art, vector shapes): leave `pixelArt` off, draw at the size things appear on the
+  1920x1080 stage, and scale pictures down rather than up.
+
+### Safe areas
+
+On a TV the edge of the picture may be cut off: keep the score, lives and prompts inside the middle 90% of the stage
+(96 px in from the sides, 54 from the top and bottom), and anything the player must see there too. On a phone Lamp's
+touch controls sit in the bottom corners and small buttons in the top corners: put the HUD at the top center or along
+the top edge between them, never under a thumb.
+
+### Drawing the art
+
+Nothing is loaded from the network, ever: the art is in Web/ or made in code.
+
+- **Ready-made sprite sheets and tilesets** from the `assets` tool: a platformer's characters with their walk, jump
+  and hurt frames, enemies, coins, tiles, a space shooter's ships, a top-down racer's cars and track, pixel-art towns
+  and dungeons, UI and icons, each pack in one style. Before drawing a game's characters, enemies and tiles, look
+  there (`find` with `show`): a pack's matching frames are what code and `make_art` struggle to give. Open the assets
+  skill to choose and to load an XML atlas or a tilesheet with spacing.
+
+- **Shapes made in code** are the quickest and always match: draw once with `this.make.graphics({ add: false })`
+  (rectangles, circles, rounded boxes, polygons, a gradient of bands) and `generateTexture('coin', 48, 48)`, in a
+  Boot scene, then use the texture like any picture. A palette of four to eight colors, used everywhere, makes a game
+  look made.
+- **Pixel art in code**: `this.textures.generate('hero', { data: ['..33..', '.3333.', …], pixelWidth: 4 })` draws a
+  picture from rows of palette digits (Phaser's 16-color palette, or give `palette`), a frame per call; it's the way to
+  get a character's frames the same size and style.
+- **Pictures from `make_art`**: for a character, an object or a background in the style of the game's icon, cut out
+  on a transparent background (with `scene` for a whole backdrop). It saves into Assets/: copy what the game uses into
+  Web/art/ (`cp Assets/hero.png Web/art/`) and load it from there. Each picture stands alone, so it suits a hero, a
+  boss, an item or a backdrop rather than animation frames: move one with tweens (a bob, a squash on landing, a tilt as
+  it runs) instead of frames that wouldn't match. Make it once and scale it in the game (`setDisplaySize`).
+- A file the person gave (Attachments/) is copied into Web/ the same way.
+
+Whichever way it's drawn, make it read at a glance: characters and objects with recognizable silhouettes, one sprite
+scale and one outline style throughout, a quieter background behind the action, hazards and rewards that never look
+alike, and animation that shows each action (a wind-up, a landing, a hit). Simple geometric art chosen for the game is
+fine.
+
+### Sound and saves
+
+The game skill's: look in the `assets` tool first for an effect for each thing the player does or meets and for the
+music, loaded once; `sound.tone` only for what nothing there fits (a jump sliding up, a coin's two quick notes, noise
+for a hit), made once; music quiet or none. The best score, levels reached and settings with
+`save(name, value)` and `load(name)`, read with a default for anything new (`load('best') ?? 0`).
+A registered state keeps the player's place through a change (the scene, its mode, which menu or DOM card is
+open, the player's position, the score, the time), and `busy()` in phaser() holds a change that runs the game's code again during a round (the game skill,
+"Changes while it's played"). A 2D game registers only its state: Phaser's game and cameras are made again from it. The first scene
+goes straight to the scene the state names, and that scene's `create` builds that place with no title card or intro,
+so a fresh start and a change's start are one path:
+
+```js
+const play = hot(import.meta).state('play', {
+    version: 1,
+    start: () => ({ scene: 'play', mode: 'ready', level: 1, score: 0, paused: false, player: { x: 120, y: 400 } }),
+});
+class Boot extends Phaser.Scene {
+    constructor() { super('boot'); }
+    preload() { … }
+    create() { this.scene.start(play.scene); }
+}
+class Play extends Phaser.Scene {
+    constructor() { super('play'); }
+    create() {
+        play.scene = 'play';
+        this.level = buildLevel(play.level);
+        this.hero.setPosition(play.player.x, play.player.y);
+        if (play.paused) this.showPause(); else if (play.mode === 'ready') hud.card(`Level ${play.level}`);
+    }
+    update() { play.player.x = this.hero.x; play.player.y = this.hero.y; … }
+}
+```
+
+A picture Phaser's loader read goes in again through `assetChanged(path)` in phaser() (load it again and
+swap the texture), or the game's code runs again in place from the state.
+
+### Keeping it smooth on the slowest place
+
+The slowest places are an Xbox One in Developer Mode, a cheap Android phone or TV stick and a Samsung or LG TV's
+browser; the request's device line names the slowest this game is played on and its budget. In 2D what costs is draws and filling the screen, rarely shapes:
+
+- few textures: sprites that share one texture (an atlas, or the shapes made into one canvas texture) are drawn in
+  one batch, and every change of texture starts another;
+- a Text object redraws its whole picture when its text changes: change it only when the number does, never every
+  frame (or use HTML over the canvas for the HUD);
+- a Graphics object drawn in play is redrawn every frame: make it a texture once instead;
+- layers of big pictures over the whole screen (parallax backgrounds, a full-screen overlay) each fill the screen
+  again: two or three at most on a TV;
+- effects (`preFX`, `postFX`, glow, blur, bloom) are full extra passes: none on a TV or an Xbox One;
+- no allocation per frame, and pools for what comes and goes; Arcade rather than Matter.
+
+The log on a device says every ten seconds how many frames a second it gets there: when it's short of 60, draw less.
+
+### Checking it
+
+`look_at_app` shows the game in its window on this Mac, where the person is in it, opening it when it's closed;
+`use_app` plays it there with Lamp's own controller (`stick`, `button`, `wait`, and a `click` on what its screen shows), from wherever it is, a picture at the
+end (the game skill, "Playtesting"). When the person asks you to try, play or test it, play it as they would: start
+it, jump, die, win, pause, change a setting and come back to find it kept. Once it looks or plays right there,
+`look_at_app` with `on_device` looks at it in the preview of where Try On points (the iPhone or iPad simulator); the
+person's own iPhone, iPad or Xbox is only for their Play.
+
+## SpriteKit in a Mac or iPhone app
+
+The game is an `SKScene` subclass for each screen, shown in SwiftUI with `SpriteView`, with SwiftUI over it for the
+score, menus and prompts (the game-ui skill says how to choose a game's screens and how they look):
+
+```swift
+import SwiftUI
+import SpriteKit
+
+struct GameScreen: View {
+    @State private var scene = PlayScene(size: CGSize(width: 1920, height: 1080))
+    var body: some View {
+        SpriteView(scene: scene, preferredFramesPerSecond: 60, options: [.ignoresSiblingOrder])
+            .ignoresSafeArea()
+            .overlay(alignment: .top) { ScoreBar(score: scene.score) }
+    }
+}
+```
+
+Make the scene once (`@State`), never in `body`. A scene of a fixed size with `scaleMode = .aspectFit` is laid out
+once and letterboxed on any window, like the game kind's stage; `.resizeFill` with an `SKCameraNode` following the
+player shows more of a big world on a big window. What SwiftUI shows over it (the score, lives, a pause) comes from
+the scene as `@Observable` (Observation), which `@State` holds as above; a scene that is an `ObservableObject` with
+`@Published` values is held with `@StateObject` instead, or the view never sees them change.
+
+- **The step**: `update(_ currentTime:)` works out the time since the last frame (at most 1/20 s, so a pause doesn't
+  jump) and moves by it; physics bodies move themselves. Logic that must be exact counts fixed steps of 1/60 s from it.
+- **Cameras**: an `SKCameraNode`, `scene.camera = cam`, moved toward the player each frame (`cam.position +=
+  (target - cam.position) * min(1, dt * 8)`) and kept inside the level; the HUD is SwiftUI, or nodes added to the
+  camera.
+- **Tiles**: for a level of rows in code, a sprite per tile is fine to a few thousand; past that, draw the level's still
+  part once into one texture (`view.texture(from: node)`) and show that. `SKTileMapNode` with a tile set made in code
+  works too, for a big grid.
+- **Sprite sheets**: one picture cut into frames with `SKTexture(rect:in:)` (the rect in 0-1 of the sheet), played with
+  `SKAction.animate(with:timePerFrame:)`. Textures of one `SKTextureAtlas`, or cut from one sheet, draw in one batch.
+- **Physics**: `SKPhysicsBody(rectangleOf:)` or `(circleOfRadius:)`, each with its `categoryBitMask`,
+  `collisionBitMask` and `contactTestBitMask`, and the scene as `physicsWorld.contactDelegate` hearing
+  `didBegin(_:)`. A platformer's ground is one body for each run of tiles side by side, not one per tile, so the player
+  doesn't catch on the seams; give the player `allowsRotation = false` and set its velocity rather than pushing it.
+- **Controls**: a controller through GameController, read each frame from `GCController.current?.extendedGamepad`
+  (`leftThumbstick`, `dpad`, `buttonA`…, and `buttonMenu` to pause); on the Mac the keys with
+  `NSEvent.addLocalMonitorForEvents(matching: [.keyDown, .keyUp])`, keeping the keys held in a set and returning nil
+  for the game's keys (so they don't beep); on an iPhone, touch: `GCVirtualController` with a left stick and one or
+  two buttons draws them over the game and reads as a controller, so one reading covers both. Name a controller's
+  buttons from the controller itself (`buttonA.sfSymbolsName` as an `Image(systemName:)`, or `localizedName`), never
+  a fixed letter, and keys by the key ("Space", "←").
+- **Pixel art**: `texture.filteringMode = .nearest` on every texture, positions rounded to whole pixels, and the scene
+  scaled by a whole number.
+- **Sound and saves**: as the game skill says for Swift (files with AVAudioPlayer or effects made once with AVAudioEngine, `.ambient` on iPhone),
+  and the best score and settings in LampStore.
+- **Game Center** (`GKLocalPlayer.local.authenticateHandler`, leaderboards) works only in an app signed for the
+  person's Apple team with Game Center on: keep the game whole without it, scores in LampStore as well.
+- **Art**: as above: shapes in code (`SKShapeNode` drawn once into a texture with `view.texture(from:)`, since a shape
+  node is costly to draw), pictures from `make_art` in Assets/ loaded once with `LampAssets.image("hero.png").map(SKTexture.init(image:))`.
+
+Look with `look_at_app` (with `motion` for what moves), and use it with `use_app`, keys and clicks, when the person
+asks you to try it: the game skill's "Playtesting" says what to say otherwise. Its "Keeping every frame smooth" holds
+here too.

package/Resources/skills/3d-game/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: 3d-game
+description: 3D games and scenes in a web page with three.js, on any device that runs web, TVs included - which library 3D is drawn with, loading it and the renderer on Lamp's game runtime or in a TV or device page, models, light and materials, physics with Rapier (things that fall, roll, stack and collide, a player that walks on them, a car on its wheels), and what costs the most. Read before writing or changing 3D in a web page.
+---
+
+# 3D in a web page
+
+three.js runs in a page wherever the device takes a page (`make_app_for`'s table) and its browser gives WebGL 2: a
+host for the page isn't enough on its own, so check WebGL 2 first (below). What differs then is speed: a Mac draws far
+more than a phone, and a TV's chip is often slower than a phone's. Nothing here limits what you make; it says what
+costs the most, so you can choose what the game is worth on the devices it's played on.
+
+Lamp ships three.js in two kinds of page: a game's page on its runtime (`make_app_for` with `kind` "game"), and a page
+with no runtime: a Samsung or LG TV app's page, or a device integration's web app whose rules name the 3D library's folder. A page with no
+runtime has no game runtime, no Phaser bridge and no Rapier: it loads three.js from the folder its rules give and makes
+its own renderer and frame loop (below).
+
+A 3D game is made this way by default, on every device Lamp has a host for a page on, the Mac included. 3D in Swift,
+in a Mac app made natively (because the person asked for native, or the app was made so), is the scene-3d skill's
+(RealityKit through LampSceneView); native 3D on iPhone, iPad or Apple TV is written with that device's own
+frameworks. A game whose play is flat is better made in 2D with Phaser (the 2d-game skill), which also runs where a
+TV's browser has no WebGL 2. The game skill holds what every game needs
+(the frame loop, controls, sound, saves); read it too.
+
+A menu that's a place (the game-ui skill) is a list of stops with a camera position for each, eased between in `frame`,
+with the stop in the game's registered state and the camera registered (the game skill, "Changes while it's played").
+
+## The renderer
+
+### A game on Lamp's runtime
+
+index.html loads lamp.js, then the scaffold's import map, then game.js as a module: keep that. The import map's
+`three` and `three/addons/` come from `Web/three`: the WebGL build and its addons such as GLTFLoader. `three/webgpu`
+and `three/tsl` (node materials, drawing with WebGL 2) are added once the page imports them, and only a heavy scene
+needs them. Nothing else is there, so no Draco or KTX2 files (the `assets` tool brings in none), and nothing is
+loaded from the network. Physics is
+Rapier, mapped in the import map when a game needs it (Physics, below).
+
+game.js registers one renderer, `live.renderer(() => new THREE.WebGLRenderer({ antialias: true }))` (with
+`const live = hot(import.meta)`), each camera with `live.camera(id, build)` and its state with `live.state` (the game
+skill, "Changes while it's played", has the recipe), and calls `game({ renderer, init, frame, touch })` from
+lamp-game.js once. A `WebGPURenderer` is made and given its `await r.init()` in an async build:
+`const renderer = await live.renderer(async () => { const r = new THREE.WebGPURenderer(); await r.init(); return r; })`.
+
+- Lamp sizes the canvas to 1920x1080 and fits it to the window or screen.
+- `init` runs once, before the first frame. It may be async, to load models with
+  `new GLTFLoader().loadAsync('ship.glb')` or sounds; make or load every sound here. It builds what the state says:
+  the level, the player and the open menu or overlay from the registered state, which is already back after a change
+  of the code, and the opening (a title, an intro, a briefing) only when `play.mode` says so (the game skill, "Changes
+  while it's played"; the game-ui skill says how a game opens and what its menus are). A camera's start pose goes in its `build`, never here.
+- `frame(f)` runs about 60 times a second. It reads the controller as `f.pads[0]`, moves things by `f.dt` (and
+  `f.time`), and ends with `renderer.render(scene, camera)`.
+- `touch` names the buttons Lamp's touch controls show on a phone or tablet.
+- game.js only puts the parts together, and keeps the scene, the lights and the world's parts with
+  `hot(import.meta).keep` (the game skill, "Changes while it's played", has the recipe). The world is built in parts (the ground, the
+  buildings, the trees and street details, the props, the traffic), each in a module of its own and into a group of
+  its own, kept with the data it's built from as its `from`, so a change to one part or its data builds only that
+  part again, and a part that's slow to build (the city, the terrain, the traffic) with `background: true`, built in
+  steps or with a worker, so the game plays on while it's built (the game skill's recipe); each thing that moves or changes in play (the player,
+  a vehicle, the camera, enemies, the HUD's code) is a class in a module that ends with `hot(import.meta).accept()`,
+  so a change to its methods goes into the running scene with nothing built again. A uniform's value or a material's
+  color set in an `update` swaps; a material made anew compiles its shader again, which Lamp does before the
+  first frame after a change while the frame before stays on screen, so a world's materials are made in its kept parts.
+
+A page laid out at the window's size whose HUD is its own HTML (a strategy game, a page made for phones as well as
+TVs) passes `fill: true` to `game()` and places and sizes its canvas itself, drawing it smaller when frames run slow;
+the rest of this section is for a game drawn at 1920x1080.
+
+When frames run slow, Lamp draws the game smaller and scales it up to the screen by itself (`sharp: true` in `game()`
+keeps it at 1920x1080), so size anything drawn off-screen (a render target, a post-process pass) from
+`renderer.getSize()`, never from 1920x1080. Read lamp-game.js's comments first: they're the whole interface.
+
+### A page with no runtime (a TV app, a device's web app)
+
+The page's rules name the folder Lamp writes three.js in and the path the page reaches it at (`./three/` in a Samsung
+or LG TV app's Web/). Lamp writes that folder before every build: never edit it. In index.html, after lamp.js, put the
+import map with that path:
+
+```html
+<script type="importmap">{ "imports": { "three": "./three/three.module.js", "three/addons/": "./three/addons/" } }</script>
+```
+
+then the 3D code in a `<script type="module">` (or a module file of your own beside it), with
+`import * as THREE from 'three'` and addons from `'three/addons/…'`. Use this three.js for anything 3D, never another
+engine or one from the network. Make the renderer yourself, sized to 1920x1080 at a pixel ratio of 1 (the page is laid
+out at that size and scaled), and draw from your own `requestAnimationFrame`, moving everything by the time since the
+last frame. Modules and import maps need a newer TV browser than the oldest the TV rules allow for, and three.js needs
+WebGL 2 (next).
+
+The three.js Lamp ships asks the browser only for a WebGL 2 context and stops with an error when it gets none, so
+WebGL 2 comes before anything else here: check on the device that a canvas gives one (log whether
+`canvas.getContext('webgl2')` returns a context, and ask the person to try it there with Play, since Lamp's looks
+never reach their device). Most browsers
+have it; not every Samsung TV does. Where it's missing, make the game another way (2D with Phaser, which draws with WebGL 1 or a plain canvas, or native on that
+device) or tell the person why 3D in a page can't run there.
+
+## Models, light and materials
+
+- Before building a game's buildings, vehicles, characters or trees in code, look in Lamp's free models (`assets` with
+  `find` and `show`; the assets skill): many distinct things, and anything that walks or runs, come out better
+  ready-made. Shapes made in code (boxes, spheres, cylinders, extruded outlines), well lit and colored, often look better than
+  mismatched models, and cost little. Build each character and prop as a `THREE.Group` of them in a function of its
+  own (a body, a head, eyes that blink, wheels that turn, a tail that wags), its parts named so they can move, and
+  give it a little life: a bob, a lean into a turn, a squash on landing. A model file (a .glb) is one the person
+  gave or named, or a ready-made one from the `assets` tool (buildings, vehicles, characters with animations, trees:
+  the assets skill says when they suit and how to scale, turn, copy and animate them). It goes in Web/ and loads once
+  in `init` with lamp-game.js's `model('ship.glb')` (a group holding its scene, with `group.animations`), and a picture with
+  `texture('bricks.png', t => { t.colorSpace = THREE.SRGBColorSpace; })`: a new copy of either goes into the running
+  game, inside the same group or texture. A clone of the model, or a mixer playing its animations, is made again in
+  `assetChanged(path)` (the game skill, "Changes while it's played").
+- One or two lights computed in the shader are the safe start. MeshStandardMaterial looks good under them;
+  MeshLambertMaterial or MeshBasicMaterial cost less.
+- Make every mesh, material and texture once in `init` and reuse it; many copies of one shape are one
+  `THREE.InstancedMesh`.
+- Compose the view, within the same budget: a camera framing what the player needs to see ahead, things at one
+  consistent scale, light that separates the player and hazards from the ground, and contact cues (a blob shadow, a
+  dust puff) that put things on the ground instead of floating.
+
+## Physics
+
+**Whether a game needs it.** Most don't. A runner, a shooter, a racer on a track or a platformer on flat ground moves
+things by its own rules and tests what touches what itself: the distance between two centers, two boxes
+(`THREE.Box3`), a ray down to the ground over a few meshes (`THREE.Raycaster`). That costs nearly nothing and does
+exactly what the game means. Physics is for games whose fun is things behaving like things: a stack of crates that
+topples, marbles that roll and knock into each other, a board that tilts, a ball through pins, a car on its
+suspension, a door on a hinge, a chain, a pile of anything. Once a game starts writing its own bounces, stacking or
+rolling, it wants physics: hand-made physics is where objects sink, jitter and pass through walls.
+
+**Rapier.** Lamp ships Rapier, a physics engine in WebAssembly, as one module that loads like three.js does,
+wherever the game is played. It's for a game's page on its runtime; a TV app's page doesn't get it. Add it to the import map in index.html,
+`"@dimforge/rapier3d-compat": "./rapier/rapier.js"`, and Lamp puts `Web/rapier/` beside the page (it's Lamp's, like
+`Web/three/`; a game that doesn't import it doesn't carry it). Start it once, in `init`, and step the world with
+`fixedStep` from lamp-game.js:
+
+```js
+import * as THREE from 'three';
+import RAPIER from '@dimforge/rapier3d-compat';
+import { game, fixedStep } from './lamp-game.js';
+
+let world, events, physics, pad, presses = 0;
+game({ renderer, async init() {
+    await RAPIER.init();
+    world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });
+    events = new RAPIER.EventQueue(true);
+    physics = fixedStep(() => { steer(); world.step(events); events.drainCollisionEvents(hit); });
+    // … the ground, the bodies and their meshes
+}, frame(f) {
+    pad = f.pads[0];
+    presses |= pad.pressed;   // kept until a step uses them
+    physics(f.dt);
+    place();
+    renderer.render(scene, camera);
+} });
+
+function steer() {
+    // Held buttons and sticks are read as they are now, every step.
+    ball.applyImpulse({ x: pad.lx * PUSH, y: 0, z: -pad.ly * PUSH }, true);
+    // A press is used by one step only: a frame can run no step (at 120 frames a second) or two (at 30).
+    if (presses & CONTROLS.jump) ball.applyImpulse({ x: 0, y: JUMP, z: 0 }, true);
+    presses = 0;
+}
+```
+
+- `await RAPIER.init()` goes inside `init` (never at the top of the module), so a failure is the game's start-up
+  error, which the game's log and the look report.
+- The world steps 1/60 s at a time (`world.timestep`, its default), the step `fixedStep` runs as often as the frame
+  needs, so the game plays the same at 30, 60 or 120 frames a second. Never pass `f.dt` to the world or change `timestep` per frame. Anything that
+  pushes bodies (the controls, a motor) runs inside the step, as `steer()` does above, reading the pad the frame
+  kept. A press (`pressed`, `released`) belongs to a frame, not a step: gather it into `presses` in `frame` and let the
+  first step that runs use it and clear it, or a jump is lost at 120 frames a second and done twice at 30. Anything
+  random in the setup comes from `random()`.
+- Meters, kilograms and seconds, y up, as three.js has them. Keep things their real size: a box a meter across, a
+  marble a few centimeters. Rapier's tolerances are tuned for things about a meter across: in a world of small things
+  (a tabletop maze, marbles, dice) set `world.lengthUnit` to their typical size in meters (0.05 for marbles), or they
+  sink into each other and jitter. Small fast things can pass through thin walls between steps: make walls thick, or
+  give the fast body `setCcdEnabled(true)`.
+
+**Bodies and colliders.** A body is how a thing moves; its colliders are its shape.
+
+- Fixed (`RigidBodyDesc.fixed()`): what never moves, the ground, walls, the track.
+- Dynamic (`RigidBodyDesc.dynamic()`): moved only by physics, crates, balls, debris. Push it with `applyImpulse` (a
+  kick) or `addForce` (a steady push), never by setting its position each frame.
+- Kinematic (`RigidBodyDesc.kinematicPositionBased()`): moved by the game, pushing dynamic bodies without being
+  pushed back: a moving platform, a tilting board, a door the game opens. Give it its place each step with
+  `setNextKinematicTranslation` and `setNextKinematicRotation`.
+
+Colliders are simple shapes: `ColliderDesc.cuboid`, `ball`, `capsule`, `cylinder`, `roundCuboid` (a box with
+rounded edges rolls and stacks more kindly), several on one body for a shape made of parts (a table: a top and four
+legs). A model's look never becomes its collider: an odd shape that moves is a `convexHull` of a few of its points,
+a level that never moves may be a `trimesh` of a simplified mesh, and land is a `heightfield`. Bounce, grip and weight
+are the collider's: `setRestitution`, `setFriction`, `setDensity`.
+
+**Meshes in step with bodies.** Keep each body with the mesh that shows it and copy the body onto the mesh after the
+step, straight into three.js's own objects, so nothing is allocated per frame:
+
+```js
+const things = [];   // { body, mesh }
+function place() {
+    for (const t of things) { t.body.translation(t.mesh.position); t.body.rotation(t.mesh.quaternion); }
+}
+```
+
+Many of one thing (a hundred crates) are one `THREE.InstancedMesh`: read each body into one Vector3 and Quaternion
+kept for it, `matrix.compose(position, quaternion, scale)`, `setMatrixAt(i, matrix)`, and set `instanceMatrix.needsUpdate`.
+
+**The player.** A character that walks, climbs steps and stands on slopes is a kinematic body with a capsule and
+Rapier's character controller, rather than a dynamic ball pushed around:
+
+```js
+const controller = world.createCharacterController(0.02);
+controller.enableAutostep(0.3, 0.2, true);   // steps up to 30 cm
+controller.enableSnapToGround(0.3);
+controller.setMaxSlopeClimbAngle(45 * Math.PI / 180);
+// each step: where the player wants to go this step, gravity included
+controller.computeColliderMovement(playerCollider, wanted);
+const moved = controller.computedMovement(), at = playerBody.translation();
+playerBody.setNextKinematicTranslation({ x: at.x + moved.x, y: at.y + moved.y, z: at.z + moved.z });
+const grounded = controller.computedGrounded();   // may jump
+```
+
+The game keeps the player's own vertical speed (gravity added each step, set on a jump, zeroed when grounded).
+
+**A vehicle.** A car is a dynamic body (a box for the chassis, its weight low) and Rapier's vehicle controller, which
+casts a ray for each wheel and gives it suspension and grip:
+
+```js
+const car = world.createVehicleController(chassis);
+const down = { x: 0, y: -1, z: 0 }, axle = { x: -1, y: 0, z: 0 };
+for (const [x, z] of [[-0.8, 1.3], [0.8, 1.3], [-0.8, -1.3], [0.8, -1.3]]) car.addWheel({ x, y: 0, z }, down, axle, 0.3, 0.35);
+// each step: steering on the front wheels, engine and brake on the back
+car.setWheelSteering(0, steer); car.setWheelSteering(1, steer);
+car.setWheelEngineForce(2, gas); car.setWheelEngineForce(3, gas);
+car.updateVehicle(world.timestep);
+```
+
+Wheels are drawn from the controller (`wheelSuspensionLength(i)`, `wheelRotation(i)`, `wheelSteering(i)`), not given
+bodies of their own. Tune `setWheelFrictionSlip` and the suspension by driving it in its window (`use_app`).
+
+**Joints** hold two bodies together: `RAPIER.JointData.revolute` (a hinge: a door, a wheel, a flipper),
+`prismatic` (a slider), `spherical` (a ball joint: a chain link, a pendulum), `fixed` (welded), made with
+`world.createImpulseJoint(data, body1, body2, true)`. A hinge can be driven with `configureMotorVelocity`.
+
+**What touched what.** Give a collider `setActiveEvents(RAPIER.ActiveEvents.COLLISION_EVENTS)` and read
+`events.drainCollisionEvents((a, b, started) => …)` after each step, a pair of collider handles: keep a `Map` from
+handle to the game's thing. A sensor (`setSensor(true)`) is a zone that's felt but not hit: a goal, a pickup, a
+checkpoint. A collision is the moment for a sound and a rumble.
+
+**Keeping it light.** Physics runs on the CPU, before anything is drawn, so it takes from the same 16 ms. Resting
+bodies fall asleep by themselves and then cost almost nothing: leave them be (don't set their position or velocity
+unless something happens to them), and when the game moves a sleeping one itself, `wakeUp()` it. Balls, boxes and
+capsules are cheapest; convex hulls cost more, trimeshes most. Where the request's device line names a slow place
+(a TV, a streamer, an older console), keep to about 100 dynamic bodies awake at once, with a few hundred more asleep or
+fixed; a Mac takes a thousand. Step only through `fixedStep`, never make a body or collider per frame (make them in `init` or when a level starts, and reuse them), and remove what
+falls out of the world (`world.removeRigidBody`). The device's log says how its frames keep to time: when they're late
+with physics in play, make fewer bodies move at once before drawing less.
+
+## What costs the most
+
+Roughly in order: shadow maps (each light that casts one draws the scene again), full-screen effects
+(post-processing, bloom), many lights, a high pixel ratio (lamp-game.js already draws at 1, never at the screen's own),
+many draw calls (each distinct mesh and material), large textures, and many triangles.
+
+## On a TV
+
+Some platforms might not be powerful enough to run three.js.
+
+## Checking it
+
+`look_at_app` shows the game in its window on this Mac, where the person is in it, opening it when it's closed; its
+log says every ten seconds how it kept to its frames there, which says nothing of a slower device's: keep to the budget
+in the request's device line. `use_app` plays it there with Lamp's own controller. `look_at_app` with `on_device` looks
+at the game in the preview of where Try On points (the iPhone or iPad simulator), never the person's own device, so its
+frame times there say nothing of a phone's either.
+When the person asks you to try, play or test it, play it as the game skill's "Playtesting" says.

package/Resources/skills/accounts/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: accounts
+description: The person's calendar, reminders, contacts, mail and cloud files through the accounts already on the device, and on a Mac what lives in another app they use (LampComputer). Read before an app reaches any of them, including when a wish names a service such as "my Google Calendar".
+---
+
+# The person's own accounts and apps
+
+When a wish needs the person's calendar, reminders, contacts, mail or files, reach first for what the device is
+already signed in to, before any service's API, sign-in, key or connector.
+
+## Calendar, reminders and contacts (Mac and iPhone)
+
+They come through the accounts already on the device (iCloud, Google, Exchange, Outlook), with no sign-in or key, from
+LampSupport.swift: `LampCalendar.events(from:to:)` / `.add(...)`, `LampReminders.open()` / `.add(...)` /
+`.complete(id)`, `LampContacts.search("name")` / `.find(email:)`.
+
+## Mail and files (Mac only)
+
+- Email: `LampMail.inbox(limit:)` / `.search(text)` / `.body(of:)` / `.draft(to:subject:body:)` (a draft opens in Mail
+  for the person to send; nothing is sent by the app).
+- Their files in Google Drive, Dropbox, OneDrive or iCloud Drive are folders on the Mac: `LampFolders.synced` lists
+  them and `LampFolders.synced("Google Drive")` gives one; read, write and watch them as files.
+
+## What a service's name means
+
+A wish that names a service ("my Google Calendar", "my Gmail", "my Outlook contacts", "my Dropbox") means these:
+never call the service's web API, never ask for a key, a sign-in or a developer registration, and don't ask which
+service they use. When their account or folder isn't on the Mac, the app says in one line where to add it (System
+Settings → Internet Accounts, the service's own Mac app, or Mail) and works once it's there. macOS and iOS ask the
+person once per kind of data; each call throws a plain message if refused, so show `error.localizedDescription`.
+
+## Another app the person uses (Mac only)
+
+When the information or the job lives in another app the person uses and the accounts and synced folders above and
+`connectors` can't reach it (Slack, Messages, Notes, or a site in their browser such as LinkedIn or a CRM), use
+`LampComputer.ask("…")` to read it or `LampComputer.perform("…")` to act there, from LampSupport.swift. It works with
+what they're already signed in to, with no API keys or connectors, and returns text (ask for JSON in the task when
+the app needs structure). Calls take 10–60 seconds, so run them when the person asks (a button), never on a timer,
+and show progress. `perform` asks the person before every click or keystroke. Prefer files, LampText and the web when
+they can do the job, and prefer the accounts above to LampComputer for mail, calendar, people and files: they're
+instant and free.