@origingame/engine 0.3.0 → 0.5.0

package/knowledge/wiki/reflect.md

@@ -6,9 +6,9 @@ Reflection: components and resources are declared once with their field layout a
 
 The inspector, Tune, the probe, scene text and the wiki read this one schema. Each column factory below makes one field.
 
-A field holds one value: there is no array or list column. A few values are numbered fields (`p0` to `p7`, as og.CameraRail does); a list of things is an entity each, 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` fields of at most 4,096 bytes each, chunked over entities. Keep none of it in module variables: they are not world state, so a snapshot, a replay and a hot reload lose them.
+A field holds one value, or a list of at most a fixed number of one number type or handle: `list(u32(), 8)`, `list(Asset(), 4)` (the list factory below). A list is read as a frozen copy (`push` throws) and written whole (`chain.passes = [...chain.passes, h]`); one over its capacity is refused, never truncated. A few vectors are numbered fields (`p0` to `p7`, as og.CameraRail does); a list of things with fields of their own is an entity each, 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` fields of at most 4,096 bytes each, chunked over entities. Keep none of it in module variables: they are not world state, so a snapshot, a replay and a hot reload lose them.
 
-A handle (an og.load answer, a texture, a sound, a geometry, a material, an entity) is a 64-bit number: keep it in a field of its own kind (`Asset()`, `Texture()`, `Sound()`, `Geometry()`, `Material()`, `Entity()`, the factories of the API's handle types), in a component or a resource. A `u32` field refuses one (handles pass 2^32: `4294967298 is not a u32`); an `f64` holds the number but loses its type.
+A handle (an og.load answer, a texture, a sound, a geometry, a material, an entity) is a 64-bit number: keep it in a field of its own kind (`Asset()`, `Texture()`, `Sound()`, `Font()`, `Style()`, `Geometry()`, `Material()`, `Entity()`: every handle type of the API has its factory, named as the type), never cast to another kind, in a component or a resource. A `u32` field refuses one (handles pass 2^32: `4294967298 is not a u32`); an `f64` holds the number but loses its type.
 
 - **TypeScript**: functions are named exports of the package: `import { … } from "@origingame/engine"`; components, resources and events are tokens on `og`.
 - **Publish builds**: kept (members may override).
@@ -20,7 +20,7 @@ module reflect {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 660</sub>
+<sub>`api.ogt` line 661</sub>
 
 ## Contents
 
@@ -38,6 +38,7 @@ module reflect {
 | [`Matrix4()`](#column-Matrix4) | column kind | A Matrix4 field: sixteen column-major elements per entity. |
 | [`Color()`](#column-Color) | column kind | A Color field: r, g, b interleaved. |
 | [`str()`](#column-str) | column kind | Text of at most `capacity` bytes of UTF-8, stored inline and zero-padded, so it is world state like a number: a player's name, a label. `str(48)` holds any 12 characters (four bytes covers every script). The capacity is 1 to 4,096 bytes: a larger one is refused when the game starts (`a string field holds 1 to 4096 bytes`), so longer text goes in chunks, an entity each. |
+| [`list()`](#column-list) | column kind | A list of at most `capacity` values of one number column (`f32`, `f64`, `u32`, `i32`) or handle column (`Asset`, `Entity`, `Post`, ...), stored inline: a count, then the elements, zeros past the count, so `[]` and `[0]` differ and the list is world state like a number. The capacity is 1 to 1,024 elements; it starts empty and is never tunable. |
 | [`defineComponent`](#fn-defineComponent) | function | Declare a component: plain data stored per entity in engine memory, one column per field. |
 | [`defineResource`](#fn-defineResource) | function | Declare a resource: a reflected singleton, such as a tuning table. Its fields start at their defaults. |
 
@@ -75,7 +76,7 @@ fn defineComponent {
 }
 ```
 
-<sub>`api.ogt` line 758</sub>
+<sub>`api.ogt` line 765</sub>
 
 <a id="fn-defineResource"></a>
 
@@ -106,7 +107,7 @@ fn defineResource {
 }
 ```
 
-<sub>`api.ogt` line 767</sub>
+<sub>`api.ogt` line 774</sub>
 
 ## Types
 
@@ -142,11 +143,11 @@ struct FieldOptions {
 }
 ```
 
-<sub>`api.ogt` line 668</sub>
+<sub>`api.ogt` line 669</sub>
 
 ## Column kinds
 
-Each is a factory, `f32(value?, options?)`, that makes one field of a component or resource layout; `str(capacity, value?, options?)` takes its capacity in bytes first.
+Each is a factory, `f32(value?, options?)`, that makes one field of a component or resource layout; `str(capacity, value?, options?)` takes its capacity in bytes first; `list(of, capacity, options?)` takes another factory's field (`u32()`, `Asset()`) and a capacity in elements.
 
 | Column | Value | Typed array | Stride | Doc |
 |---|---|---|---|---|
@@ -161,6 +162,7 @@ Each is a factory, `f32(value?, options?)`, that makes one field of a component
 | <a id="column-Matrix4"></a>`Matrix4` | `Matrix4` | `Float32Array` | 16 | A Matrix4 field: sixteen column-major elements per entity. |
 | <a id="column-Color"></a>`Color` | `Color` | `Float32Array` | 3 | A Color field: r, g, b interleaved. |
 | <a id="column-str"></a>`str` | `string` | `Uint8Array` | the capacity | Text of at most `capacity` bytes of UTF-8, stored inline and zero-padded, so it is world state like a number: a player's name, a label. `str(48)` holds any 12 characters (four bytes covers every script). The capacity is 1 to 4,096 bytes: a larger one is refused when the game starts (`a string field holds 1 to 4096 bytes`), so longer text goes in chunks, an entity each. Get and set it as a JavaScript string; text over the capacity is refused with the fix named (an error value from world.insert/world.set, a throw from a resource's setter), never truncated. Its view is the raw bytes. |
+| <a id="column-list"></a>`list` | an array of the element's | the element's | the element's × (capacity + 1) | A list of at most `capacity` values of one number column (`f32`, `f64`, `u32`, `i32`) or handle column (`Asset`, `Entity`, `Post`, ...), stored inline: a count, then the elements, zeros past the count, so `[]` and `[0]` differ and the list is world state like a number. The capacity is 1 to 1,024 elements; it starts empty and is never tunable. Reading it answers a frozen array, a copy: `push`, `splice` and index writes throw, so change it by writing a whole array (`v.passes = [...v.passes, h]`, `v.passes = []`). A list over the capacity is refused with the fix named (an error value from world.insert/world.set, a throw from a resource's setter), never truncated. Scene text and looks give it on one line, its elements in order (`passes 3 5`), the key alone for the empty list. Its view is the element's typed array with a stride of (capacity + 1) elements, the count first. |
 
 ```ogt
 column f32 {
@@ -171,7 +173,7 @@ column f32 {
 }
 ```
 
-<sub>`api.ogt` line 680</sub>
+<sub>`api.ogt` line 681</sub>
 
 ```ogt
 column f64 {
@@ -182,7 +184,7 @@ column f64 {
 }
 ```
 
-<sub>`api.ogt` line 687</sub>
+<sub>`api.ogt` line 688</sub>
 
 ```ogt
 column u32 {
@@ -193,7 +195,7 @@ column u32 {
 }
 ```
 
-<sub>`api.ogt` line 694</sub>
+<sub>`api.ogt` line 695</sub>
 
 ```ogt
 column i32 {
@@ -204,7 +206,7 @@ column i32 {
 }
 ```
 
-<sub>`api.ogt` line 701</sub>
+<sub>`api.ogt` line 702</sub>
 
 ```ogt
 column bool {
@@ -215,7 +217,7 @@ column bool {
 }
 ```
 
-<sub>`api.ogt` line 708</sub>
+<sub>`api.ogt` line 709</sub>
 
 ```ogt
 column Vector2 {
@@ -226,7 +228,7 @@ column Vector2 {
 }
 ```
 
-<sub>`api.ogt` line 715</sub>
+<sub>`api.ogt` line 716</sub>
 
 ```ogt
 column Vector3 {
@@ -237,7 +239,7 @@ column Vector3 {
 }
 ```
 
-<sub>`api.ogt` line 722</sub>
+<sub>`api.ogt` line 723</sub>
 
 ```ogt
 column Quaternion {
@@ -248,7 +250,7 @@ column Quaternion {
 }
 ```
 
-<sub>`api.ogt` line 729</sub>
+<sub>`api.ogt` line 730</sub>
 
 ```ogt
 column Matrix4 {
@@ -259,7 +261,7 @@ column Matrix4 {
 }
 ```
 
-<sub>`api.ogt` line 736</sub>
+<sub>`api.ogt` line 737</sub>
 
 ```ogt
 column Color {
@@ -270,7 +272,7 @@ column Color {
 }
 ```
 
-<sub>`api.ogt` line 743</sub>
+<sub>`api.ogt` line 744</sub>
 
 ```ogt
 column str {
@@ -282,4 +284,14 @@ column str {
 }
 ```
 
-<sub>`api.ogt` line 750</sub>
+<sub>`api.ogt` line 751</sub>
+
+```ogt
+column list {
+  doc "A list of at most `capacity` values of one number column (`f32`, `f64`, `u32`, `i32`) or handle column (`Asset`, `Entity`, `Post`, ...), stored inline: a count, then the elements, zeros past the count, so `[]` and `[0]` differ and the list is world state like a number. The capacity is 1 to 1,024 elements; it starts empty and is never tunable."
+  doc "Reading it answers a frozen array, a copy: `push`, `splice` and index writes throw, so change it by writing a whole array (`v.passes = [...v.passes, h]`, `v.passes = []`). A list over the capacity is refused with the fix named (an error value from world.insert/world.set, a throw from a resource's setter), never truncated. Scene text and looks give it on one line, its elements in order (`passes 3 5`), the key alone for the empty list. Its view is the element's typed array with a stride of (capacity + 1) elements, the count first."
+  list true
+}
+```
+
+<sub>`api.ogt` line 759</sub>