@origingame/engine 0.4.0 → 0.5.0

package/knowledge/skills/og-build/SKILL.md

@@ -53,8 +53,9 @@ a number and a sound (taste 98, feel 79).
    `get:<Resource>[.<field>]` or `get:<entity>[.<Component>[.<field>]]`
    (logs the value as game code sees it, og.Time whole and a light og.DayNight
    drives as it is drawn, and writes `get-<tick>.json`, then
-   `get-<tick>-2.json`, ... for more on one tick; a world dump lists
-   resources by name only, so `get:` is how to read one),
+   `get-<tick>-2.json`, ... for more on one tick; `get:Game:game.json`
+   names the file; a world dump lists resources by name only, so `get:`
+   is how to read one),
    `set:<entity>.<Component>.<field>=<value>` or
    `set:<Resource>.<field>=<value>` (`set:og.Camera.trauma=0.5`,
    `set:Game.coins=10`, `set:og.Stylise.ink=false`: a number, `true` or
@@ -98,7 +99,46 @@ each its argument form and one sentence in `GameDesc.commandHelp`
 (`{ spawn_wave: { usage: "<count>", doc: "Spawns a wave now." } }`)
 so `help` explains it (it lists `spawn_wave:<count>`: the name, then the
 usage). An entry naming no action is logged when the game
-starts.
+starts. A step's arguments are its colon-delimited fields after the
+action, never shell words: `0.5:records:12:34.5` hands the handler
+`args[0]` `"12"` and `args[1]` `"34.5"`, and its usage is written the same
+way, `usage: "<berries>:<seconds>"` (a space stays inside its field:
+`records:12 34.5` is one argument). A game may not take a core action's
+name; og-game §3 lists them, with `open_pause` beside the engine's `pause`.
+
+**File names.** Every output of one script has its own file. An unnamed
+output takes the action and the tick (`get-000030.json`), and a second on
+the same tick is suffixed quietly (`get-000030-2.json`). A named one that
+an earlier step of the script already wrote, at any time (a copy-pasted
+`0.5:get:Game:met.json`), is written as `met-2.json`, then `met-3.json`,
+never over the first, and logs a WARN naming both steps ("'met.json' was
+already written by the 0.5s get step, so this one is 'met-2.json'"). The
+WARN is in `run.warnings`, so a playtest that asserts a clean run
+(`t.equal(run.warnings.length, 0, ...)`) fails on the clash, and
+`run.json("met.json")` reads the first step's: give each named step its
+own file.
+
+**Values in the JSON.** A dump and a `get` answer write a vector as an
+array in lane order (`Vector3` `[x, y, z]`, `Quaternion` `[x, y, z, w]`,
+`Color` `[r, g, b]`), where the API's values are objects
+(`{ x, y, z }`); `set:` takes the lanes comma-separated, without spaces
+(`set:box.og.Transform.position=4,5,6`). Read a dump by index:
+
+```ts
+// 0.3:get:box.og.Transform:t.json writes {"kind":"get","target":"box.og.Transform","tick":18,"value":{"position":[1,2.5,-3],...}}
+const [x, y, z] = run.json<{ value: { position: [number, number, number] } }>("t.json").value.position;
+t.near(y, 2.5, 1e-4, "the box stands on the ledge");
+```
+
+An `f32` field is IEEE-754 single precision. Game code reads it as the
+f32's exact value promoted to a JavaScript number, so `2.7` written to an
+f32 reads back as `2.700000047683716`, and what game code sends carries
+that number as JSON (the facts, an og.platform payload, so
+`dump_platform`); `get` and the dumps print the f32's shortest form,
+`2.7`. Compare numbers with a tolerance in a test (`t.near(a, b, 1e-4,
+...)`), round only to display one (`toFixed(1)` on the label), and keep a
+value that must round-trip exactly (a payload a test compares with `===`)
+in an `f64` field.
 
 ## 2. Live sessions: the probe and hot reload
 
@@ -205,7 +245,7 @@ every screen that matters.
 | taste | UI sounds | a press that changed the UI and started a voice on the ui bus within 8 ticks | every press | og-taste §6, og-audio §3 |
 | taste | Locale keys | `og cook`'s warnings | none | og-i18n §1 |
 | feel | Input latency | ticks from the tick an input lands to the first thing seen or heard to change (a named entity accelerating or changing clip, the UI, a sound, a tween, a floating text, shake, hit stop, a particle burst); a press answered on its release counts from the release | 0–1 ticks | og-feel §1 |
-| feel | Hit feedback | each damage moment (a fact named `hp`, `health`, `lives`… falling, or `hits`, `damage`, `kills`… rising): hit stop, shake, floating text and a sound within 8 ticks | three of the four | og-feel §3, §4, §7, og-audio §1 |
+| feel | Hit feedback | each damage moment (a fact named `hp`, `health`, `lives`… falling, or `hits`, `damage`, `kills`… rising): hit stop, shake, floating text and a sound within 8 ticks | three of the four, per moment (a moment with three owes no fourth: a bump that holds, shakes and sounds is not asked for a number) | og-feel §3, §4, §7, og-audio §1 |
 | feel | Idle frames | ticks after the first ten where nothing moves or animates, no UI moves, no sound starts or plays, no tween, text or particle runs | at most 10 % | og-feel §9, og-taste §5 |
 | feel | Sound on input | inputs answered by a sound within 6 ticks | every action | og-audio §1 |
 | feel | Frame time | step + render, p95, on the tier it ran on (`metal` on a Mac, `vulkan` on a GPU); the probe's own screenshots (render, read back, PNG) are not the game's step and are left out. Without a renderer the row says `n/a (no renderer)`, as do contrast, text size and HUD occupancy, which read frames | 8.3 ms (half the frame) | og-game §14 |

package/knowledge/skills/og-core/SKILL.md

@@ -240,9 +240,10 @@ export const Move = defineSystem("Move", { reads: [Velocity], writes: [og.Transf
   entity each.
 - A handle is a 64-bit number (an `og.load` answer, a texture, a sound,
   a geometry, a material, an entity): keep it in a field of its own kind,
-  `Asset()`, `Texture()`, `Sound()`, `Geometry()`, `Material()` or
-  `Entity()` (each handle type of the API has its factory), in a
-  component or a resource. A `u32` field refuses one (`4294967298 is not
+  `Asset()`, `Texture()`, `Sound()`, `Font()`, `Style()`, `Look()`,
+  `Geometry()`, `Material()` or `Entity()` (each handle type of the API
+  has its factory, named as the type: a font is a `Font()`, never an
+  `Asset()` cast), in a component or a resource. A `u32` field refuses one (`4294967298 is not
   a u32`).
 - Per-entity calls (`world.get`, `world.set`) are for commands, setup and
   the few named entities a system touches (a camera, a listener, the

package/knowledge/skills/og-feel/SKILL.md

@@ -169,7 +169,10 @@ it is a cutscene or a reward.
 ## 7. Floating text
 
 `og.render.floatingText(world, { text, position, ... })` pops a text that
-rises, drifts and fades by itself (world state, deterministic).
+rises, drifts and fades by itself (world state, deterministic). A label
+that stays with a character (a name tag, a player's number) is not
+floating text: it is screen text where the og.Camera resource's
+`worldToScreen` puts the point, og-ui §3 (Text over a world point).
 
 - Damage and score numbers above the hit point, not on the HUD: the eye is
   already there. Pickups: what was gained (`+1`, `key`), short.
@@ -180,6 +183,11 @@ rises, drifts and fades by itself (world state, deterministic).
   biggest number on screen should be the most important.
 - Lifetime 0.6–1.0 s, rise 0.8–1.5 units, spread 0.2–0.4 so stacked hits do
   not overlap. At most 6–8 on screen: sum rapid hits into one number.
+- Not every impact wants a number. An impact is held by three of four
+  signals (hit stop §3, shake §4, floating text, a sound): `og polish`
+  counts them per damage moment and asks for the missing ones only of a
+  moment with fewer than three, so a party game's bump that holds, shakes
+  and sounds owes no floating text.
 
 ## 8. Camera: look-ahead, dead zones, zones, rails
 

package/knowledge/skills/og-game/SKILL.md

@@ -213,6 +213,36 @@ export default og.game({
   channel and playtests can call (`0.5:spawn_wave:3`), with their usage in
   `GameDesc.commandHelp` for `help` (og-build §1). Add one for each state a
   test needs to reach quickly, instead of playing there.
+  - **Arguments are colon-delimited**, the fields after the name, each a
+    string (`Number(args[0])` to read a number); a space is part of its
+    field, not a separator, and `\:` writes a colon inside one. Two
+    arguments, and the usage that says so:
+
+    ```ts
+    commands: { records: (world, args) => setRecords(world, Number(args[0]), Number(args[1])) },
+    commandHelp: { records: { usage: "<berries>:<seconds>", doc: "Sets the isle's records." } },
+    ```
+
+    `0.5:records:12:34.5` hands `args` `["12", "34.5"]`; `records:12 34.5`
+    would hand one argument, `"12 34.5"`.
+  - **Reserved names.** The channel's core actions are not a game's to
+    take, and the game refuses to start on one (`'pause' is a core action;
+    register under another name`): `screenshot`, `listen`, `touch_move_to`,
+    `touch_move`, `touch_start`, `touch_end`, `touch`, `scroll`, `gamepad`,
+    `key_down`, `key_up`, `type`, `compose`, `commit`, `move_to_text`,
+    `teleport`, `frame_entity`, `dump_world`, `dump_entity`, `dump_ui`,
+    `get`, `set`, `seed`, `pause`, `resume`, `advance`, `describe`,
+    `expect`, `save_scene`, `quit` and `help`. The actions the engine's
+    modules register are refused the same way (`'view' is a registered
+    engine action; register under another name`), in every build:
+    `bake_probes`, `cover`, `debug`, `dump_ai`, `dump_desync`,
+    `dump_lanes`, `dump_nav`, `dump_platform`, `dump_pulse`,
+    `dump_render`, `dump_room`, `dump_stream`, `lanes`, `locale`,
+    `terrain_stream`, `timeline`, `turntable` and `view` (`help` marks
+    them `(registered)`). The engine's `pause`
+    freezes the tick from outside the game; the game's own pause (its menu
+    open, `Game.paused` set) is a game action under its own name,
+    `open_pause`.
 - **Facts** (`GameDesc.facts`) return a small JSON object for the probe's
   `state()`: score, phase, lives. Tests assert on facts and dumps.
 
@@ -255,7 +285,19 @@ registered schema and refuses a model path that does not exist.
   (ETC1S for colour, UASTC for normal and linear maps), WAV into QOA, fonts
   into MSDF atlases, scenes into component tables. Import settings live next
   to the source as `<file>.ogt` (`texture { kind normal }`,
-  `font { charset latin chars "开始游戏" }`).
+  `font { charset latin chars "开始游戏" }`). The prose here writes a
+  block on one line for short; in a file, as in every `.ogt`, a `{` ends
+  its key's line and a `}` stands alone on its own (the parser refuses
+  `'{' must end its line`):
+
+  ```text
+  type import
+  version 1
+  ---
+  texture {
+    kind normal
+  }
+  ```
 - At load a cooked texture reaches the GPU block-compressed in the device's
   format with its mips (BC7, and BC5 for normal maps, on desktop GPUs; ASTC
   on Apple and most Android; ETC2 and EAC elsewhere), a quarter of RGBA8's
@@ -411,6 +453,22 @@ else ignores it. The stamp is world state, so a replay reproduces it.
   ```ts
   world.insert(hero, og.Sprite, { texture: tex, width: 1, height: 1.5, anchor: { x: 0.5, y: 0 }, dropShadow: 0.5, shadow: 0.3 });
   ```
+- **Billboards** (three.js `Sprite`): `og.Sprite.facing` (or
+  `SpriteDesc.facing`) turns a world sprite to the camera that draws it.
+  `"cameraY"` stands it upright and turns it about y (trees, characters,
+  props a looking-down camera must not tip back); `"camera"` lays it in
+  the view plane (smoke, glints, signs); `"none"`, the default, keeps the
+  xy plane. Every camera turns it to itself (og.CameraView, og.Mirror, reflection
+  probes), the turn is render-only (never read by systems or snapshots),
+  faced sprites in one layer draw back to front from the camera and are
+  culled off screen, and a faced sprite's `dropShadow` is its whole shape
+  from any angle. It is still a sprite: flash, glow, blend, 2D lighting,
+  arrays, flipbooks and `toneMapped` all apply. A billboard behind a
+  transparent mesh still draws over it (sprites draw after the 3D scene).
+
+  ```ts
+  world.insert(tree, og.Sprite, { texture: treeTex, width: 2, height: 2.6, anchor: { x: 0.5, y: 0 }, facing: "cameraY", dropShadow: 0.6 });
+  ```
 - **World UI that must not change with the light** (speech bubbles, name
   tags, markers) takes `og.Sprite.toneMapped: false` (or
   `SpriteDesc.toneMapped`), three.js's `Material.toneMapped`: still placed
@@ -717,6 +775,65 @@ strike, a bite or a fall at weight 1, back to 0 when `finished`.
 Transform by the root joint's xz travel and yaw, `full` by all of it,
 `off` (the default) leaves the hips travelling inside the model; switch it
 to `planar` for a lunge's clip and back to `off` after.
+**Look-at and joint limits.** `og.LookAt { skeleton, joint, target }`
+on its own entity turns a joint (a head, an eye, a turret's barrel) so its
+`axis` (default +Z, as three.js `lookAt`) points at `target` after the
+clips and IK, its `upAxis` (+Y) rolling towards `up` (world +Y; zero
+keeps the animated roll). `maxYaw` and `maxPitch` (radians from the
+animated forward) hold a head from turning round, `clamped` reads back
+when they did; `bones: 3` spreads the turn over neck, chest and spine;
+`weight` fades it in and out. `og.JointLimit { skeleton, joint, axis,
+swing, twistMin, twistMax }` (radians from the rest pose) limits what
+`og.IkChain` and `og.LookAt` may turn a joint to: a knee is a hinge,
+`axis` +X, `swing: 0.15`, `twistMin: 0`, `twistMax: 2.6`, so a
+foot IK target never bends it backwards; a shoulder is a cone (`swing`).
+The defaults limit nothing, and the clip's own pose is never clamped.
+
+```ts
+const look = must(world.spawn({ name: "hero-look" }));
+must(world.insert(look, og.LookAt, { skeleton: body, joint: HEAD, bones: 2, maxYaw: 1.2, maxPitch: 0.5 }));
+const knee = must(world.spawn({ name: "hero-knee-l" }));
+must(world.insert(knee, og.JointLimit, { skeleton: body, joint: SHIN_L, axis: { x: 1, y: 0, z: 0 }, swing: 0.15, twistMin: 0, twistMax: 2.6 }));
+// each tick, from a system that writes og.LookAt: world.set(look, og.LookAt, { target: playerPosition })
+```
+
+**Foot locking.** `og.FootLock { skeleton, foot }` on its own entity, one
+per foot, keeps a foot the clips plant (within 5 mm of its lowest in the
+clip, the same test retargeting uses) where it touched the ground while
+root motion carries the body on and clips cross-fade, bending the leg
+(two-bone IK, `og.JointLimit`s respected); when the clips lift it the
+foot rejoins its animation over `release` (0.15 s). `planted` and
+`locked` read back each tick; `maxDistance` (0.5 m) lets go before a leg
+would stretch. It needs clips whose feet actually rest: a foot that only
+grazes its lowest for a frame is held for that frame only.
+
+**Spring bones.** `og.SpringBone { skeleton, joint, bones }` on its own
+entity, one per chain (a tail, ears, a ponytail, a single jiggling node),
+swings `joint` and its `bones` − 1 parents after their parents' motion:
+each joint's tail is a damped spring (`frequency` 3 Hz, `damping` 0.3;
+1 settles without overshoot) towards where the animation puts it, under
+`gravity` (`{ x: 0, y: -9.8, z: 0 }` droops it), held at the bone's
+length. `space` world (default) lags behind the entity's motion; model
+ignores it (a teleport does not whip the tail). Applied last, after IK
+and look-at; `lag` reads back how far the chain trails. Deterministic and
+saved with the world. `tipFrequency` and `tipDamping` (1) scale the last
+joint's frequency and damping, the joints between in proportion: 0.25 is
+a strand soft at its tip on a stiff root.
+
+Keep hair out of the head with `og.SpringCollider { skeleton, joint,
+shape, offset, tail, radius }` on its own entity, a sphere about `offset`
+or a capsule from `offset` to `tail` in the joint's frame: every tail of
+that skeleton's springs is pushed out of it to its `radius` plus the
+spring's `radius`, keeping its bone's length. A collider's `layers` (1)
+must meet the spring's `colliders` (all) to count.
+
+```ts
+const tail = must(world.spawn({ name: "hero-tail" }));
+must(world.insert(tail, og.SpringBone, { skeleton: body, joint: TAIL_TIP, bones: 3, gravity: { x: 0, y: -4, z: 0 }, tipFrequency: 0.5, radius: 0.02 }));
+const hips = must(world.spawn({ name: "hero-hips-collider" }));
+must(world.insert(hips, og.SpringCollider, { skeleton: body, joint: HIPS, shape: "capsule", offset: { x: -0.15, y: 0, z: 0 }, tail: { x: 0.15, y: 0, z: 0 }, radius: 0.12 }));
+```
+
 `templates/archetypes/third-person` (`src/anim.ts`: a 1D blend by speed,
 a hero retargeted at cook time and sentinels at run time) is the pattern,
 and for a 3D action game as a whole: a CharacterController over a level,
@@ -770,6 +887,7 @@ animation {
   library "anims/humanoid-clips.glb"   # its clips land in this model's #anim, retargeted (repeatable)
   rig "rigs/hero.ogt"                  # how this model's bones are named (`type rig`); default: detected from the node names
   footIk true                          # retargeting solves the legs so planted feet stay planted (default true)
+  mirror "turnLeft" "turnRight"        # also write a clip mirrored to the other side, under that name (default "<clip>.mirrored"; repeatable)
   compress false                       # quantised samples and keyframe reduction (default false: f32)
   tolerance 0.0001                     # the most compression may move a sampled value (default 0.0001, at most 0.1)
 }
@@ -789,6 +907,34 @@ stride), and its legs are solved so planted feet stay on the ground
 (`footIk`, on by default). The fx-showcase `retarget` station is the
 pattern.
 
+Hands retarget too: the fingers are humanoid bones (VRM 1.0's
+`leftThumbMetacarpal` … `leftLittleDistal`, read from Mixamo's
+`LeftHandIndex1`, VRoid's `J_Bip_L_Index1`, Rigify's `DEF-f_index.01.L`,
+Unreal's `index_01_l`, plain `index.01.L`; Unity's legacy `Left Thumb
+Proximal` is the metacarpal), each turning from its hand as
+the source's does, so a fist or a grip holds on an A-posed arm whatever
+the arm does. The target's twist bones (unmapped nodes named `twist`, such
+as Unreal's `lowerarm_twist_01_l`, or Rigify's `DEF-forearm.L.001`) take a
+share of their segment's roll by where they sit along it: none at the
+segment's head, the next bone's at its end, so a forearm does not
+candy-wrap. A clip made for the rig itself that leaves its twist bones
+still gets the same shares each tick (after IK); a clip that keys them
+is played as keyed. A character whose rest pose does not stand on the ground (an
+armature lifted off it, a crouched rest) says how high its ankles stand
+in its `type rig` file, `footHeight 0.08` (or `footHeight <left>
+<right>`); planted feet then land on that ground, not at the rest pose's
+foot height.
+
+**Mirroring.** `og.anim.mirror(world, { clip, skeleton })` answers a new
+clip that plays `clip` on the other side (a left-handed swing, a limp on
+the other leg, a turn the other way): left and right nodes are paired by
+the side tokens every naming scheme writes (`LeftArm`/`RightArm`,
+`thigh.L`/`thigh.R`, `J_Bip_L_`/`J_Bip_R_`, `calf_l`/`calf_r`), each
+node takes its counterpart's motion reflected across the skeleton's
+x = 0 plane, root motion's sideways travel and turns flip. It assumes a
+symmetric rest pose; mirror a retargeted clip on the skeleton it was
+retargeted for.
+
 **Compression** shrinks a model's clips in the bundle (not in memory: they
 are rebuilt at load). In the same `animation` block, `compress true`
 quantises rotations to 48 bits and the rest to 16 and drops the keyframes
@@ -818,6 +964,9 @@ clip walk "walk" {
   speed 1                   # duration multiplier, above 0 (default 1)
   loop true                 # false: holds its last frame (default true)
 }
+clip walkOther "walk" {
+  mirror true               # plays the clip on the other side of the skeleton (default false): no og.anim.mirror needed
+}
 clip run "run"
 clip waving "wave"
 blend1d move speed {        # blend1d <motion> <param>: the two children around the value blend linearly, clamped at the ends
@@ -833,12 +982,14 @@ layer base {                # the first layer is the base: root motion and og.An
   state still idle          # state <name> <motion>
   state move move {
     speed 1                 # playback rate, 0 or more (default 1)
+    sync gait               # a sync group: states of one group play in step across layers (default none)
   }
   entry still               # the state it starts in (default: the first)
   transition still move {   # transition <from | any> <to>; in file order, the first that holds fires
     when speed gt 0.2       # when <param> gt | ge | lt | le | eq | ne <number>; every `when` must hold
     exit 0.9                # and the source has played this many cycles (a `when` or an `exit` is required)
     fade 0.25               # cross-fade seconds (default 0.2)
+    interrupt any           # what may cut this fade: any (default) | none (it completes first) | source (only the state being left) | next (only the new state's own)
   }
   transition any still {    # any: from every state but the target
     when speed le 0.2
@@ -847,7 +998,11 @@ layer base {                # the first layer is the base: root motion and og.An
 layer upper {
   mode additive             # override (default): replaces the pose below | additive: adds each clip's difference from its first frame
   weight wave               # a number 0 to 1, or a parameter clamped to it (default 1)
-  state wave waving
+  mask "spine" 0.5          # mask "<node>" [weight 0 to 1, default 1]: that node and every node under it (default: no mask, all 1)
+  mask "arm.L"              # a deeper line wins for its branch; nodes under no line take 0
+  state wave waving {
+    sync gait
+  }
 }
 ```
 
@@ -855,7 +1010,16 @@ Each state advances one phase by `dt × AnimationGraph.speed × state speed
 / duration`, the duration weighted across a blend's clips, so blended
 clips stay in step. Per tick and layer the transitions are checked first,
 then the phases advance, then the poses blend; a transition during a fade
-replaces it. `og.anim.graph` refuses a parse error naming the line, a
+replaces it unless its `interrupt` says otherwise (`none` for a
+committed attack or landing, `source` to let an idle re-target a start
+that has just begun). A layer's `mask` lines confine it to branches of the
+skeleton (by node name, the nearest named ancestor's weight; an upper-body
+layer is `mask "spine"`), so a wave or an aim plays over a walk without
+freezing the legs. In a sync group the first layer (file order) whose
+current state is in it leads: every later layer's state of that group
+plays at the leader's phase, whatever its clip's length, and a transition
+between two states of one group keeps the phase (a walk-to-run blend
+keeps the feet in step). `og.anim.graph` refuses a parse error naming the line, a
 clip name `clips` lacks, a parameter not declared and a motion that
 contains itself. Write the parameters from a system every tick
 (`world.set(body, og.AnimationGraph, { p0: speed })`); `state` and
@@ -1671,16 +1835,24 @@ there. `world.set(e, og.Velocity, ...)` refuses on
 an entity without one (a body in `start`, before its first step):
 `world.insert` it there, which adds and sets it.
 
-`og.CollisionStarted` is read on the tick after the physics step. Its
-`normal` points from `a` to `b`; the bodies' `og.Velocity` already contains
-the solver's outgoing velocity, not their incoming impact velocity. Do
-not derive impact weight from those velocities: bodies may already be
-separating. There is no contact-time velocity or impulse on this event.
-For driven bodies, retain the velocity handed to physics in a component
-and read that cache before the next drive system overwrites it (as in
-`examples/rumpus-isle/src/critters.ts`). Project `velocityA - velocityB`
-onto the event normal for closing speed. This estimates linear approach
-speed, not contact-point speed from rotation or forces during the step.
+`og.CollisionStarted` is read on the tick after the physics step, when
+the bodies' `og.Velocity` already holds the solver's answer (they may
+already be parting), so never weigh a hit from og.Velocity. The event
+carries the hit itself, taken in the step that made the contact. `a` is
+the lower id, and `normal` points from `a` to `b`. `point` is the deepest
+contact point.
+`relativeVelocity` (m/s) is `a`'s velocity relative to `b` at `point` as
+that step began: each body's linear velocity plus its spin crossed with
+the point's offset from its centre of mass. A static collider counts as
+still, and a kinematic body moves at its velocity. Its part along
+`normal` is the closing speed:
+`Math.max(0, rv.x * n.x + rv.y * n.y + rv.z * n.z)`, which is positive
+while they approach. `impulse` (N·s, at least 0) is the normal impulse the
+solver gave the pair in that step, summed over substeps and contact points:
+`b` took `impulse` along `normal` and `a` the same against it, so heavier
+bodies hitting give more. Scale feedback on the closing speed (how fast)
+or the impulse (how hard, mass included), as
+`examples/rumpus-isle/src/critters.ts` does for its bumps.
 
 ```ts
 const hit = og.physics.raycast(world, { origin: eye, direction: { x: 0, y: 0, z: -1 }, maxDistance: 30, filter: { mask: 0b10, exclude: player } });
@@ -2821,11 +2993,22 @@ door. Mark the scene's unmoving models `static true` and put an
 entity "hall" {
   model "models/hall.glb"
   static true
-  Transform { position 0 0 0 quaternion 0 0 0 1 scale 1 1 1 }
+  Transform {
+    position 0 0 0
+    quaternion 0 0 0 1
+    scale 1 1 1
+  }
 }
 entity "hall-probes" {
-  Transform { position 0 2 0 quaternion 0 0 0 1 scale 1 1 1 }
-  LightVolume { size 12 4 12 spacing 1 }
+  Transform {
+    position 0 2 0
+    quaternion 0 0 0 1
+    scale 1 1 1
+  }
+  LightVolume {
+    size 12 4 12
+    spacing 1
+  }
 }
 ```
 

package/knowledge/skills/og-platform-sdk/SKILL.md

@@ -88,6 +88,12 @@ if (answer.ok && typeof answer.data.value === "number") run.best[i] = Math.max(r
 | AI-generated content shown | `aiMark(world, { kind, label })` | disclosure, not permission |
 | Play with others in one room | `roomCreate(world, { name })`, `roomJoin(world, room)`, `roomLeave`, `roomSend(world, data, to?)`, `roomPeers`, `roomInfo`; the answers as `og.RoomJoined`, `og.RoomPeerJoined`, `og.RoomPeerLeft`, `og.RoomMessage` (read one with `roomMessage`) | natively `og relay` with `og run --room ws://127.0.0.1:P/<room>`; on the web the Player's rooms, when its hello lists `room.join` (`roomInfo(world).host` is `none` otherwise and joins are refused). A message is this peer's host input only: for a game both peers simulate, use og.net's lockstep (`og.Lockstep`, `og.PlayerInput`, og-game §20) and send nothing yourself |
 
+A payload keeps the number it was given: an `f32` field's value is single
+precision promoted to a JSON number (`f32(2.7)` sends `2.700000047683716`),
+and the store neither rounds nor widens it. Compare with a tolerance in
+a playtest, round only for display, or keep a value that must compare
+exactly in an `f64` (og-build §1, Values in the JSON).
+
 `og.platform.info(world)` says what answers here (`player`, `local` or
 `none`) and the methods it answers (`capabilities`): check it rather than
 trying.

package/knowledge/skills/og-taste/SKILL.md

@@ -342,6 +342,13 @@ the look lives in authored art (painted backdrops, frame-by-frame
 animation, hand-placed pixels); the engine frames it with the look, but
 the assets carry it, so budget for them.
 
+**Read `look.profiles` before matching.** It names the project profiles a
+style draws for: `["2d"]` for flipbooks, hand-placed pixels and paper
+cut-outs, `["3d"]` for lit meshes, toon materials and voxels, both for a
+post treatment that frames either. `create --premise` matches only among the
+styles of the game's profile (`--profile`, else the premise's, else 3D);
+`--look` names any style and wins.
+
 **Write the look.** Start from the style's preset and change only what the
 game needs; your file wins field by field. A style whose `look.presetReady`
 is false has no preset in this engine yet: leave out `extends` and set the

package/knowledge/skills/og-ui/SKILL.md

@@ -105,6 +105,30 @@ layers (`anchor` for HUD corners, `modal` for dialogs,
 playtest can `touch_move_to` it (`Shop/Panel/Detail/Buy` resolves as
 `Detail/Buy`).
 
+**Text over a world point** (a name tag over a critter, a marker over a
+door): project the point each tick with the og.Camera resource's
+`worldToScreen` (null behind the camera: draw nothing) and draw screen
+text there, not world text. World text (`og.render.text` without `screen`) faces +z, rides
+the tone curve and is blurred by depth of field at the frame's edge;
+screen text is never tone mapped, blurred or depth tested, so the tag
+stays crisp and in its colour, and at a `layer` up to `UI_LAYER` (1000) it
+draws under every UI element (the HUD and the dialogs cover it):
+
+```ts
+const Tags = defineSystem("Tags", { reads: [Game, og.Camera] }, (_q, _t, world) => {
+  const cam = must(world.resource(og.Camera));
+  for (const c of critters(world)) {
+    const at = cam.worldToScreen({ x: c.x, y: c.y + 1.25, z: c.z }); // CSS pixels, y down
+    if (at === null) continue;
+    og.render.text(world, { font, text: c.name, position: { x: at.x, y: at.y, z: 0 }, size: 18, align: "center", outline: 0.7, screen: true, layer: 10 });
+  }
+});
+```
+
+Keep the font in a `Font()` field. Two tags within a tag's width of each
+other overlap into one label: lift the later one by its height, or hide
+the farther one's.
+
 Mixed styles in one paragraph are `richText(id, markup)`: `[b]`,
 `[color=danger]` (a token, or `#rrggbb`), `[size=lg]`, `[font=mono]`,
 `[icon=coin]`, `[link=shop]…[/link]` and the per-glyph `[wave]`, `[shake]`,

package/knowledge/wiki/ai.md

@@ -18,7 +18,7 @@ module ai {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 9496</sub>
+<sub>`api.ogt` line 9869</sub>
 
 ## Contents
 
@@ -74,7 +74,7 @@ fn load {
 }
 ```
 
-<sub>`api.ogt` line 9668</sub>
+<sub>`api.ogt` line 10041</sub>
 
 <a id="fn-parse"></a>
 
@@ -104,7 +104,7 @@ fn parse {
 }
 ```
 
-<sub>`api.ogt` line 9675</sub>
+<sub>`api.ogt` line 10048</sub>
 
 <a id="fn-get"></a>
 
@@ -136,7 +136,7 @@ fn get {
 }
 ```
 
-<sub>`api.ogt` line 9682</sub>
+<sub>`api.ogt` line 10055</sub>
 
 <a id="fn-set"></a>
 
@@ -170,7 +170,7 @@ fn set {
 }
 ```
 
-<sub>`api.ogt` line 9690</sub>
+<sub>`api.ogt` line 10063</sub>
 
 <a id="fn-restart"></a>
 
@@ -200,7 +200,7 @@ fn restart {
 }
 ```
 
-<sub>`api.ogt` line 9699</sub>
+<sub>`api.ogt` line 10072</sub>
 
 <a id="fn-noise"></a>
 
@@ -230,7 +230,7 @@ fn noise {
 }
 ```
 
-<sub>`api.ogt` line 9706</sub>
+<sub>`api.ogt` line 10079</sub>
 
 <a id="fn-describe"></a>
 
@@ -260,7 +260,7 @@ fn describe {
 }
 ```
 
-<sub>`api.ogt` line 9713</sub>
+<sub>`api.ogt` line 10086</sub>
 
 ## Components, resources and events
 
@@ -310,7 +310,7 @@ component AiAgent {
 }
 ```
 
-<sub>`api.ogt` line 9515</sub>
+<sub>`api.ogt` line 9888</sub>
 
 <a id="record-Perception"></a>
 
@@ -411,7 +411,7 @@ component Perception {
 }
 ```
 
-<sub>`api.ogt` line 9541</sub>
+<sub>`api.ogt` line 9914</sub>
 
 <a id="record-Perceivable"></a>
 
@@ -440,7 +440,7 @@ component Perceivable {
 }
 ```
 
-<sub>`api.ogt` line 9611</sub>
+<sub>`api.ogt` line 9984</sub>
 
 <a id="record-AiChanged"></a>
 
@@ -467,7 +467,7 @@ event AiChanged {
 }
 ```
 
-<sub>`api.ogt` line 9623</sub>
+<sub>`api.ogt` line 9996</sub>
 
 ## Types
 
@@ -483,7 +483,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Behaviour "A loaded behaviour tree or state machine."
 ```
 
-<sub>`api.ogt` line 9502</sub>
+<sub>`api.ogt` line 9875</sub>
 
 <a id="type-BehaviourInfo"></a>
 
@@ -512,7 +512,7 @@ struct BehaviourInfo {
 }
 ```
 
-<sub>`api.ogt` line 9631</sub>
+<sub>`api.ogt` line 10004</sub>
 
 <a id="type-NoiseDesc"></a>
 
@@ -544,7 +544,7 @@ struct NoiseDesc {
 }
 ```
 
-<sub>`api.ogt` line 9641</sub>
+<sub>`api.ogt` line 10014</sub>
 
 <a id="type-AiDescription"></a>
 
@@ -579,7 +579,7 @@ struct AiDescription {
 }
 ```
 
-<sub>`api.ogt` line 9655</sub>
+<sub>`api.ogt` line 10028</sub>
 
 ## Column kinds
 
@@ -598,7 +598,7 @@ column Behaviour {
 }
 ```
 
-<sub>`api.ogt` line 9504</sub>
+<sub>`api.ogt` line 9877</sub>
 
 ## Constants
 
@@ -612,16 +612,16 @@ column Behaviour {
 const AI_RUNNING u32 1 "AiAgent.status: the tree or state is still running."
 ```
 
-<sub>`api.ogt` line 9511</sub>
+<sub>`api.ogt` line 9884</sub>
 
 ```ogt
 const AI_SUCCESS u32 2 "AiAgent.status: the tree succeeded on the last think."
 ```
 
-<sub>`api.ogt` line 9512</sub>
+<sub>`api.ogt` line 9885</sub>
 
 ```ogt
 const AI_FAILURE u32 3 "AiAgent.status: the tree failed on the last think."
 ```
 
-<sub>`api.ogt` line 9513</sub>
+<sub>`api.ogt` line 9886</sub>