@origingame/engine 0.1.1 → 0.3.0

package/knowledge/wiki/atmosphere.md

@@ -16,7 +16,7 @@ module atmosphere {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 5220</sub>
+<sub>`api.ogt` line 6734</sub>
 
 ## Contents
 
@@ -63,7 +63,7 @@ fn timeOfDay {
 }
 ```
 
-<sub>`api.ogt` line 5597</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 5231</sub>
+<sub>`api.ogt` line 6745</sub>
 
 <a id="record-Sky"></a>
 
@@ -261,7 +284,7 @@ resource Sky {
 }
 ```
 
-<sub>`api.ogt` line 5293</sub>
+<sub>`api.ogt` line 6826</sub>
 
 <a id="record-DayNight"></a>
 
@@ -343,7 +366,7 @@ resource DayNight {
 }
 ```
 
-<sub>`api.ogt` line 5368</sub>
+<sub>`api.ogt` line 6901</sub>
 
 <a id="record-Weather"></a>
 
@@ -405,7 +428,7 @@ resource Weather {
 }
 ```
 
-<sub>`api.ogt` line 5425</sub>
+<sub>`api.ogt` line 6958</sub>
 
 <a id="record-Water"></a>
 
@@ -539,7 +562,7 @@ component Water {
 }
 ```
 
-<sub>`api.ogt` line 5465</sub>
+<sub>`api.ogt` line 6998</sub>
 
 <a id="record-Water2D"></a>
 
@@ -593,7 +616,7 @@ component Water2D {
 }
 ```
 
-<sub>`api.ogt` line 5565</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 5225</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 5226</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 5227</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 5228</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 5229</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 6408</sub>
+<sub>`api.ogt` line 8069</sub>
 
 ## Contents
 
@@ -73,7 +73,7 @@ fn outputLatency {
 }
 ```
 
-<sub>`api.ogt` line 6788</sub>
+<sub>`api.ogt` line 8449</sub>
 
 ## Components, resources and events
 
@@ -200,7 +200,7 @@ component AudioSource {
 }
 ```
 
-<sub>`api.ogt` line 6435</sub>
+<sub>`api.ogt` line 8096</sub>
 
 <a id="record-AudioListener"></a>
 
@@ -226,7 +226,7 @@ component AudioListener {
 }
 ```
 
-<sub>`api.ogt` line 6523</sub>
+<sub>`api.ogt` line 8184</sub>
 
 <a id="record-Audio"></a>
 
@@ -314,7 +314,7 @@ resource Audio {
 }
 ```
 
-<sub>`api.ogt` line 6533</sub>
+<sub>`api.ogt` line 8194</sub>
 
 <a id="record-AudioBusFx"></a>
 
@@ -435,7 +435,7 @@ component AudioBusFx {
 }
 ```
 
-<sub>`api.ogt` line 6596</sub>
+<sub>`api.ogt` line 8257</sub>
 
 <a id="record-ReverbZone"></a>
 
@@ -506,7 +506,7 @@ component ReverbZone {
 }
 ```
 
-<sub>`api.ogt` line 6685</sub>
+<sub>`api.ogt` line 8346</sub>
 
 <a id="record-Music"></a>
 
@@ -562,7 +562,7 @@ component Music {
 }
 ```
 
-<sub>`api.ogt` line 6731</sub>
+<sub>`api.ogt` line 8392</sub>
 
 <a id="record-MusicBeat"></a>
 
@@ -589,7 +589,7 @@ event MusicBeat {
 }
 ```
 
-<sub>`api.ogt` line 6765</sub>
+<sub>`api.ogt` line 8426</sub>
 
 <a id="record-SoundStarted"></a>
 
@@ -614,7 +614,7 @@ event SoundStarted {
 }
 ```
 
-<sub>`api.ogt` line 6773</sub>
+<sub>`api.ogt` line 8434</sub>
 
 <a id="record-SoundEnded"></a>
 
@@ -641,7 +641,7 @@ event SoundEnded {
 }
 ```
 
-<sub>`api.ogt` line 6780</sub>
+<sub>`api.ogt` line 8441</sub>
 
 ## Types
 
@@ -670,7 +670,7 @@ enum AudioBus {
 }
 ```
 
-<sub>`api.ogt` line 6420</sub>
+<sub>`api.ogt` line 8081</sub>
 
 ## Column kinds
 
@@ -689,7 +689,7 @@ column AudioBus {
 }
 ```
 
-<sub>`api.ogt` line 6428</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 6414</sub>
+<sub>`api.ogt` line 8075</sub>
 
 ```ogt
 const SOUND_STOPPED u32 1 "SoundEnded.reason: `playing` was set to false."
 ```
 
-<sub>`api.ogt` line 6415</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 6416</sub>
+<sub>`api.ogt` line 8077</sub>
 
 ```ogt
 const SOUND_REPLACED u32 3 "SoundEnded.reason: `sound` changed while it played."
 ```
 
-<sub>`api.ogt` line 6417</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 6418</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 1288</sub>
+<sub>`api.ogt` line 1872</sub>
 
 ## Contents
 
@@ -62,7 +62,7 @@ fn shake {
 }
 ```
 
-<sub>`api.ogt` line 1624</sub>
+<sub>`api.ogt` line 2212</sub>
 
 <a id="fn-punch"></a>
 
@@ -92,7 +92,7 @@ fn punch {
 }
 ```
 
-<sub>`api.ogt` line 1631</sub>
+<sub>`api.ogt` line 2219</sub>
 
 <a id="fn-kick"></a>
 
@@ -124,7 +124,7 @@ fn kick {
 }
 ```
 
-<sub>`api.ogt` line 1638</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 1293</sub>
+<sub>`api.ogt` line 1877</sub>
 
 <a id="member-Camera-lookAt"></a>
 
@@ -325,7 +329,7 @@ fn lookAt {
 }
 ```
 
-<sub>`api.ogt` line 1406</sub>
+<sub>`api.ogt` line 1990</sub>
 
 <a id="member-Camera-worldToScreen"></a>
 
@@ -353,7 +357,7 @@ fn worldToScreen {
 }
 ```
 
-<sub>`api.ogt` line 1410</sub>
+<sub>`api.ogt` line 1994</sub>
 
 <a id="member-Camera-screenToRay"></a>
 
@@ -383,7 +387,7 @@ fn screenToRay {
 }
 ```
 
-<sub>`api.ogt` line 1415</sub>
+<sub>`api.ogt` line 1999</sub>
 
 <a id="record-OrbitCamera"></a>
 
@@ -491,7 +495,7 @@ component OrbitCamera {
 }
 ```
 
-<sub>`api.ogt` line 1423</sub>
+<sub>`api.ogt` line 2010</sub>
 
 <a id="record-FollowCamera"></a>
 
@@ -529,7 +533,7 @@ component FollowCamera {
 }
 ```
 
-<sub>`api.ogt` line 1497</sub>
+<sub>`api.ogt` line 2084</sub>
 
 <a id="record-Follow2D"></a>
 
@@ -608,7 +612,7 @@ component Follow2D {
 }
 ```
 
-<sub>`api.ogt` line 1516</sub>
+<sub>`api.ogt` line 2103</sub>
 
 <a id="record-CameraZone"></a>
 
@@ -643,7 +647,7 @@ component CameraZone {
 }
 ```
 
-<sub>`api.ogt` line 1568</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 1584</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 10355</sub>
+<sub>`api.ogt` line 12139</sub>
 
 ## Contents
 
@@ -67,7 +67,7 @@ fn register {
 }
 ```
 
-<sub>`api.ogt` line 10431</sub>
+<sub>`api.ogt` line 12218</sub>
 
 <a id="fn-parse"></a>
 
@@ -95,7 +95,7 @@ fn parse {
 }
 ```
 
-<sub>`api.ogt` line 10439</sub>
+<sub>`api.ogt` line 12226</sub>
 
 <a id="fn-help"></a>
 
@@ -123,7 +123,7 @@ fn help {
 }
 ```
 
-<sub>`api.ogt` line 10445</sub>
+<sub>`api.ogt` line 12232</sub>
 
 <a id="fn-schedule"></a>
 
@@ -153,7 +153,7 @@ fn schedule {
 }
 ```
 
-<sub>`api.ogt` line 10451</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 10362</sub>
+<sub>`api.ogt` line 12146</sub>
 
 <a id="type-CommandHandler"></a>
 
@@ -257,7 +263,7 @@ callback CommandHandler {
 }
 ```
 
-<sub>`api.ogt` line 10394</sub>
+<sub>`api.ogt` line 12181</sub>
 
 <a id="type-CommandDesc"></a>
 
@@ -281,7 +287,7 @@ struct CommandDesc {
 }
 ```
 
-<sub>`api.ogt` line 10400</sub>
+<sub>`api.ogt` line 12187</sub>
 
 <a id="type-CommandStep"></a>
 
@@ -306,7 +312,7 @@ struct CommandStep {
 }
 ```
 
-<sub>`api.ogt` line 10407</sub>
+<sub>`api.ogt` line 12194</sub>
 
 <a id="type-CommandInfo"></a>
 
@@ -331,7 +337,7 @@ struct CommandInfo {
 }
 ```
 
-<sub>`api.ogt` line 10416</sub>
+<sub>`api.ogt` line 12203</sub>
 
 <a id="type-CommandsReport"></a>
 
@@ -354,4 +360,4 @@ struct CommandsReport {
 }
 ```
 
-<sub>`api.ogt` line 10424</sub>
+<sub>`api.ogt` line 12211</sub>