phoria2 1.2.0 → 1.4.0

package/llms-full.txt

@@ -139,12 +139,37 @@ Methods:
 - `on('click' | 'hover', (hit, event) => ...)` - see Interaction. Returns an unsubscribe function.
 - `tooltip(fn)` - set the tooltip function later.
 - `pick(x, y)` / `pick(event)` - the hit under a canvas position; `pickAll` for every hit.
+- `pickArea(area)` - every hit inside a box `{ x, y, width, height }` or a lasso of `[x, y]` points
+  (CSS pixels), nearest first - see Interaction.
 - `rayAt(x, y)` / `rayAt(event)` - the world `Ray` through a canvas position, for placing things:
   `ray.at(ray.intersectPlane([0, 1, 0], [0, 0, 0]))` is the point on the floor under the pointer
   (`intersectPlane` returns null when the ray runs along the plane or away from it).
 - `await view.toImage()` - a PNG `Blob` of the picture, labels included.
 - `await view.explain()` - a plain-text report of what is drawn, with warnings ("nothing in view",
   "no lights", labels hidden...). Use it to debug a blank or wrong picture.
+- `view.debug` (or the `debug` option) - pictures for a person checking a scene, drawn over it:
+  `true` for all but normals, or `{ lights, shadows, bounds, normals, axes, camera, stats }`.
+  - `lights`: an arrow for each directional light (over the scene's middle, the way it shines), a
+    small sphere and a ring at its range for point lights, a cone for spot lights - in the light's colour.
+  - `shadows`: the box (directional) or cone (spot) each shadow map is drawn from, in yellow - the
+    usual reason a shadow is cut off, blocky or soft.
+  - `bounds`: each drawable's world box, in cyan - what culling, `view.frame()` and shadow fitting
+    see. `'hovered'`: only what is under the pointer (an instance's own box).
+  - `normals`: a short magenta line along each vertex normal - for lighting that looks wrong on
+    imported or generated geometry. Meshes up to 5,000 vertices when all are shown; `'hovered'` shows
+    the mesh under the pointer, whatever its size.
+  - `axes`: x, y and z at the origin, red, green and blue. `camera`: the point the orbit turns round.
+  - `stats`: a corner readout - fps and frame time, the CPU time of a frame, draw calls, triangles,
+    programs, textures and geometries; `true` is top left, or `'top-right'`, `'bottom-left'`,
+    `'bottom-right'`.
+
+  The helpers are lines in the scene's depth that also show faintly through what is in front of
+  them. They aren't part of the scene: never picked, framed, saved or counted, and `explain()` says
+  when debug drawing is on. Their code loads the first time debug is turned on.
+
+  ```js
+  view.debug = { lights: true, shadows: true, bounds: 'hovered', stats: 'bottom-right' }
+  ```
 - `render()`, `invalidate()` (redraw after changing data the view can't see), `dispose()`.
 
 If a page shows nothing or the wrong thing, `console.log(await view.explain())` before anything else.
@@ -222,6 +247,24 @@ new Lines({ geometry: edges(box(2)), material: { color: '#333', width: 2 } })
 new Label({ text: 'Rack A1', position: [0, 2, 0], className: 'my-label', place: 'above' })
 ```
 
+**Lines** dashed and with arrowheads - flow and direction in network diagrams. Dashes are material
+options in the model's units: `dash` (0 is solid), `gap` (0 is the dash's length) and `dashOffset`,
+which moves them along - animate it for traffic. Arrowheads are Lines options: `arrows: 'start' |
+'end' | 'both'` puts them at the ends of each chain (segments each starting where the one before
+ended - a polyline is one chain, separate links are one each), `arrowSize` in pixels (0, the default,
+sizes them from the width). The dashes run on along a chain, and arrowheads are never dashed.
+
+```js
+const flow = view.scene.add(new Lines({ geometry: links, arrows: 'end', material: { color: '#4cc9f0', width: 2, dash: 0.3, gap: 0.15 } }))
+view.start((dt) => { flow.material.dashOffset += dt * 0.8 })   // traffic moving along each link
+```
+
+**Points** each their own size, opacity or angle: give the geometry `sizes` (multiples of the material's
+`size`), `opacities` (0-1) or `angles` (radians, turning the point's `map`), one per vertex. Such points
+are drawn as camera-facing squares, so any size works and they stay whole at the edge of the view.
+`sort: true` draws them furthest first each frame - for soft points with `blending: 'normal'`
+(smoke, cloud) that would otherwise layer wrongly; with additive blending order doesn't matter.
+
 **InstancedMesh** - many copies of one geometry in one draw call, for bars, racks, nodes:
 
 ```js
@@ -361,7 +404,10 @@ unless its `colorSpace` was set on purpose - `normalMap: await loadTexture('n.pn
 
 **Canvas and video textures**: a texture's `image` can be a canvas - draw on it, then call
 `texture.needsUpdate()` - or a `<video>`, whose frames upload by themselves while it plays, with
-nothing to call. `new Texture({ url: 'promo.mp4' })` (or .webm, .ogv, .mov, .m4v) makes the video
+nothing to call. For a big canvas drawn on a little at a time (paint, a map being revealed), say what
+changed - `texture.needsUpdate({ x, y, width, height })`, in the canvas's pixels from its top left -
+and only that rectangle is sent, rather than the whole canvas every frame (several calls before a
+frame add up). `new Texture({ url: 'promo.mp4' })` (or .webm, .ogv, .mov, .m4v) makes the video
 for you, muted and looping so browsers let it start by itself; `texture.image` is that `<video>` -
 pause, seek or unmute it as any other. A browser that blocks autoplay leaves it on its first frame
 until `texture.image.play()` from a click. Video textures make no mipmaps (they would be remade
@@ -445,6 +491,210 @@ on top, as with UVs (animate `offset` to scroll a pattern). 0 (the default) uses
 { bumpMap: pores, bumpScale: 0.0005, roughnessMap: sheen, triplanar: 45 }   // bone texture on a scanned skull
 ```
 
+**Shader hooks** - a few lines of GLSL of your own, run at fixed points inside phoria2's shader, for
+what the material options can't say: waves, wind, dissolves, scanlines, glows, colour by height. You
+write statements, not a shader: lighting, shadows, fog, clipping, picking and outlines keep working -
+a waving flag casts a waving shadow and is picked where it is drawn. Meshes, instanced meshes, points
+and lines all take them, as `material.shader`:
+
+```js
+new Mesh({ geometry: plane({ width: 3, depth: 2, segments: 40 }), material: {
+  color: '#3a7bd5', doubleSided: true,
+  shader: {
+    uniforms: { uAmp: 0.25 },
+    vertex: 'local.y += sin(local.x * 3.0 + uTime * 3.0) * uAmp;',        // a wave, in the geometry's own space
+    fragment: 'base.rgb *= 0.8 + 0.2 * sin(vWorldPosition.y * 20.0);',   // stripes, before lighting
+    lit: 'color += vec3(0.0, 0.1, 0.2) * (0.5 + 0.5 * sin(uTime));',     // a glow the light doesn't touch
+  },
+} })
+```
+
+Three hooks, each optional. What each can use (✎ = change it; everything else is read only):
+
+| | Mesh / InstancedMesh | Points | Lines |
+|---|---|---|---|
+| `vertex` - each vertex, before it is placed | ✎ `local` (vec3, own space), ✎ `n` (vec3 normal), `uv` (vec2), `index` (int: the instance) | ✎ `local`, ✎ `size` (float, times the material's), `index` (int: the point) | ✎ `local`, `along` (float: 0 at a segment's start, 1 at its end), `index` (int: the segment) - runs once per end, so a segment moves but stays straight |
+| `fragment` - each pixel, before lighting | ✎ `base` (vec4: linear colour, alpha), ✎ `emissive` (vec3), ✎ `normal` (vec3: the shading normal, world space, facing the viewer - bend it for relief lit per pixel), `vUv`, `vWorldPosition`, `vNormal`, `vColor`; `discard` | ✎ `base`, `pointUv` (vec2, 0-1 across the point), `index` (int); `discard` | ✎ `base`, `distance` (float: along the line, in the geometry's units), `index` (int: the segment); `discard` |
+| `lit` - each pixel, after lighting | ✎ `color` (vec3, linear, lit), ✎ `base.a` | ✎ `color`, ✎ `base.a` | ✎ `color`, ✎ `base.a` |
+
+Every hook can also read `uTime` - the View's clock in seconds - and the uniforms you give, and
+call functions for randomness and texture without a texture (hooks can't define their own). `p`
+is a vec2 or vec3, and every result is 0 to 1:
+
+- `hash(x)` - from a float, vec2 or vec3's exact bits. The same on every GPU for the same bits, so hash
+  exact things - `hash(float(index))` gives each point, instance or segment its own random number,
+  `hash(floor(vUv * 20.0))` each cell of a grid. An interpolated value such as `vWorldPosition` can
+  differ in its last bits from GPU to GPU, and so can its hash.
+- `vnoise(p)` - value noise: random values at whole-number points, eased between. Cheapest; looks
+  blockier, its features lined up with the axes.
+- `snoise(p)` - simplex noise: smoother, rounder, no grid to see - the better choice for anything
+  natural. About one feature per unit of `p`: scale `p` up for finer detail, `snoise(vUv * 10.0)`,
+  `snoise(vec3(local.xz, uTime))` to change over time.
+- `snoised(p)` - simplex noise with its gradient: a vec3 (value, d/dx, d/dy) from a vec2, a vec4
+  from a vec3. The slope for a normal, with no extra samples.
+- `vfbm(p)`, `sfbm(p)` - fractal noise: octaves of value or simplex noise added up, each finer and
+  half as strong, each turned so their grids don't line up. Five octaves; `sfbm(p, 8)` for more
+  detail, fewer for softer and cheaper (1-12). Mostly 0.25-0.75 - the octaves average out.
+- `sfbmd(p)`, `sfbmd(p, octaves)` - simplex fbm with its gradient, as `snoised`: terrain normals.
+- `voronoi(p)` - cellular (Worley) noise: a random point in each unit cell of `p`. Returns a vec3 -
+  `x` the distance to the nearest point (F1), `y` to the second nearest (F2), both in cells, and `z` a
+  random 0-1 for the nearest point's cell. `y - x` is 0 on the edges between cells: cracks, cells,
+  scales, stone, crystals; `z` gives each cell its own colour or height. A vec3 `p` with time as one
+  axis makes the cells drift and re-form. Costs 9 cells (vec2) or 27 (vec3) - more than `snoise`.
+
+And the everyday ones, with `cameraPosition` (vec3, the camera in world space) to read too:
+
+- `srgb(c)` - a colour as picked (sRGB, as in a colour picker or CSS) to the linear colour hooks work
+  in: `base.rgb = srgb(vec3(0.75, 0.12, 0.16))` is the red you picked, not a pale pink.
+- `hsv2rgb(h, s, v)` (or a vec3) - hue, saturation and value 0-1 to a linear colour. Hue 0 red, 1/3
+  green, 2/3 blue, wrapping: `hsv2rgb(fract(vWorldPosition.y * 0.2 - uTime * 0.1), 0.8, 1.0)`.
+- `palette(t, a, b, c, d)` - Inigo Quilez's cosine palette, `a + b cos(2pi(c t + d))`, its four
+  vec3s as picked, the result linear. `palette(t, vec3(0.5), vec3(0.5), vec3(1.0), vec3(0.0, 0.33,
+  0.67))` is a rainbow; other a-d give heat, ocean, pastel ramps.
+- `fresnel(normal, position, power)` - how side-on a surface is to the camera, 0 facing it, 1 edge-on,
+  sharpened by the power: rim light, holograms, force fields, `fresnel(vNormal, vWorldPosition, 3.0)`.
+- `rotate2(angle)` - a mat2 turning anticlockwise: `rotate2(a) * v`. `rotate3(axis, angle)` - a mat3
+  turning about an axis. Twists, spins, turned uvs or noise.
+- `remap(x, inMin, inMax, outMin, outMax)` - from one range to another (not clamped; float, vec2 or
+  vec3 x). `saturate(x)` - clamped to 0-1, as HLSL has it.
+
+- **`uniforms`**, by GLSL name: a number (float), two to four numbers (vec2-vec4), a colour string or
+  Color (vec3, sent linear) or a Texture (sampler2D, read with `texture(uName, uv)`). Change one on
+  `material.shader.uniforms` (`mesh.material.shader.uniforms.uAmp = 0.5`) and the View redraws; assign
+  a new `material.shader` to change the code. Names starting `gl_` or `phoria`, `uTime`, and phoria2's
+  own uniforms (`uColor`, `uModel`, `uOpacity`...) are taken.
+- **`uTime`**: a hook that reads it keeps the View drawing while time runs - no frame loop of your own.
+  `view.stop()` freezes it.
+- **Every pass runs the vertex hook** - shadow maps, outlines, GPU picking. A mesh's `fragment`
+  `discard` cuts its shadow and its picking too, so a dissolve leaves no shadow of what has gone.
+- **`bounds`**: how far, in world units, the vertex hook can move a vertex. Bounds are padded by it for
+  culling, `view.frame()` and shadows; without it a vertex hook turns frustum culling off for the node.
+- **Picking** a node a vertex hook moves is always done on the GPU, so clicks, hovers and tooltips find
+  it where it is drawn (the hit has the point, not a normal or uv). `pickAll`, `pickArea` and
+  `Raycaster` work from the geometry as given, not as moved.
+- **A hook that doesn't compile** is reported once, by its own line numbers - `shader.vertex line 2:
+  'wobble' : undeclared identifier` - with the names it can use, and the material is drawn without its
+  hooks. `view.explain()` lists the hooked materials.
+
+Recipes - each a material option to copy:
+
+```js
+// bumps lit per pixel from any height: bend the shading normal by its slope - crisp at any mesh
+// resolution, no vertices moved (here a surface facing up, its uvs along x and z)
+shader: { fragment: `
+  vec2 q = vUv * 20.0;
+  float e = 0.01, h = sfbm(q, 4);
+  vec2 slope = vec2(sfbm(q + vec2(e, 0.0), 4) - h, sfbm(q + vec2(0.0, e), 4) - h) / e;
+  normal = normalize(normal - vec3(slope.x, 0.0, slope.y) * 0.05);` }
+
+// a wave with its normal bent to match, so the light follows the folds (a plane, a flag, a sheet)
+shader: { uniforms: { uAmp: 0.2 }, vertex: `
+  float phase = local.x * 3.0 - uTime * 4.0;
+  local.y += sin(phase) * uAmp;
+  n = normalize(vec3(-cos(phase) * 3.0 * uAmp, 1.0, 0.0));` }
+
+// ripples spreading from the middle of a plane (give it segments: 64 or so)
+shader: { vertex: `
+  float r = length(local.xz), phase = r * 6.0 - uTime * 3.0, h = 0.04 * exp(-r * 0.4);
+  local.y += sin(phase) * h;
+  vec2 slope = local.xz / max(r, 1e-3) * cos(phase) * 6.0 * h;
+  n = normalize(vec3(-slope.x, 1.0, -slope.y));` }
+
+// breathing: grow and shrink about the middle
+shader: { vertex: 'local *= 1.0 + 0.06 * sin(uTime * 2.0);' }
+
+// dissolve through fractal noise, its edge glowing (its shadow dissolves too)
+shader: { fragment: `
+  float level = 0.5 - 0.55 * cos(uTime * 0.6);
+  float v = sfbm(vUv * vec2(10.0, 3.0));
+  if (v < level) discard;
+  emissive += vec3(1.0, 0.2, 0.02) * smoothstep(level + 0.05, level, v) * 5.0;` }
+
+// terrain from simplex fbm, its normal from the same call's gradient (a plane with segments: 128
+// or so); the octaves set how rugged - 3 rolling hills, 8 craggy
+shader: { uniforms: { uOctaves: 7 }, vertex: `
+  vec3 h = sfbmd(local.xz * 0.4, int(uOctaves));
+  local.y += h.x * 2.0;
+  n = normalize(vec3(-h.y * 2.0 * 0.4, 1.0, -h.z * 2.0 * 0.4));` }
+
+// a texture uniform: scroll a noise or pattern image across a surface
+shader: { uniforms: { uPattern: patternTexture }, fragment: 'base.rgb *= texture(uPattern, vUv * 4.0 + vec2(uTime * 0.1, 0.0)).rgb;' }
+
+// colour by height - a ramp from deep blue at y = 0 to orange at y = 2
+shader: { fragment: 'base.rgb = mix(vec3(0.01, 0.05, 0.5), vec3(1.0, 0.25, 0.0), clamp(vWorldPosition.y / 2.0, 0.0, 1.0));' }
+
+// rim glow: a hologram or force field - a faint body, bright where it turns away (with
+// transparent: true)
+shader: {
+  fragment: 'base.rgb = srgb(vec3(0.25, 0.9, 1.0)) * 0.15; emissive += srgb(vec3(0.25, 0.9, 1.0)) * fresnel(vNormal, vWorldPosition, 2.5) * 2.0;',
+  lit: 'base.a *= 0.3 + 0.7 * fresnel(vNormal, vWorldPosition, 1.5);',
+}
+
+// a twist: each height turned further round the y axis, its normal turned with it (give the mesh segments)
+shader: { vertex: 'mat2 turn = rotate2(local.y * 1.2 * sin(uTime)); local.xz = turn * local.xz; n.xz = turn * n.xz;' }
+
+// a hue climbing an object, and a cosine palette across another
+shader: { fragment: 'base.rgb = hsv2rgb(fract(vWorldPosition.y * 0.2 - uTime * 0.1), 0.75, 1.0);' }
+shader: { fragment: 'base.rgb = palette(vUv.x + uTime * 0.05, vec3(0.5), vec3(0.5), vec3(1.0), vec3(0.0, 0.33, 0.67));' }
+
+// instances as a meter: each bar's height from one sine, a phase apart by index, remapped and saturated
+shader: { vertex: 'float h = saturate(remap(sin(uTime * 2.0 + float(index) * 0.5), -1.0, 1.0, 0.05, 1.0)); local.y = (local.y + 0.5) * h - 0.5;' }
+
+// cracked lava: dark crust plates, each its own shade, molten in the cracks between them (time as
+// the third axis, so the plates drift and re-form)
+shader: { fragment: `
+  vec3 v = voronoi(vec3(vUv * 8.0, uTime * 0.2));
+  float crack = 1.0 - smoothstep(0.0, 0.12, v.y - v.x);
+  base.rgb = srgb(vec3(0.16, 0.12, 0.11)) * (0.5 + 0.9 * v.z);
+  emissive += vec3(1.0, 0.25, 0.0) * crack * 4.0;` }
+
+// stained glass: each cell a random hue, dark leading between them
+shader: { fragment: 'vec3 v = voronoi(vUv * 6.0); base.rgb = hsv2rgb(v.z, 0.7, 1.0) * smoothstep(0.02, 0.06, v.y - v.x);' }
+
+// scanlines over the lit picture
+shader: { lit: 'color *= 0.75 + 0.25 * step(0.5, fract(vWorldPosition.y * 20.0 - uTime));' }
+
+// fade with distance from a point (with transparent: true on the material)
+shader: { uniforms: { uCentre: [0, 0, 0] }, lit: 'base.a *= 1.0 - smoothstep(2.0, 4.0, distance(vWorldPosition, uCentre));' }
+
+// points: twinkling, each at its own rate, and soft and round
+shader: {
+  vertex: 'size *= 1.0 + 0.6 * sin(uTime * (1.5 + hash(float(index)) * 3.0) + float(index));',
+  fragment: 'base.a *= smoothstep(1.0, 0.0, length(pointUv * 2.0 - 1.0));',
+}
+
+// lines: pulses running along them (distance is along each run of joined segments), each line's
+// at its own time
+shader: { fragment: 'base.rgb += vec3(0.3, 0.9, 1.0) * smoothstep(0.85, 1.0, fract(distance * 0.6 - uTime + hash(float(index)))) * 4.0;' }
+```
+
+Mistakes to avoid:
+
+- **Colours are linear**, as the shader works, so an sRGB-looking value comes out pale. Wrap a colour
+  as picked in `srgb()` - `srgb(vec3(0.75, 0.12, 0.16))` - or write linear values, roughly the sRGB
+  value squared: orange `vec3(1.0, 0.22, 0.0)`. `hsv2rgb` and `palette` give linear colour already,
+  and colour uniforms given as strings are converted for you.
+- **Hooks are statements**, run inside phoria2's `main()`: no functions of your own, no `uniform`
+  declarations (use `uniforms`), no `return` in a mesh or points hook. Declare locals as you like.
+  `hash`, the noises and the fbms are there for what you'd otherwise write a function for.
+- **Randomness from `hash()`, not `fract(sin(x) * 43758.5453)`**: the sin trick multiplies a GPU's
+  last bits of `sin` into the answer, so the same scene comes out differently on different GPUs.
+  `hash` is integer arithmetic, exact everywhere.
+- **`index` is an int**: `float(index)` to do sums with it.
+- **Bend the normal when you move vertices**, or the light shades the shape as it was: change `n`
+  (meshes) to match, and keep it normalised. Waves on a flat plane need `segments` to bend at all.
+- **Fine relief belongs in the fragment hook**: moving vertices can only be as sharp as the mesh's
+  resolution - a steep step (cracks, tiles, grooves) becomes a staircase between them. Bend `normal`
+  in the fragment hook instead, lit per pixel, and keep any vertex movement gentle.
+- **Fades need `transparent: true`**: changing `base.a` in an opaque material changes nothing.
+  `discard` works either way.
+- **Move in the geometry's own space**: `local` is before the node's position, rotation and scale (and
+  an instance's), so a wave along `local.y` turns with the mesh.
+- **Use `vWorldPosition`** for effects fixed in the world - a band at a height, a fade round a point -
+  and `vUv` for ones fixed to the surface.
+- **Lines move by their ends**: a straight segment stays straight - give the geometry more segments to
+  bend a line.
+
 ## Lights and cameras
 
 | | Options |
@@ -537,6 +787,16 @@ view.on('hover', (hit) => show(hit?.datum))                 // fires when the th
 - The **nearest surface** under the pointer is the hit - a link drawn over a site's top wins the
   hover there. To let one kind of thing through, give it `pickable: false`; to choose among
   everything under the pointer, `view.pickAll(event)` lists every hit, nearest first.
+- **Selecting an area** - `view.pickArea({ x, y, width, height })` (width and height may be negative,
+  as a drag up or left makes them) or `view.pickArea([[x, y], ...])` for a lasso: a hit for each point,
+  instance and line segment whose place on screen is inside, and each mesh whose middle is. Places, not
+  surfaces: what is hidden behind other things is found too, so a box over a scatter takes that whole
+  region. Hidden, unpickable and zero-scale instances are left out. Turn `view.controls.enabled` off
+  while the user drags out the area.
+
+  ```js
+  const chosen = view.pickArea({ x: 40, y: 30, width: 200, height: 120 }).map((h) => h.datum)
+  ```
 - **Rays of your own** - line of sight, what's below a dropped object, picking in tests: a
   `Raycaster` finds what any ray hits, on the CPU. Set `raycaster.ray.origin` and `.direction`, or aim
   it with `setFromCamera([x, y], camera)` (-1 to 1, y up); `intersect(nodeOrNodes)` returns hits,
@@ -807,6 +1067,20 @@ second), `follow` (a node whose position is the origin each frame - a trail), `o
 default material is small additive points. `burst(count, spawnOptions)`, `clear()`, `set(options)`,
 `count`.
 
+How particles look over their lives: `size` (a multiple of the material's size, or a list each particle
+goes through - `[0.5, 3]` billows), `sizeSpread` (each one's size varies by up to this share, 0-1),
+`opacity` (0-1, or a list - `[0, 1, 0]` fades in and out) and `spin` (radians per second: a number
+either way, or `[min, max]`; spinning particles start at a random angle). For smoke, a soft `map`,
+`blending: 'normal'` and `sort: true`:
+
+```js
+const smoke = view.scene.add(new Emitter({
+  rate: 40, velocity: [0, 1.5, 0], velocitySpread: 0.4, lifetime: [3, 5], color: ['#777', '#333'],
+  size: [0.6, 4], sizeSpread: 0.3, opacity: [0, 0.6, 0], spin: 0.5, sort: true,
+  material: { map: puff, size: 1, blending: 'normal' },
+}))
+```
+
 `Body` moves any node: `node.onUpdate(new Body({ velocity, gravity, drag }).update)`;
 `body.impulse([x, y, z])` kicks it.
 

package/llms.txt

@@ -11,7 +11,7 @@ why a page might look wrong. Coordinates are +Y up, in metres; angles in radians
 
 ## Docs
 
-- [Full reference](https://kevs3d.co.uk/phoria2/llms-full.txt): the whole API in one page - View, scene graph, drawables, geometry, materials, lights, interaction and dragging, charts, editing, models, motion, particles, plain-data scenes
+- [Full reference](https://kevs3d.co.uk/phoria2/llms-full.txt): the whole API in one page - View, scene graph, drawables, geometry, materials (and shader hooks: GLSL of your own inside the material - waves, dissolves, glows), lights, interaction and dragging, charts, editing, models, motion, particles, plain-data scenes
 - [README](https://github.com/kevinroast/phoria2#readme): install, CDN use, the entry points
 - Source: the package ships its readable, commented source in `node_modules/phoria2/src` - read that, not the minified `dist/`, for anything the reference doesn't settle
 - [Chart spec JSON Schema](https://cdn.jsdelivr.net/npm/phoria2/schema/chart.schema.json): the spec `chart()` takes, as `phoria2/charts/schema.json` in the package

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phoria2",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Small, friendly 3D for the web - a WebGL 2 renderer with charts, labels, picking, particles and glTF",
   "keywords": [
     "3d",

package/schema/scene.schema.json

@@ -102,6 +102,10 @@
           "properties": {
             "type": {
               "const": "points"
+            },
+            "sort": {
+              "type": "boolean",
+              "description": "Draw the points furthest first each frame, for soft points that cover what is behind them."
             }
           },
           "unevaluatedProperties": false
@@ -113,6 +117,15 @@
           "properties": {
             "type": {
               "const": "lines"
+            },
+            "arrows": {
+              "enum": ["none", "start", "end", "both"],
+              "description": "Arrowheads at the ends of each chain of joined segments."
+            },
+            "arrowSize": {
+              "type": "number",
+              "description": "Arrowhead length in pixels; 0 sizes them from the material's width.",
+              "minimum": 0
             }
           },
           "unevaluatedProperties": false
@@ -916,6 +929,47 @@
           "description": "Lines: width in pixels.",
           "minimum": 0
         },
+        "dash": {
+          "type": "number",
+          "description": "Lines: dashed, with dashes this long in the model's units; 0 is solid.",
+          "minimum": 0
+        },
+        "gap": {
+          "type": "number",
+          "description": "Lines: the gaps between dashes; 0 is as long as the dashes.",
+          "minimum": 0
+        },
+        "dashOffset": {
+          "type": "number",
+          "description": "Lines: moves the dashes along the lines - animate it for flow."
+        },
+        "shader": {
+          "type": "object",
+          "description": "GLSL hooks run inside phoria2's own shader: vertex (change local, and n on meshes), fragment (change base and emissive before lighting; discard cuts) and lit (change color after lighting). Every hook can read uTime.",
+          "additionalProperties": false,
+          "properties": {
+            "vertex": { "type": "string" },
+            "fragment": { "type": "string" },
+            "lit": { "type": "string" },
+            "uniforms": {
+              "type": "object",
+              "description": "Values the hooks read, by GLSL name: a number, two to four numbers, a colour string, or a texture description.",
+              "additionalProperties": {
+                "anyOf": [
+                  { "type": "number" },
+                  { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 4 },
+                  { "type": "string" },
+                  { "type": "object", "required": ["url"] }
+                ]
+              }
+            },
+            "bounds": {
+              "type": "number",
+              "minimum": 0,
+              "description": "How far, in world units, the vertex hook can move a vertex; without it a vertex hook turns frustum culling off."
+            }
+          }
+        },
         "alphaTest": {
           "type": "number",
           "description": "Cut-outs: drop pixels with less alpha.",
@@ -1280,6 +1334,27 @@
                 "type": "number"
               }
             },
+            "sizes": {
+              "type": "array",
+              "description": "Points: one per vertex, a multiple of the material's size.",
+              "items": {
+                "type": "number"
+              }
+            },
+            "opacities": {
+              "type": "array",
+              "description": "Points: one per vertex, 0-1, times the material's opacity.",
+              "items": {
+                "type": "number"
+              }
+            },
+            "angles": {
+              "type": "array",
+              "description": "Points: one per vertex, radians anticlockwise on screen.",
+              "items": {
+                "type": "number"
+              }
+            },
             "indices": {
               "type": "array",
               "items": {