@origingame/engine 0.2.0 → 0.4.0

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

@@ -14,8 +14,8 @@ needs a browser or a Rust toolchain. The command channel is
 The loop held for two whole games written from this package alone
 (`examples/lantern-vale`, `examples/hollowbell`): `og cook` took 47 and 69
 assets cold in 8.2 s and 3.6 s and under 100 ms after a change, without a
-warning, and every refusal named the line and the fix (a copied skin
-without its CJK `fallback` named the line and og-taste §1;
+warning, and every refusal named the line and the fix (a copied UI style, as
+styles were then called, without its CJK `fallback` named the line and og-taste §1;
 `PostEffects.vignette is true or false` named the line). Scripted runs gave
 the same frames every time, `store: "keep"` relaunches and two-process
 replays worked the first time they were asked for, and `og polish` scored
@@ -169,6 +169,15 @@ same store, for a relaunch (og-platform-sdk §4).
 - Determinism is checkable: two runs with the same seed and script give the
   same world hash in `dump_world`. When they do not, find the wall-clock
   read or the unseeded randomness before anything else.
+- A model built as code (og-model) is judged on numbers and one sheet,
+  not on a frame read by eye: `view:<entity>:front|back|side|top`,
+  `view:<entity>:orbit:<degrees>` and `turntable:<entity>:<n>` frame it
+  from fixed cameras, and `og compare <reference.png> <render.png>`
+  prints the silhouette IoU and the ΔE00 per mask region and writes the
+  reference beside the render as one sheet PNG (`--mask`, `--align`,
+  `--json`). Two runs give the same numbers and the same sheet bytes, so
+  quote them with the command. og-model §3 has the commands and how to
+  read them, og-model §4 the gate each pass must meet.
 - Report what ran and what did not. A build that compiled is not a game
   that plays.
 
@@ -201,7 +210,10 @@ every screen that matters.
 | 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 |
 
-The report also lists clipped samples in the mix (og-audio §4). Contrast and
+The report also lists clipped samples in the mix (og-audio §4), and a UI
+style finding (no score) when a shot's `dump_ui` reports `style` empty: the
+UI draws in prototype, the engine's placeholder, not a style of the game's
+own (og-taste §1). Contrast and
 text size read text only: icons and images (their "text" is a picture's
 name), disabled controls and what they hold (WCAG exempts them), the
 slivers a scroll container cuts, what a dialog's or a tutorial's scrim
@@ -218,7 +230,7 @@ so it depends on the glyphs' coverage: thin strokes cover few pixels
 whole, and a regular-weight CJK face at body sizes measures lower than
 Latin in the same colours (a 15 px "设置" 3.1:1 where "Settings" reads
 4.6:1 on one button), as it reads lower to the eye. Darken the ink in the
-skin's palette, give the CJK face a heavier weight or the label a larger
+style's palette, give the CJK face a heavier weight or the label a larger
 step; the measure is not wrong there. Facts are the game's `facts`
 (og-game §3): expose `hp`, `hits` or `kills` there or the hit measures stay
 n/a. A baseline line says how often things change with no input at all;
@@ -226,7 +238,7 @@ when it is high (a runner that always moves), read latency together with
 the frames.
 
 The numbers cannot judge a style. Read the frames before changing anything,
-fix the cause in the skin, the template or the system, never per call, and
+fix the cause in the style, the template or the system, never per call, and
 run it again after the fix: the report is the evidence.
 
 ## 6. Shipping
@@ -234,14 +246,24 @@ run it again after the fix: the report is the evidence.
 `og build .` bundles `src/` to `dist/game.js`, cooks, and copies the engine
 runtime and wasm next to it. `og build . --publish` produces the published
 form: the probe keeps only its player-facing members (hello, tick, state,
-pick, entity, input, capture) and the command channel is gone.
+pick, entity, input, capture) and the command channel is gone. A `2d`
+project publishes the 2D module, which has no 3D world
+(`RenderCapabilities.world3d` false): the build refuses scenes holding
+`Terrain`, `TerrainScatter`, `Water`, `WaterSurface` or `Fluid3D`, naming
+each by scene file and line (og-game §2).
 What ships is still checked by script, through what it keeps: real input
 on the published page and the probe's `tick`, `state` and `capture`. A
 playtest written in input steps (`key_down`, `type`, `touch_move_to` an
 id, `move_to_text`, `touch_start`) and `screenshot` steps runs there as it
 runs under `og test`, each frame compared with the same references; a
 game command (warp, give) has no channel there and is refused, so keep
-the steps a published check needs free of them. The engine runs this on
+the steps a published check needs free of them. The page shows the
+Player's Back over the canvas's top-left corner (12, 12, 40 by 40 CSS px
+on a desktop page; og-ui §5), which anchored HUD groups keep out of, so
+a playtest the page is held to gives its native run the same cover with
+`setup: "cover:12,12,40,40"` (`PlaytestDesc.setup`: command steps run
+once after `start`, before the first tick, never part of the page's
+script) and its frames lay out as the page's. The engine runs this on
 the published build of its own games (its `tests/web/published.ts`: the
 boot, the title, a press, a typed name and a frame against the metal
 reference, with a clean console).

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

