@origingame/engine 0.2.0 → 0.3.0

package/knowledge/wiki/atmosphere.md

@@ -16,7 +16,7 @@ module atmosphere {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 5250</sub>
+<sub>`api.ogt` line 6734</sub>
 
 ## Contents
 
@@ -63,7 +63,7 @@ fn timeOfDay {
 }
 ```
 
-<sub>`api.ogt` line 5627</sub>
+<sub>`api.ogt` line 7130</sub>
 
 ## Components, resources and events
 
@@ -89,6 +89,10 @@ Token `og.Fog`, registered under the schema name `og.Fog`; its value type is `Fo
 | `sunPower` | `number` | `8` | 0 … 256 | — | tunable | How tight the sun's glow in the fog is (higher: smaller). |
 | `maxOpacity` | `number` | `1` | 0 … 1 | `ratio` | tunable | The most the fog hides. |
 | `sky` | `number` | `1` | 0 … 1 | `ratio` | tunable | How much of the fog covers the sky (0: the sky stays clear). |
+| `volumetric` | `boolean` | `false` | — | — | — | Light the fog as a participating medium: within volumetricDistance of the camera the fog (density per metre, thickened below height by heightDensity and falloff, as above) scatters the sun through its shadow cascades, so light shafts fall through windows and between trees and move with the sun, and every point, spot and rect light it is lit by (up to RenderCapabilities.volumetricLights at each sample); it dims what lies behind it by the same amounts. RenderCapabilities.volumetricFog names the method (a froxel grid on the full tier, a raymarch on WebGL2). Opaque surfaces and the sky are seen through the volume; blended surfaces, particles and sprites take the plain distance and height fog of the same medium. Past volumetricDistance nothing more is added. |
+| `scattering` | `number` | `0.8` | 0 … 4 | — | tunable | How much of the light the fog takes from a ray it scatters (its albedo, tinted by color): 0 dims without glowing, 1 sends all of it on, above 1 brightens the shafts for effect. |
+| `anisotropy` | `number` | `0.6` | -0.95 … 0.95 | — | tunable | Which way the fog scatters (Henyey–Greenstein g): 0 evenly, towards 1 forward (bright looking into the light: shafts against the sun), below 0 back towards the light. |
+| `volumetricDistance` | `number` | `48` | 4 … 400 | `m` | — | How far from the camera the volume reaches. |
 
 ```ogt
 resource Fog {
@@ -151,10 +155,29 @@ resource Fog {
     unit ratio
     tunable true
   }
+  field volumetric bool "Light the fog as a participating medium: within volumetricDistance of the camera the fog (density per metre, thickened below height by heightDensity and falloff, as above) scatters the sun through its shadow cascades, so light shafts fall through windows and between trees and move with the sun, and every point, spot and rect light it is lit by (up to RenderCapabilities.volumetricLights at each sample); it dims what lies behind it by the same amounts. RenderCapabilities.volumetricFog names the method (a froxel grid on the full tier, a raymarch on WebGL2). Opaque surfaces and the sky are seen through the volume; blended surfaces, particles and sprites take the plain distance and height fog of the same medium. Past volumetricDistance nothing more is added."
+  field scattering f32 "How much of the light the fog takes from a ray it scatters (its albedo, tinted by color): 0 dims without glowing, 1 sends all of it on, above 1 brightens the shafts for effect." {
+    default 0.8
+    min 0
+    max 4
+    tunable true
+  }
+  field anisotropy f32 "Which way the fog scatters (Henyey–Greenstein g): 0 evenly, towards 1 forward (bright looking into the light: shafts against the sun), below 0 back towards the light." {
+    default 0.6
+    min -0.95
+    max 0.95
+    tunable true
+  }
+  field volumetricDistance f32 "How far from the camera the volume reaches." {
+    default 48
+    min 4
+    max 400
+    unit m
+  }
 }
 ```
 
-<sub>`api.ogt` line 5261</sub>
+<sub>`api.ogt` line 6745</sub>
 
 <a id="record-Sky"></a>
 
@@ -261,7 +284,7 @@ resource Sky {
 }
 ```
 
-<sub>`api.ogt` line 5323</sub>
+<sub>`api.ogt` line 6826</sub>
 
 <a id="record-DayNight"></a>
 
@@ -343,7 +366,7 @@ resource DayNight {
 }
 ```
 
-<sub>`api.ogt` line 5398</sub>
+<sub>`api.ogt` line 6901</sub>
 
 <a id="record-Weather"></a>
 
@@ -405,7 +428,7 @@ resource Weather {
 }
 ```
 
-<sub>`api.ogt` line 5455</sub>
+<sub>`api.ogt` line 6958</sub>
 
 <a id="record-Water"></a>
 
@@ -539,7 +562,7 @@ component Water {
 }
 ```
 
-<sub>`api.ogt` line 5495</sub>
+<sub>`api.ogt` line 6998</sub>
 
 <a id="record-Water2D"></a>
 
@@ -593,7 +616,7 @@ component Water2D {
 }
 ```
 
-<sub>`api.ogt` line 5595</sub>
+<sub>`api.ogt` line 7098</sub>
 
 ## Constants
 
@@ -609,28 +632,28 @@ component Water2D {
 const WEATHER_NONE u32 0 "Weather.kind: clear."
 ```
 
-<sub>`api.ogt` line 5255</sub>
+<sub>`api.ogt` line 6739</sub>
 
 ```ogt
 const WEATHER_RAIN u32 1 "Weather.kind: rain streaks falling with the wind, the light dimmed and a grey distance fog."
 ```
 
-<sub>`api.ogt` line 5256</sub>
+<sub>`api.ogt` line 6740</sub>
 
 ```ogt
 const WEATHER_SNOW u32 2 "Weather.kind: flakes drifting down on gusts, a pale fog."
 ```
 
-<sub>`api.ogt` line 5257</sub>
+<sub>`api.ogt` line 6741</sub>
 
 ```ogt
 const WEATHER_DUST u32 3 "Weather.kind: dust blowing along the wind near the ground, a warm thick fog."
 ```
 
-<sub>`api.ogt` line 5258</sub>
+<sub>`api.ogt` line 6742</sub>
 
 ```ogt
 const WEATHER_MIST u32 4 "Weather.kind: no particles, a dense low height fog."
 ```
 
-<sub>`api.ogt` line 5259</sub>
+<sub>`api.ogt` line 6743</sub>

package/knowledge/wiki/audio.md

@@ -18,7 +18,7 @@ module audio {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 6440</sub>
+<sub>`api.ogt` line 8069</sub>
 
 ## Contents
 
@@ -73,7 +73,7 @@ fn outputLatency {
 }
 ```
 
-<sub>`api.ogt` line 6820</sub>
+<sub>`api.ogt` line 8449</sub>
 
 ## Components, resources and events
 
@@ -200,7 +200,7 @@ component AudioSource {
 }
 ```
 
-<sub>`api.ogt` line 6467</sub>
+<sub>`api.ogt` line 8096</sub>
 
 <a id="record-AudioListener"></a>
 
@@ -226,7 +226,7 @@ component AudioListener {
 }
 ```
 
-<sub>`api.ogt` line 6555</sub>
+<sub>`api.ogt` line 8184</sub>
 
 <a id="record-Audio"></a>
 
@@ -314,7 +314,7 @@ resource Audio {
 }
 ```
 
-<sub>`api.ogt` line 6565</sub>
+<sub>`api.ogt` line 8194</sub>
 
 <a id="record-AudioBusFx"></a>
 
@@ -435,7 +435,7 @@ component AudioBusFx {
 }
 ```
 
-<sub>`api.ogt` line 6628</sub>
+<sub>`api.ogt` line 8257</sub>
 
 <a id="record-ReverbZone"></a>
 
@@ -506,7 +506,7 @@ component ReverbZone {
 }
 ```
 
-<sub>`api.ogt` line 6717</sub>
+<sub>`api.ogt` line 8346</sub>
 
 <a id="record-Music"></a>
 
@@ -562,7 +562,7 @@ component Music {
 }
 ```
 
-<sub>`api.ogt` line 6763</sub>
+<sub>`api.ogt` line 8392</sub>
 
 <a id="record-MusicBeat"></a>
 
@@ -589,7 +589,7 @@ event MusicBeat {
 }
 ```
 
-<sub>`api.ogt` line 6797</sub>
+<sub>`api.ogt` line 8426</sub>
 
 <a id="record-SoundStarted"></a>
 
@@ -614,7 +614,7 @@ event SoundStarted {
 }
 ```
 
-<sub>`api.ogt` line 6805</sub>
+<sub>`api.ogt` line 8434</sub>
 
 <a id="record-SoundEnded"></a>
 
@@ -641,7 +641,7 @@ event SoundEnded {
 }
 ```
 
-<sub>`api.ogt` line 6812</sub>
+<sub>`api.ogt` line 8441</sub>
 
 ## Types
 
@@ -670,7 +670,7 @@ enum AudioBus {
 }
 ```
 
-<sub>`api.ogt` line 6452</sub>
+<sub>`api.ogt` line 8081</sub>
 
 ## Column kinds
 
@@ -689,7 +689,7 @@ column AudioBus {
 }
 ```
 
-<sub>`api.ogt` line 6460</sub>
+<sub>`api.ogt` line 8089</sub>
 
 ## Constants
 
@@ -705,28 +705,28 @@ column AudioBus {
 const SOUND_FINISHED u32 0 "SoundEnded.reason: a one-shot played to its end."
 ```
 
-<sub>`api.ogt` line 6446</sub>
+<sub>`api.ogt` line 8075</sub>
 
 ```ogt
 const SOUND_STOPPED u32 1 "SoundEnded.reason: `playing` was set to false."
 ```
 
-<sub>`api.ogt` line 6447</sub>
+<sub>`api.ogt` line 8076</sub>
 
 ```ogt
 const SOUND_REMOVED u32 2 "SoundEnded.reason: the AudioSource was removed from a living entity."
 ```
 
-<sub>`api.ogt` line 6448</sub>
+<sub>`api.ogt` line 8077</sub>
 
 ```ogt
 const SOUND_REPLACED u32 3 "SoundEnded.reason: `sound` changed while it played."
 ```
 
-<sub>`api.ogt` line 6449</sub>
+<sub>`api.ogt` line 8078</sub>
 
 ```ogt
 const SOUND_CULLED u32 4 "SoundEnded.reason: more sources played than Audio.maxVoices and this one stood lowest (priority, then volume, then age)."
 ```
 
-<sub>`api.ogt` line 6450</sub>
+<sub>`api.ogt` line 8079</sub>

package/knowledge/wiki/camera.md

@@ -16,7 +16,7 @@ module camera {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 1299</sub>
+<sub>`api.ogt` line 1872</sub>
 
 ## Contents
 
@@ -62,7 +62,7 @@ fn shake {
 }
 ```
 
-<sub>`api.ogt` line 1635</sub>
+<sub>`api.ogt` line 2212</sub>
 
 <a id="fn-punch"></a>
 
@@ -92,7 +92,7 @@ fn punch {
 }
 ```
 
-<sub>`api.ogt` line 1642</sub>
+<sub>`api.ogt` line 2219</sub>
 
 <a id="fn-kick"></a>
 
@@ -124,7 +124,7 @@ fn kick {
 }
 ```
 
-<sub>`api.ogt` line 1649</sub>
+<sub>`api.ogt` line 2226</sub>
 
 ## Components, resources and events
 
@@ -165,6 +165,7 @@ Token `og.Camera`, registered under the schema name `og.Camera`; its value type
 | `zoneFromMax` | `Vector2` | `{ x: 0, y: 0 }` | — | `m` | — | Its top-right corner. |
 | `zoneScroll` | `number` | `1` | 0 … 1 | — | — | How far the transition has come, 0 to 1 (eased; 1 is settled). |
 | `zoneScrollTime` | `number` | `0` | ≥ 0 | `s` | — | How long the transition takes: the entered zone's scrollTime. |
+| `layers` | `number` | `1` | — | — | — | Three.js layers, as Camera.layers.mask: the frame draws the meshes, models, world sprites, particle systems, lines and points whose layers share a bit with it. 1 (layer 0) by default, as every object's. |
 
 ```ogt
 resource Camera {
@@ -295,10 +296,13 @@ resource Camera {
     param y f32 "Vertical position in CSS pixels."
     returns Ray
   }
+  field layers u32 "Three.js layers, as Camera.layers.mask: the frame draws the meshes, models, world sprites, particle systems, lines and points whose layers share a bit with it. 1 (layer 0) by default, as every object's." {
+    default 1
+  }
 }
 ```
 
-<sub>`api.ogt` line 1304</sub>
+<sub>`api.ogt` line 1877</sub>
 
 <a id="member-Camera-lookAt"></a>
 
@@ -325,7 +329,7 @@ fn lookAt {
 }
 ```
 
-<sub>`api.ogt` line 1417</sub>
+<sub>`api.ogt` line 1990</sub>
 
 <a id="member-Camera-worldToScreen"></a>
 
@@ -353,7 +357,7 @@ fn worldToScreen {
 }
 ```
 
-<sub>`api.ogt` line 1421</sub>
+<sub>`api.ogt` line 1994</sub>
 
 <a id="member-Camera-screenToRay"></a>
 
@@ -383,7 +387,7 @@ fn screenToRay {
 }
 ```
 
-<sub>`api.ogt` line 1426</sub>
+<sub>`api.ogt` line 1999</sub>
 
 <a id="record-OrbitCamera"></a>
 
@@ -491,7 +495,7 @@ component OrbitCamera {
 }
 ```
 
-<sub>`api.ogt` line 1434</sub>
+<sub>`api.ogt` line 2010</sub>
 
 <a id="record-FollowCamera"></a>
 
@@ -529,7 +533,7 @@ component FollowCamera {
 }
 ```
 
-<sub>`api.ogt` line 1508</sub>
+<sub>`api.ogt` line 2084</sub>
 
 <a id="record-Follow2D"></a>
 
@@ -608,7 +612,7 @@ component Follow2D {
 }
 ```
 
-<sub>`api.ogt` line 1527</sub>
+<sub>`api.ogt` line 2103</sub>
 
 <a id="record-CameraZone"></a>
 
@@ -643,7 +647,7 @@ component CameraZone {
 }
 ```
 
-<sub>`api.ogt` line 1579</sub>
+<sub>`api.ogt` line 2155</sub>
 
 <a id="record-CameraRail"></a>
 
@@ -665,6 +669,7 @@ Token `og.CameraRail`, registered under the schema name `og.CameraRail`; its val
 | `p6` | `Vector3` | `{ x: 0, y: 0, z: 0 }` | — | `m` | — | Rail point 6. |
 | `p7` | `Vector3` | `{ x: 0, y: 0, z: 0 }` | — | `m` | — | Rail point 7. |
 | `smoothTime` | `number` | `0.2` | ≥ 0 | `s` | tunable | Roughly how long the camera takes to catch up along the rail; 0 snaps. |
+| `path` | `Path` | `0` | — | — | — | A path (og.path.create, or a scene's `path` by og.path.find) the rail follows instead of p0 to p(points - 1): any number of points, catmullRom, bezier or linear, closed or not. 0 uses the points. |
 
 ```ogt
 component CameraRail {
@@ -705,7 +710,8 @@ component CameraRail {
     unit s
     tunable true
   }
+  field path Path "A path (og.path.create, or a scene's `path` by og.path.find) the rail follows instead of p0 to p(points - 1): any number of points, catmullRom, bezier or linear, closed or not. 0 uses the points."
 }
 ```
 
-<sub>`api.ogt` line 1595</sub>
+<sub>`api.ogt` line 2171</sub>

package/knowledge/wiki/commands.md

@@ -18,7 +18,7 @@ module commands {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 10420</sub>
+<sub>`api.ogt` line 12139</sub>
 
 ## Contents
 
@@ -67,7 +67,7 @@ fn register {
 }
 ```
 
-<sub>`api.ogt` line 10496</sub>
+<sub>`api.ogt` line 12218</sub>
 
 <a id="fn-parse"></a>
 
@@ -95,7 +95,7 @@ fn parse {
 }
 ```
 
-<sub>`api.ogt` line 10504</sub>
+<sub>`api.ogt` line 12226</sub>
 
 <a id="fn-help"></a>
 
@@ -123,7 +123,7 @@ fn help {
 }
 ```
 
-<sub>`api.ogt` line 10510</sub>
+<sub>`api.ogt` line 12232</sub>
 
 <a id="fn-schedule"></a>
 
@@ -153,7 +153,7 @@ fn schedule {
 }
 ```
 
-<sub>`api.ogt` line 10516</sub>
+<sub>`api.ogt` line 12238</sub>
 
 ## Types
 
@@ -186,7 +186,7 @@ A string: one of the variants below. The zero value is `"screenshot"`.
 | `"frame_entity"` | `frame_entity:<entity>`: point the camera at an entity. |
 | `"dump_world"` | `dump_world[:path]`: tables, systems and their matched counts. |
 | `"dump_entity"` | `dump_entity:<name>[:path]`: one entity's components and transform. |
-| `"dump_ui"` | `dump_ui[:path]`: the UI tree with bounds. |
+| `"dump_ui"` | `dump_ui[:path]`: the UI tree with bounds, and `style`, the configured UI style's name (empty for the placeholder prototype). |
 | `"set"` | `set:<entity>.<component>.<field>=<value>` or `set:<Resource>.<field>=<value>`: a Tune write through the schema: a number, `true` or `false` for a bool, `x,y,z` for a vector, an enum's variant name or its index; refused outside the field's FieldOptions min/max, never clamped. |
 | `"get"` | `get:<Resource>[.<field>]` or `get:<entity>[.<component>[.<field>]][:path]`: read through the schema as game code sees it (an enum as its variant's name, `"music"`; og.Time whole, with rate and the time scale; the DirectionalLight og.DayNight drives with the colour, intensity and direction it is drawn with), logged and written as JSON to `get-<tick>.json` (more unnamed ones on one tick: `get-<tick>-2.json`, ...). |
 | `"seed"` | `seed:<n>`: reseed the Rng resource. |
@@ -194,6 +194,9 @@ A string: one of the variants below. The zero value is `"screenshot"`.
 | `"resume"` | `resume`: release the clock. |
 | `"advance"` | `advance:<ticks>`: take fixed steps. |
 | `"quit"` | `quit`: exit. |
+| `"describe"` | `describe[:path]`: write the frame as data (probe.Description): the visible entities with screen boxes, depth order and occlusion from the entity-id pass, what each secondary camera (og.CameraView, og.Mirror) shows from its own pass, the UI elements with rects and text, the camera. |
+| `"expect"` | `expect:<what>`: assert at this tick (probe.ExpectResult): `entity:<id>:within:x,y,w,h` (its visible box, CSS pixels) or `:within:x0,y0,z0,x1,y1,z1` (its position, world units), `event:<Name>[:count]`, `ui:text:[=]<text>`, `region:x,y,w,h:color:#rrggbb[:tolerance]`, `frame:<ref.png>:rmse:<=v`, `state:<path>==<value>` (also != < <= > >=), `entity:<id>:<path>==<value>` (a field of its dump_entity: `render.lod==2`, `og.Transform.position.y>0`), `timings:<path>==<value>` (state().timings: `triangles<=1500000`). A failure is a warning with the tick and the observed value; `og run --json` lists every result and exits 1 on a failure. Frame expectations without a renderer are unchecked, as are an entity's `render.*` fields and the renderer's timings (`triangles`, `render`, `passes`). |
+| `"save_scene"` | `save_scene[:path][:spawned]`: write every scene the world was assembled from back from the world (the boot scene's, then each og.world.instantiate made, each to its own `.ogt`): only the lines whose values changed (comments and order kept), the fields set or patch tuned, and resources as `resource <Name> { }` blocks; with `spawned`, the entities the game spawned at run time under the boot scene's marked section. To each scene's source, or with a path the boot scene's to that file under the output directory and the others beside it. |
 | `"help"` | `help`: list every action the channel knows, core and registered. |
 
 ```ogt
@@ -218,7 +221,7 @@ enum CoreAction {
   variant frame_entity "`frame_entity:<entity>`: point the camera at an entity."
   variant dump_world "`dump_world[:path]`: tables, systems and their matched counts."
   variant dump_entity "`dump_entity:<name>[:path]`: one entity's components and transform."
-  variant dump_ui "`dump_ui[:path]`: the UI tree with bounds."
+  variant dump_ui "`dump_ui[:path]`: the UI tree with bounds, and `style`, the configured UI style's name (empty for the placeholder prototype)."
   variant set "`set:<entity>.<component>.<field>=<value>` or `set:<Resource>.<field>=<value>`: a Tune write through the schema: a number, `true` or `false` for a bool, `x,y,z` for a vector, an enum's variant name or its index; refused outside the field's FieldOptions min/max, never clamped."
   variant get "`get:<Resource>[.<field>]` or `get:<entity>[.<component>[.<field>]][:path]`: read through the schema as game code sees it (an enum as its variant's name, `\"music\"`; og.Time whole, with rate and the time scale; the DirectionalLight og.DayNight drives with the colour, intensity and direction it is drawn with), logged and written as JSON to `get-<tick>.json` (more unnamed ones on one tick: `get-<tick>-2.json`, ...)."
   variant seed "`seed:<n>`: reseed the Rng resource."
@@ -226,11 +229,14 @@ enum CoreAction {
   variant resume "`resume`: release the clock."
   variant advance "`advance:<ticks>`: take fixed steps."
   variant quit "`quit`: exit."
+  variant describe "`describe[:path]`: write the frame as data (probe.Description): the visible entities with screen boxes, depth order and occlusion from the entity-id pass, what each secondary camera (og.CameraView, og.Mirror) shows from its own pass, the UI elements with rects and text, the camera."
+  variant expect "`expect:<what>`: assert at this tick (probe.ExpectResult): `entity:<id>:within:x,y,w,h` (its visible box, CSS pixels) or `:within:x0,y0,z0,x1,y1,z1` (its position, world units), `event:<Name>[:count]`, `ui:text:[=]<text>`, `region:x,y,w,h:color:#rrggbb[:tolerance]`, `frame:<ref.png>:rmse:<=v`, `state:<path>==<value>` (also != < <= > >=), `entity:<id>:<path>==<value>` (a field of its dump_entity: `render.lod==2`, `og.Transform.position.y>0`), `timings:<path>==<value>` (state().timings: `triangles<=1500000`). A failure is a warning with the tick and the observed value; `og run --json` lists every result and exits 1 on a failure. Frame expectations without a renderer are unchecked, as are an entity's `render.*` fields and the renderer's timings (`triangles`, `render`, `passes`)."
+  variant save_scene "`save_scene[:path][:spawned]`: write every scene the world was assembled from back from the world (the boot scene's, then each og.world.instantiate made, each to its own `.ogt`): only the lines whose values changed (comments and order kept), the fields set or patch tuned, and resources as `resource <Name> { }` blocks; with `spawned`, the entities the game spawned at run time under the boot scene's marked section. To each scene's source, or with a path the boot scene's to that file under the output directory and the others beside it."
   variant help "`help`: list every action the channel knows, core and registered."
 }
 ```
 
-<sub>`api.ogt` line 10427</sub>
+<sub>`api.ogt` line 12146</sub>
 
 <a id="type-CommandHandler"></a>
 
@@ -257,7 +263,7 @@ callback CommandHandler {
 }
 ```
 
-<sub>`api.ogt` line 10459</sub>
+<sub>`api.ogt` line 12181</sub>
 
 <a id="type-CommandDesc"></a>
 
@@ -281,7 +287,7 @@ struct CommandDesc {
 }
 ```
 
-<sub>`api.ogt` line 10465</sub>
+<sub>`api.ogt` line 12187</sub>
 
 <a id="type-CommandStep"></a>
 
@@ -306,7 +312,7 @@ struct CommandStep {
 }
 ```
 
-<sub>`api.ogt` line 10472</sub>
+<sub>`api.ogt` line 12194</sub>
 
 <a id="type-CommandInfo"></a>
 
@@ -331,7 +337,7 @@ struct CommandInfo {
 }
 ```
 
-<sub>`api.ogt` line 10481</sub>
+<sub>`api.ogt` line 12203</sub>
 
 <a id="type-CommandsReport"></a>
 
@@ -354,4 +360,4 @@ struct CommandsReport {
 }
 ```
 
-<sub>`api.ogt` line 10489</sub>
+<sub>`api.ogt` line 12211</sub>