@origingame/engine 0.2.0 → 0.3.0

package/knowledge/wiki/video.md

@@ -0,0 +1,157 @@
+<!-- Generated from crates/og-api/api.ogt by `og api gen`. Do not edit: `og api check` fails on any difference; change api.ogt and regenerate. -->
+
+# The `video` module
+
+Footage in a game (docs/design.md §2.9): a `type video` asset cooked by ffmpeg into a texture array of its frames and its sound, loaded with og.load.video and played by og.VideoPlayer. The frame shown is a Texture (VideoInfo.texture, also VideoPlayer.texture) any material map, og.Sprite or UI image draws, and the sound plays on the entity's og.AudioSource in step with it.
+
+Playback is simulation: the og.video system (after the game's systems, before og.audio) advances VideoPlayer.time by the tick's dt times `speed` (not the time scale, so the picture stays with its sound), so the frame at a tick is the same on both hosts, in every run and after a snapshot is restored. With a 30 Hz tick a player started at 0 shows the source's frame 3 s in at tick 90.
+
+- **TypeScript**: functions are none at module level (its members live on the types below); components, resources and events are tokens on `og`.
+- **Publish builds**: kept (members may override).
+- **Skill**: `og-game`, which teaches the module (how much of it to use, and how to prove it).
+- **Index**: [every module and name](index.md).
+
+```ogt
+module video {
+  # declarations follow, each quoted below
+```
+
+<sub>`api.ogt` line 13361</sub>
+
+## Contents
+
+| Name | Kind | Summary |
+|---|---|---|
+| [`Video`](#type-Video) | handle | Cooked footage: its frames as a texture array, its sound (og.load.video). |
+| [`Video()`](#column-Video) | column kind | A Video handle field (0 is none). |
+| [`VideoInfo`](#type-VideoInfo) | struct | What og.load.video loaded. |
+| [`og.VideoPlayer`](#record-VideoPlayer) | component | Plays a loaded video: VideoInfo.texture shows its current frame (frame n is the source at n / fps seconds), and when the entity has an og.AudioSource the og.video system sets its sound, playing, pitch and loop each tick so the sound plays in step: a seek or a restart starts the sound again at the new time on the next tick (AudioSource.startOffset). Each player has a texture of its own (written to `texture`): the first player of a video takes VideoInfo.texture, each further one a texture the og.video system makes for it over the same decoded frames (one frame of GPU memory each), so two players at different times show different frames. Show a player's `texture`, not VideoInfo.texture, once a video has more than one player. |
+
+## Components, resources and events
+
+<a id="record-VideoPlayer"></a>
+
+### `og.VideoPlayer` (component)
+
+Plays a loaded video: VideoInfo.texture shows its current frame (frame n is the source at n / fps seconds), and when the entity has an og.AudioSource the og.video system sets its sound, playing, pitch and loop each tick so the sound plays in step: a seek or a restart starts the sound again at the new time on the next tick (AudioSource.startOffset). Each player has a texture of its own (written to `texture`): the first player of a video takes VideoInfo.texture, each further one a texture the og.video system makes for it over the same decoded frames (one frame of GPU memory each), so two players at different times show different frames. Show a player's `texture`, not VideoInfo.texture, once a video has more than one player.
+
+Token `og.VideoPlayer`, registered under the schema name `og.VideoPlayer`; its value type is `VideoPlayer`.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `video` | `Video` | `0` | — | — | — | The video (og.load.video's `video`); 0 plays nothing. |
+| `playing` | `boolean` | `true` | — | — | — | Whether time advances. |
+| `time` | `number` | `0` | ≥ 0 | `s` | — | Seconds into the video; written every tick, set it to seek. |
+| `speed` | `number` | `1` | 0 … 4 | — | tunable | The playback rate: 1 as cooked, 0.5 half speed (the sound's pitch follows). |
+| `loop` | `boolean` | `false` | — | — | — | Start again at 0 past the end; otherwise hold the last frame and set finished. |
+| `frame` | `number` | `0` | — | — | read only | Written: the frame shown, floor(time * fps). |
+| `finished` | `boolean` | `false` | — | — | read only | Written: a player without loop reached the end. |
+| `texture` | `Texture` | `0` | — | — | read only | Written: this player's texture (VideoInfo.texture for the video's first player, a texture of its own for each further one), for a material, sprite or UI image set up from the player. It keeps it while it lives. |
+
+```ogt
+component VideoPlayer {
+  doc "Plays a loaded video: VideoInfo.texture shows its current frame (frame n is the source at n / fps seconds), and when the entity has an og.AudioSource the og.video system sets its sound, playing, pitch and loop each tick so the sound plays in step: a seek or a restart starts the sound again at the new time on the next tick (AudioSource.startOffset). Each player has a texture of its own (written to `texture`): the first player of a video takes VideoInfo.texture, each further one a texture the og.video system makes for it over the same decoded frames (one frame of GPU memory each), so two players at different times show different frames. Show a player's `texture`, not VideoInfo.texture, once a video has more than one player."
+  field video Video "The video (og.load.video's `video`); 0 plays nothing."
+  field playing bool "Whether time advances." {
+    default true
+  }
+  field time f32 "Seconds into the video; written every tick, set it to seek." {
+    min 0
+    unit s
+  }
+  field speed f32 "The playback rate: 1 as cooked, 0.5 half speed (the sound's pitch follows)." {
+    default 1
+    min 0
+    max 4
+    tunable true
+  }
+  field loop bool "Start again at 0 past the end; otherwise hold the last frame and set finished."
+  field frame u32 "Written: the frame shown, floor(time * fps)." {
+    readonly true
+  }
+  field finished bool "Written: a player without loop reached the end." {
+    readonly true
+  }
+  field texture Texture "Written: this player's texture (VideoInfo.texture for the video's first player, a texture of its own for each further one), for a material, sprite or UI image set up from the player. It keeps it while it lives." {
+    readonly true
+  }
+}
+```
+
+<sub>`api.ogt` line 13393</sub>
+
+## Types
+
+<a id="type-Video"></a>
+
+### `Video` (handle)
+
+Cooked footage: its frames as a texture array, its sound (og.load.video).
+
+A generational handle: a number the engine hands out. A dead handle is an error value, never a crash.
+
+```ogt
+handle Video "Cooked footage: its frames as a texture array, its sound (og.load.video)."
+```
+
+<sub>`api.ogt` line 13366</sub>
+
+<a id="type-VideoInfo"></a>
+
+### `VideoInfo` (struct)
+
+What og.load.video loaded.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `video` | `Video` | `0` | — | — | — | The video. |
+| `texture` | `Texture` | `0` | — | — | — | The texture that shows the frame its og.VideoPlayer is at (frame 0 until one plays it). |
+| `sound` | `Sound` | `0` | — | — | — | Its sound track (og.load.sound's kind of handle, for an og.AudioSource); 0 when it has none or was cooked with `audio false`. |
+| `width` | `number` | `0` | — | — | — | Each frame's width in texels. |
+| `height` | `number` | `0` | — | — | — | Each frame's height in texels. |
+| `frames` | `number` | `0` | — | — | — | Frames kept (at most 256). |
+| `fps` | `number` | `0` | — | — | — | Frames per second kept. |
+| `seconds` | `number` | `0` | — | `s` | — | frames / fps. |
+| `format` | `string` | `""` | — | — | — | The frames' encoding on the GPU (`rgba8`, `bc7`, `astc4x4`, `etc2`). |
+| `bytes` | `number` | `0` | — | `bytes` | — | Bytes its frames take on the GPU. |
+
+```ogt
+struct VideoInfo {
+  doc "What og.load.video loaded."
+  field video Video "The video."
+  field texture Texture "The texture that shows the frame its og.VideoPlayer is at (frame 0 until one plays it)."
+  field sound Sound "Its sound track (og.load.sound's kind of handle, for an og.AudioSource); 0 when it has none or was cooked with `audio false`."
+  field width u32 "Each frame's width in texels."
+  field height u32 "Each frame's height in texels."
+  field frames u32 "Frames kept (at most 256)."
+  field fps u32 "Frames per second kept."
+  field seconds f32 "frames / fps." {
+    unit s
+  }
+  field format String "The frames' encoding on the GPU (`rgba8`, `bc7`, `astc4x4`, `etc2`)."
+  field bytes f64 "Bytes its frames take on the GPU." {
+    unit bytes
+  }
+}
+```
+
+<sub>`api.ogt` line 13375</sub>
+
+## Column kinds
+
+Each is a factory, `Video(value?, options?)`, that makes one field of a component or resource layout.
+
+| Column | Value | Typed array | Stride | Doc |
+|---|---|---|---|---|
+| <a id="column-Video"></a>`Video` | `Video` | `Uint32Array` | 2 | A Video handle field (0 is none). |
+
+```ogt
+column Video {
+  doc "A Video handle field (0 is none)."
+  array Uint32Array
+  stride 2
+  value Video
+}
+```
+
+<sub>`api.ogt` line 13368</sub>

package/knowledge/wiki/world.md

@@ -16,7 +16,7 @@ module world {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 205</sub>
+<sub>`api.ogt` line 778</sub>
 
 ## Contents
 
@@ -59,7 +59,7 @@ event WorldRestored {
 }
 ```
 
-<sub>`api.ogt` line 243</sub>
+<sub>`api.ogt` line 816</sub>
 
 ## Interfaces
 
@@ -75,7 +75,7 @@ interface World {
   # members follow, each quoted below
 ```
 
-<sub>`api.ogt` line 260</sub>
+<sub>`api.ogt` line 833</sub>
 
 <a id="member-World-tick"></a>
 
@@ -93,7 +93,7 @@ Binding symbol `og_world_get_tick` · publish builds: kept
 prop tick u32 "Fixed steps taken since the world was created."
 ```
 
-<sub>`api.ogt` line 263</sub>
+<sub>`api.ogt` line 836</sub>
 
 <a id="member-World-spawn"></a>
 
@@ -121,7 +121,7 @@ fn spawn {
 }
 ```
 
-<sub>`api.ogt` line 265</sub>
+<sub>`api.ogt` line 838</sub>
 
 <a id="member-World-despawn"></a>
 
@@ -149,7 +149,7 @@ fn despawn {
 }
 ```
 
-<sub>`api.ogt` line 271</sub>
+<sub>`api.ogt` line 844</sub>
 
 <a id="member-World-alive"></a>
 
@@ -177,7 +177,7 @@ fn alive {
 }
 ```
 
-<sub>`api.ogt` line 277</sub>
+<sub>`api.ogt` line 850</sub>
 
 <a id="member-World-has"></a>
 
@@ -208,7 +208,7 @@ fn has {
 }
 ```
 
-<sub>`api.ogt` line 283</sub>
+<sub>`api.ogt` line 856</sub>
 
 <a id="member-World-insert"></a>
 
@@ -243,7 +243,7 @@ fn insert {
 }
 ```
 
-<sub>`api.ogt` line 291</sub>
+<sub>`api.ogt` line 864</sub>
 
 <a id="member-World-remove"></a>
 
@@ -274,7 +274,7 @@ fn remove {
 }
 ```
 
-<sub>`api.ogt` line 302</sub>
+<sub>`api.ogt` line 875</sub>
 
 <a id="member-World-get"></a>
 
@@ -305,7 +305,7 @@ fn get {
 }
 ```
 
-<sub>`api.ogt` line 310</sub>
+<sub>`api.ogt` line 883</sub>
 
 <a id="member-World-set"></a>
 
@@ -338,7 +338,7 @@ fn set {
 }
 ```
 
-<sub>`api.ogt` line 318</sub>
+<sub>`api.ogt` line 891</sub>
 
 <a id="member-World-resource"></a>
 
@@ -367,7 +367,7 @@ fn resource {
 }
 ```
 
-<sub>`api.ogt` line 327</sub>
+<sub>`api.ogt` line 900</sub>
 
 <a id="member-World-find"></a>
 
@@ -395,7 +395,7 @@ fn find {
 }
 ```
 
-<sub>`api.ogt` line 334</sub>
+<sub>`api.ogt` line 907</sub>
 
 <a id="member-World-nameOf"></a>
 
@@ -423,7 +423,7 @@ fn nameOf {
 }
 ```
 
-<sub>`api.ogt` line 340</sub>
+<sub>`api.ogt` line 913</sub>
 
 <a id="member-World-query"></a>
 
@@ -451,7 +451,7 @@ fn query {
 }
 ```
 
-<sub>`api.ogt` line 346</sub>
+<sub>`api.ogt` line 919</sub>
 
 <a id="member-World-events"></a>
 
@@ -480,7 +480,7 @@ fn events {
 }
 ```
 
-<sub>`api.ogt` line 352</sub>
+<sub>`api.ogt` line 925</sub>
 
 <a id="member-World-emit"></a>
 
@@ -511,7 +511,7 @@ fn emit {
 }
 ```
 
-<sub>`api.ogt` line 359</sub>
+<sub>`api.ogt` line 932</sub>
 
 <a id="member-World-instantiate"></a>
 
@@ -544,7 +544,7 @@ fn instantiate {
 }
 ```
 
-<sub>`api.ogt` line 367</sub>
+<sub>`api.ogt` line 940</sub>
 
 <a id="member-World-snapshot"></a>
 
@@ -567,7 +567,7 @@ fn snapshot {
 }
 ```
 
-<sub>`api.ogt` line 375</sub>
+<sub>`api.ogt` line 948</sub>
 
 <a id="member-World-restore"></a>
 
@@ -597,7 +597,7 @@ fn restore {
 }
 ```
 
-<sub>`api.ogt` line 380</sub>
+<sub>`api.ogt` line 953</sub>
 
 <a id="type-Query"></a>
 
@@ -611,7 +611,7 @@ interface Query {
   # members follow, each quoted below
 ```
 
-<sub>`api.ogt` line 388</sub>
+<sub>`api.ogt` line 961</sub>
 
 <a id="member-Query-archetypes"></a>
 
@@ -634,7 +634,7 @@ fn archetypes {
 }
 ```
 
-<sub>`api.ogt` line 390</sub>
+<sub>`api.ogt` line 963</sub>
 
 <a id="member-Query-count"></a>
 
@@ -657,7 +657,7 @@ fn count {
 }
 ```
 
-<sub>`api.ogt` line 394</sub>
+<sub>`api.ogt` line 967</sub>
 
 <a id="type-ArchetypeView"></a>
 
@@ -671,7 +671,7 @@ interface ArchetypeView {
   # members follow, each quoted below
 ```
 
-<sub>`api.ogt` line 400</sub>
+<sub>`api.ogt` line 973</sub>
 
 <a id="member-ArchetypeView-count"></a>
 
@@ -689,7 +689,7 @@ Binding symbol `og_archetype_view_get_count` · publish builds: kept
 prop count u32 "The number of entities in the archetype."
 ```
 
-<sub>`api.ogt` line 402</sub>
+<sub>`api.ogt` line 975</sub>
 
 <a id="member-ArchetypeView-tick"></a>
 
@@ -707,7 +707,7 @@ Binding symbol `og_archetype_view_get_tick` · publish builds: kept
 prop tick u32 "The tick this view belongs to."
 ```
 
-<sub>`api.ogt` line 403</sub>
+<sub>`api.ogt` line 976</sub>
 
 <a id="member-ArchetypeView-entities"></a>
 
@@ -725,7 +725,7 @@ Binding symbol `og_archetype_view_get_entities` · publish builds: kept
 prop entities Uint32Array "The entities as (index, generation) pairs: entity i is at 2i and 2i + 1."
 ```
 
-<sub>`api.ogt` line 404</sub>
+<sub>`api.ogt` line 977</sub>
 
 <a id="member-ArchetypeView-entity"></a>
 
@@ -753,7 +753,7 @@ fn entity {
 }
 ```
 
-<sub>`api.ogt` line 405</sub>
+<sub>`api.ogt` line 978</sub>
 
 <a id="member-ArchetypeView-has"></a>
 
@@ -782,7 +782,7 @@ fn has {
 }
 ```
 
-<sub>`api.ogt` line 410</sub>
+<sub>`api.ogt` line 983</sub>
 
 <a id="member-ArchetypeView-column"></a>
 
@@ -814,7 +814,7 @@ fn column {
 }
 ```
 
-<sub>`api.ogt` line 416</sub>
+<sub>`api.ogt` line 989</sub>
 
 ## Types
 
@@ -835,7 +835,7 @@ handle Entity {
 }
 ```
 
-<sub>`api.ogt` line 210</sub>
+<sub>`api.ogt` line 783</sub>
 
 <a id="type-SpawnDesc"></a>
 
@@ -871,7 +871,7 @@ struct SpawnDesc {
 }
 ```
 
-<sub>`api.ogt` line 222</sub>
+<sub>`api.ogt` line 795</sub>
 
 <a id="type-RestoreDesc"></a>
 
@@ -893,7 +893,7 @@ struct RestoreDesc {
 }
 ```
 
-<sub>`api.ogt` line 237</sub>
+<sub>`api.ogt` line 810</sub>
 
 <a id="type-QueryDesc"></a>
 
@@ -917,7 +917,7 @@ struct QueryDesc {
 }
 ```
 
-<sub>`api.ogt` line 253</sub>
+<sub>`api.ogt` line 826</sub>
 
 ## Column kinds
 
@@ -936,4 +936,4 @@ column Entity {
 }
 ```
 
-<sub>`api.ogt` line 215</sub>
+<sub>`api.ogt` line 788</sub>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@origingame/engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Origin Engine: the TypeScript API, generated from crates/og-api/api.ogt, its runtime on the web (wasm in a Worker) and native (napi addon) hosts, the player shell, and the agents' knowledge (skills, wiki, style catalogue) in knowledge/.",
   "license": "MIT",
   "repository": {
@@ -51,8 +51,9 @@
     "bun": ">=1.3"
   },
   "optionalDependencies": {
-    "@origingame/engine-darwin-arm64": "0.2.0",
-    "@origingame/engine-linux-x64": "0.2.0",
+    "@origingame/engine-darwin-arm64": "0.3.0",
+    "@origingame/engine-linux-x64": "0.3.0",
+    "@origingame/engine-win32-x64": "0.3.0",
     "@tsrs/darwin-arm64": "0.18.0-ts7.1.0-dev.20260929",
     "@tsrs/linux-arm64-gnu": "0.18.0-ts7.1.0-dev.20260929",
     "@tsrs/linux-arm64-musl": "0.18.0-ts7.1.0-dev.20260929",