@@ -218,11 +218,26 @@ export const Move = defineSystem("Move", { reads: [Velocity], writes: [og.Transf
   module variable or as numbers of code points.
   A `str` holds 1 to 4,096 bytes: a larger capacity typechecks and is
   refused when the game starts (`a string field holds 1 to 4096 bytes`).
-- A field holds one value: a component has no array or list field. A few
-  values are numbered fields (`p0`..`p7`, as og.CameraRail's rail points);
-  a list is an entity per element with its own component, looped over by
-  a query (a ring of skid marks, the laps of a race); a long record (a
-  lap's taped inputs) is text in `str(4096)` chunks, an entity each.
+- A field holds one value, or a fixed-capacity list of one number or
+  handle kind: `list(u32(), 8)`, `list(Asset(), 4)` (1 to 1,024 elements,
+  starting empty, never tunable). Reading it answers a frozen array, a
+  copy: `push`, `splice` and index writes throw, so write it whole
+  (`v.passes = [...v.passes, h]`, `v.passes = []`, `world.set(e, Chain,
+  { passes: [3, 5] })`). One over the capacity is refused with the fix
+  named (`declare the field list(u32(), 9) or larger`), never truncated.
+  Its column is the element's typed array with (capacity + 1) lanes per
+  entity, the count first, zeros past it, so `[]` and `[0]` are different
+  worlds. The probe reads it as a JSON array (`get:`, `dump_entity`),
+  `set:Chain.passes=[3,5]` (or `3,5`, nothing for `[]`) writes it whole, a
+  scene or a look gives it on one line (`passes 3 5`, the key alone for
+  `[]`), and snapshots and the hash carry it; a migrating restore keeps a
+  list that fits a new capacity and empties one that does not.
+  A list holds numbers only: a few vectors are numbered fields
+  (`p0`..`p7`, as og.CameraRail's rail points); a list of things with
+  fields of their own is an entity per element with its own component,
+  looped over by a query (a ring of skid marks, the laps of a race); a
+  long record (a lap's taped inputs) is text in `str(4096)` chunks, an
+  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
@@ -270,6 +285,17 @@ it is declared.
   probe and the command channel address entities by them.
 - Vector, quaternion, matrix, colour, transform and material vocabulary is
   three.js's (`position`, `quaternion`, `scale`, `metalness`, `roughness`).
+- Math on those values is three.js's methods as pure functions, imported
+  from `@origingame/engine`: `vec3`, `vec2`, `quat`, `mat4`, `box3`,
+  `sphere`, `plane`, `frustum`, `ray`, `color` (`vec3.add(a, b)`,
+  `quat.slerp(a, b, t)`, `mat4.transformPoint(m, p)`,
+  `frustum.fromCamera(...)` then `frustum.intersectsBox(f, box)`,
+  `ray.intersectTriangle(r, a, b, c)` answering a point or null,
+  `color.fromHex(0x14161b)` answering linear RGB). They never change their
+  arguments and answer new plain objects, so there are no classes to
+  construct and a result is written into a column as any other value;
+  they use only arithmetic and `sqrt`, so a system using them stays
+  deterministic. Signatures: `reference/math.md`.
 
 ## 7. Where the API is described
 

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

@@ -135,7 +135,7 @@ is what a sprite wants.
 | Take-off | (0.85, 1.15) | 0.1 s |
 | Hit taken | (1.2, 0.8) | 0.15 s, with a flash |
 | Pickup collected (on the pickup) | (1.4, 1.4) then shrink to 0 | 0.15 s |
-| UI button press (the skin's `press` does it for og.ui) | (0.92, 0.92) | 0.08 s, unscaled |
+| UI button press (the style's `press` does it for og.ui) | (0.92, 0.92) | 0.08 s, unscaled |
 
 Do not squash rigid things (crates, walls, the camera's target in a
 cutscene) or anything more than once per 6 ticks.
@@ -161,7 +161,7 @@ motion and hit stop (UI motion). `og.tween.squash` (§5) and
 | Constant motion, timers, scrolling, colour cycles | `linear` |
 | Most small motion when unsure | `quadOut` (the default) |
 
-Durations: 0.1–0.2 s for feedback, 0.12–0.3 s for UI (the skin's
+Durations: 0.1–0.2 s for feedback, 0.12–0.3 s for UI (the style's
 durations, og-taste §5), 0.2–0.35 s for swaps, 0.4–0.8 s for camera moves,
 reveals and screen transitions (up to 0.7 s). Longer feels sluggish unless
 it is a cutscene or a reward.