@opsydyn/effect-three 0.3.0 → 0.6.4

package/src/runtime/SceneSchema.ts

@@ -202,6 +202,7 @@ export const BasicMaterial = Schema.TaggedStruct('Basic', {
   color: Rgb,
   map: TextureId,
   ...surface,
+  depthTest: Schema.Boolean.pipe(Schema.withDecodingDefaultKey(Effect.succeed(true))),
 });
 
 /** Matte material parameters. */
@@ -378,6 +379,21 @@ export const JointKind = Schema.Union([
   }),
 ]);
 
+/** A trail behind a moving node (Drei's `Trail`). */
+export const Trail = absentAsNull(
+  Schema.Struct({
+    width: NonNegative,
+    length: NonNegative,
+    decay: NonNegative,
+    local: Schema.Boolean,
+    stride: NonNegative,
+    interval: NonNegative,
+    color: Rgb,
+    taper: Schema.Literals(['none', 'linear', 'quadratic']),
+    fade: Schema.Boolean,
+  }),
+);
+
 /** A joint between two bodies. */
 export const Joint = Schema.Struct({
   key: Schema.String,
@@ -389,11 +405,19 @@ export const Joint = Schema.Struct({
   contacts: Schema.Boolean,
 });
 
+/** A count of physics steps. */
+const StepCount = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+
 export const Physics = Schema.Struct({
   gravity: Vec3,
   paused: Schema.Boolean,
   timeStep: Positive,
   interpolate: Schema.Boolean,
+  until: absentAsNull(StepCount),
+  run: Schema.Int.pipe(Schema.withDecodingDefaultKey(Effect.succeed(0))),
+  snapshotAt: absentAsNull(StepCount),
+  from: absentAsNull(Schema.Struct({ step: StepCount, snapshot: Schema.NullOr(Schema.String) })),
+  keep: StepCount.pipe(Schema.withDecodingDefaultKey(Effect.succeed(0))),
   debug: Schema.Boolean,
   joints: Schema.Array(Joint),
 });
@@ -411,6 +435,20 @@ export const MeshNode = Schema.TaggedStruct('Mesh', {
   castShadow: Schema.Boolean,
   receiveShadow: Schema.Boolean,
   body: Schema.NullOr(Body),
+  edges: absentAsNull(
+    Schema.Struct({
+      threshold: NonNegative,
+      color: Rgb,
+      width: NonNegative,
+      worldUnits: Schema.Boolean,
+      dashed: Schema.Boolean,
+      dashSize: NonNegative,
+      gapSize: NonNegative,
+      opacity: NonNegative,
+      transparent: Schema.Boolean,
+    }),
+  ),
+  trail: Trail,
 });
 
 /** One instance of an instances node. */
@@ -593,6 +631,76 @@ export const HemisphereLightNode = Schema.TaggedStruct('HemisphereLight', {
   position: Vec3,
 });
 
+/** What points look like: dots, Drei's sparkles, or its stars. */
+export const PointLook = Schema.Union([
+  Schema.TaggedStruct('Dots', {
+    positions: Schema.Array(Vec3),
+    colors: Schema.NullOr(Schema.Array(Rgb)),
+    sizes: Schema.NullOr(Schema.Array(NonNegative)),
+    color: Rgb,
+    size: NonNegative,
+    sizeAttenuation: Schema.Boolean,
+    round: Schema.Boolean,
+    opacity: NonNegative,
+    transparent: Schema.Boolean,
+  }),
+  Schema.TaggedStruct('Sparkles', {
+    count: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    speed: Schema.Finite,
+    opacity: NonNegative,
+    scale: Vec3,
+    size: Schema.NullOr(NonNegative),
+    color: Rgb,
+    noise: Vec3,
+    seed: Schema.Finite,
+  }),
+  Schema.TaggedStruct('Stars', {
+    radius: NonNegative,
+    depth: NonNegative,
+    count: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    factor: NonNegative,
+    saturation: NonNegative,
+    fade: Schema.Boolean,
+    speed: Schema.Finite,
+    seed: Schema.Finite,
+  }),
+]);
+
+/** Points (Drei's `Points`, `Sparkles` or `Stars`), drawn by the render kit. */
+export const PointsNode = Schema.TaggedStruct('Points', {
+  key: Schema.String,
+  position: Vec3,
+  rotation: Rotation,
+  scale: Vec3,
+  transition: Transition,
+  behaviour: Schema.NullOr(Behave),
+  look: PointLook,
+});
+
+/** A line through points (Drei's `Line`), drawn by the render kit. */
+export const LineNode = Schema.TaggedStruct('Line', {
+  key: Schema.String,
+  position: Vec3,
+  rotation: Rotation,
+  scale: Vec3,
+  transition: Transition,
+  behaviour: Schema.NullOr(Behave),
+  interactive: Schema.Boolean,
+  points: Schema.Array(Vec3),
+  segments: Schema.Boolean,
+  color: Rgb,
+  vertexColors: Schema.NullOr(Schema.Array(Rgb)),
+  width: NonNegative,
+  worldUnits: Schema.Boolean,
+  dashed: Schema.Boolean,
+  dashSize: NonNegative,
+  gapSize: NonNegative,
+  dashScale: NonNegative,
+  dashOffset: Schema.Finite,
+  opacity: NonNegative,
+  transparent: Schema.Boolean,
+});
+
 /** Any scene node. Groups nest recursively. */
 export const SceneNode: Schema.Codec<KernelSceneNode, unknown> = Schema.Union([
   Schema.TaggedStruct('Group', {
@@ -609,11 +717,14 @@ export const SceneNode: Schema.Codec<KernelSceneNode, unknown> = Schema.Union([
     detail: absentAsNull(
       Schema.Struct({ distances: Schema.Array(NonNegative), hysteresis: NonNegative }),
     ),
+    trail: Trail,
   }),
   MeshNode,
   InstancesNode,
   BorrowedNode,
   LabelNode,
+  LineNode,
+  PointsNode,
   ShaderGridNode,
   AmbientLightNode,
   DirectionalLightNode,
@@ -715,6 +826,26 @@ export const RenderTexture = Schema.Struct({
   children: Schema.Array(SceneNode),
 });
 
+/** Where a HUD's origin sits on the canvas. */
+export const HudAlignment = Schema.Literals([
+  'top-left',
+  'top-center',
+  'top-right',
+  'center-left',
+  'center-center',
+  'center-right',
+  'bottom-left',
+  'bottom-center',
+  'bottom-right',
+]);
+
+/** Nodes drawn over the scene, with their own camera in CSS pixels. */
+export const Hud = Schema.Struct({
+  alignment: HudAlignment,
+  margin: Schema.Tuple([Schema.Finite, Schema.Finite]),
+  children: Schema.Array(SceneNode),
+});
+
 /** A complete scene description. */
 /** A point to show HTML at. */
 export const Overlay = Schema.Struct({
@@ -789,11 +920,23 @@ export const Xr = Schema.Struct({
 /** Whether the scene claims the pointer's gestures from the page. */
 export const Gestures = Schema.Literals(['page', 'scene']);
 
+/** What an asset is: a glTF or GLB model, a colour texture, an HDR panorama, a typeface font. */
+export const AssetKind = Schema.Literals(['model', 'texture', 'environment', 'font']);
+
+/** An asset a scene asks for (`modelAsset` and the rest). */
+export const Asset = Schema.Struct({
+  kind: AssetKind,
+  id: Schema.String,
+  url: Schema.String,
+  levels: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+});
+
 export const SceneDescription = Schema.Struct({
   camera: Camera,
   gestures: Gestures,
   views: Schema.Array(View),
   renderTextures: Schema.Array(RenderTexture),
+  hud: absentAsNull(Hud),
   overlays: Schema.Array(Overlay),
   environment: Schema.NullOr(Environment),
   sky: Schema.NullOr(Sky),
@@ -801,11 +944,42 @@ export const SceneDescription = Schema.Struct({
   physics: Schema.NullOr(Physics),
   xr: Schema.NullOr(Xr),
   measure: Schema.Array(Schema.String),
+  assets: Schema.Array(Asset).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
   render: RenderSettings,
   resources: ResourceDefinitions,
   children: Schema.Array(SceneNode),
 });
 
+/**
+ * Detail of asset loaded events: the asset, the level of detail now shown (0 for the
+ * coarsest of its `levels`, as many as it has levels for `url` itself) and whether that is
+ * the finest, and for a model its parts and clips.
+ */
+export const AssetLoadedDetail = Schema.Struct({
+  kind: AssetKind,
+  id: Schema.String,
+  url: Schema.String,
+  levels: Schema.Array(Schema.String),
+  level: Schema.Int,
+  final: Schema.Boolean,
+  /** Names of the objects inside a model, as hits report them in `part`. */
+  parts: Schema.Array(Schema.String),
+  /** Names of a model's animation clips. */
+  clips: Schema.Array(Schema.String),
+});
+
+/**
+ * Detail of asset failed events: the asset, and why its finest level could not be loaded
+ * (a coarser level shown before stays).
+ */
+export const AssetFailedDetail = Schema.Struct({
+  kind: AssetKind,
+  id: Schema.String,
+  url: Schema.String,
+  levels: Schema.Array(Schema.String),
+  reason: Schema.String,
+});
+
 /** Detail of pointer-leave events: the interactive mesh's key. */
 export const KeyDetail = Schema.Struct({ key: Schema.String });
 
@@ -906,6 +1080,17 @@ export const CollisionDetail = Schema.Struct({
   started: Schema.Boolean,
 });
 
+/**
+ * Detail of physics reached events: the run and step a world on `physics({ until })`
+ * reached, a checksum of its bodies' poses there, and at `snapshotAt` a snapshot of it.
+ */
+export const PhysicsReachedDetail = Schema.Struct({
+  run: Schema.Int,
+  step: StepCount,
+  checksum: Schema.String,
+  snapshot: Schema.optionalKey(Schema.String),
+});
+
 const XrHand = Schema.Literals(['left', 'right', 'none']);
 
 /** Detail of XR stick events: a thumbstick pushed past halfway, or let back. */
@@ -986,6 +1171,14 @@ export const AutoRotatedDetail = Schema.Struct({
 /** Detail of gesture events. */
 export const GestureDetail = Schema.Struct({ gesture: Gesture });
 
+/** Detail of the end of a gesture that moved: the press's button, modifiers, mesh and view. */
+export const GestureEndDetail = Schema.Struct({
+  button: Schema.Int,
+  modifiers: Modifiers,
+  key: Schema.optionalKey(Schema.String),
+  view: Schema.optionalKey(Schema.String),
+});
+
 /** A pointer interaction with an interactive mesh, or a miss. */
 export const SceneEvent = Schema.Union([
   Schema.TaggedStruct('PointerEnter', HitDetail.fields),
@@ -1001,11 +1194,13 @@ export const SceneEvent = Schema.Union([
   Schema.TaggedStruct('Drag', DragDetail.fields),
   Schema.TaggedStruct('DragEnd', DragDetail.fields),
   Schema.TaggedStruct('Gesture', GestureDetail.fields),
+  Schema.TaggedStruct('GestureEnd', GestureEndDetail.fields),
   Schema.TaggedStruct('AutoRotated', AutoRotatedDetail.fields),
   Schema.TaggedStruct('Collision', CollisionDetail.fields),
   Schema.TaggedStruct('Measured', MeasuredDetail.fields),
   Schema.TaggedStruct('LabelMeasured', LabelMeasuredDetail.fields),
   Schema.TaggedStruct('ContactForce', ContactForceDetail.fields),
+  Schema.TaggedStruct('PhysicsReached', PhysicsReachedDetail.fields),
   Schema.TaggedStruct('XrStick', XrStickDetail.fields),
   Schema.TaggedStruct('XrButton', XrButtonDetail.fields),
   Schema.TaggedStruct('XrSurface', XrSurfaceDetail.fields),
@@ -1031,7 +1226,131 @@ export const DescriptionError = Schema.Union([
   Schema.TaggedStruct('UnknownOverlayNode', { key: Schema.String, node: Schema.String }),
   Schema.TaggedStruct('UnknownOverlayView', { key: Schema.String, view: Schema.String }),
   Schema.TaggedStruct('UnknownMeasuredNode', { key: Schema.String }),
+  Schema.TaggedStruct('DuplicateAssetId', { id: Schema.String }),
   Schema.TaggedStruct('DuplicateJointKey', { key: Schema.String }),
   Schema.TaggedStruct('UnknownJointBody', { joint: Schema.String, body: Schema.String }),
   Schema.TaggedStruct('DuplicateRenderTextureId', { id: Schema.String }),
 ]);
+
+/** Where an object is, for a transform gizmo: position, Euler angles and scale. */
+export const Placement = Schema.Struct({ position: Vec3, rotation: Vec3, scale: Vec3 });
+
+const GizmoHandle = Schema.Literals(['x', 'y', 'z', 'xy', 'yz', 'xz', 'xyz']);
+
+/** A transform gizmo's state, for keeping in a Model. */
+export const Gizmo = Schema.Struct({
+  mode: Schema.Literals(['translate', 'rotate', 'scale']),
+  space: Schema.Literals(['world', 'local']),
+  size: Positive,
+  translationSnap: Schema.NullOr(Positive),
+  rotationSnap: Schema.NullOr(Positive),
+  scaleSnap: Schema.NullOr(Positive),
+  showX: Schema.Boolean,
+  showY: Schema.Boolean,
+  showZ: Schema.Boolean,
+  hovered: Schema.NullOr(GizmoHandle),
+  grab: Schema.NullOr(
+    Schema.Struct({
+      handle: GizmoHandle,
+      start: Placement,
+      from: Vec3,
+      plane: Schema.Struct({ normal: Vec3, constant: Schema.Finite }),
+      eye: Vec3,
+      distance: Schema.Finite,
+    }),
+  ),
+});
+
+/** A branching history of `value`s (`History.make`), for a Model that keeps one. */
+export const History = <S extends Schema.Top>(value: S) =>
+  Schema.Struct({
+    entries: Schema.Array(
+      Schema.Struct({
+        id: Schema.Int,
+        parent: Schema.NullOr(Schema.Int),
+        label: Schema.String,
+        value,
+        next: Schema.NullOr(Schema.Int),
+      }),
+    ),
+    current: Schema.Int,
+  });
+
+/** A lockstep entry: an app's input, or the leader admitting a peer. */
+const LockstepEntry = <S extends Schema.Top>(input: S) =>
+  Schema.Union([
+    Schema.TaggedStruct('Input', { input }),
+    Schema.TaggedStruct('Admit', { peer: Schema.String }),
+  ]);
+
+/** One peer's lockstep packet for one turn, carrying the app's `input`s. */
+export const LockstepPacket = <S extends Schema.Top>(input: S) =>
+  Schema.Struct({
+    peer: Schema.String,
+    turn: Schema.Int,
+    entries: Schema.Array(LockstepEntry(input)),
+  });
+
+/** A lockstep member: the first turn it sends for, and the turn it stopped before. */
+export const LockstepMember = Schema.Struct({
+  peer: Schema.String,
+  from: Schema.Int,
+  until: Schema.NullOr(Schema.Int),
+});
+
+/** A lockstep session (`Lockstep.make`) over the app's `input`s, for a Model. */
+export const Lockstep = <S extends Schema.Top>(input: S) =>
+  Schema.Struct({
+    self: Schema.String,
+    members: Schema.Array(LockstepMember),
+    turn: Schema.Int,
+    sent: Schema.Int,
+    lead: Schema.Int,
+    pending: Schema.Array(LockstepEntry(input)),
+    received: Schema.Array(LockstepPacket(input)),
+  });
+
+/** A timeline of physics steps (`Timeline.make`) over the app's `input`s, for a Model. */
+export const Timeline = <S extends Schema.Top>(input: S) =>
+  Schema.Struct({
+    inputs: Schema.Array(Schema.Struct({ step: StepCount, input })),
+    applied: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    reached: Schema.NullOr(StepCount),
+    frontier: StepCount,
+  });
+
+/** A measuring tape as data (`tape`), for a Model that keeps it. */
+export const Tape = Schema.Struct({
+  from: Schema.NullOr(Vec3),
+  to: Schema.NullOr(Vec3),
+  pointer: Schema.NullOr(Vec3),
+  snap: Schema.NullOr(Positive),
+});
+
+/** A pivot handle: what it does, and its axis. */
+export const PivotHandle = Schema.Literals(
+  (['arrow', 'slider', 'rotator', 'sphere'] as const).flatMap((kind) =>
+    (['x', 'y', 'z'] as const).map((axis) => `${kind}-${axis}` as const),
+  ),
+);
+
+/** Pivot controls as data (`pivot`), for a Model that keeps them. */
+export const Pivot = Schema.Struct({
+  scale: Positive,
+  depthTest: Schema.Boolean,
+  disableAxes: Schema.Boolean,
+  disableSliders: Schema.Boolean,
+  disableRotations: Schema.Boolean,
+  disableScaling: Schema.Boolean,
+  hovered: Schema.NullOr(PivotHandle),
+  grab: Schema.NullOr(
+    Schema.Struct({
+      handle: PivotHandle,
+      start: Placement,
+      point: Vec3,
+      e1: Vec3,
+      e2: Vec3,
+      normal: Vec3,
+    }),
+  ),
+});

package/src/runtime/errors.ts

@@ -12,6 +12,12 @@ export class InvalidScene extends Data.TaggedError('InvalidScene')<{
   readonly error: DescriptionError;
 }> {}
 
+/** A scene file could not be read: not JSON, not a scene file, or not a scene. */
+export class UnreadableScene extends Data.TaggedError('UnreadableScene')<{
+  /** Where and why, as the schema reports it. */
+  readonly issue: string;
+}> {}
+
 /** The renderer backend could not be created (for example, no WebGL2 context). */
 export class RendererUnavailable extends Data.TaggedError('RendererUnavailable')<{
   readonly cause: unknown;

package/src/runtime/index.ts

@@ -3,8 +3,10 @@
  *
  * @module
  */
-export { InvalidScene, RendererUnavailable } from './errors.ts';
+export { InvalidScene, RendererUnavailable, UnreadableScene } from './errors.ts';
 export * as FrameSource from './FrameSource.ts';
+export * as Inspector from './Inspector.ts';
 export * as ResourceRegistry from './ResourceRegistry.ts';
+export * as SceneFile from './SceneFile.ts';
 export * as SceneRuntime from './SceneRuntime.ts';
 export * as SceneSchema from './SceneSchema.ts';

package/src/webgl/index.ts

@@ -8,6 +8,8 @@
  */
 import type { RenderKit } from '../kernel/renderKit.ts';
 import { createContactShadows } from './contactShadows.ts';
+import { hostLine } from './line.ts';
+import { hostPoints } from './points.ts';
 import { hostShaderGrid } from './shaderGrid.ts';
 import { hostSky } from './sky.ts';
 
@@ -15,5 +17,7 @@ export const webglKit: RenderKit = {
   shading: 'webgl',
   sky: hostSky,
   shaderGrid: hostShaderGrid,
+  line: hostLine,
+  points: hostPoints,
   contactShadows: createContactShadows,
 };

package/src/webgl/line.ts

@@ -0,0 +1,66 @@
+/**
+ * The WebGL kit's lines: three's fat lines (`Line2`, `LineSegments2` and `LineMaterial`,
+ * which Drei's `Line` takes from three-stdlib), which size themselves to the viewport
+ * before each draw.
+ *
+ * @module
+ */
+import { Group } from 'three';
+import { Line2 } from 'three/addons/lines/Line2.js';
+import { LineGeometry } from 'three/addons/lines/LineGeometry.js';
+import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
+import { LineSegments2 } from 'three/addons/lines/LineSegments2.js';
+import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
+
+import type { LineNode } from '../kernel/description.ts';
+import { drawable, fillLineGeometry } from '../kernel/lineGeometry.ts';
+import type { HostedLine } from '../kernel/renderKit.ts';
+
+/** The material's look from the description; vertex colours want white, as Drei sets. */
+const style = (material: LineMaterial, line: LineNode): void => {
+  material.color.setHex(line.vertexColors === null ? line.color : 0xffffff);
+  if (material.vertexColors !== (line.vertexColors !== null)) {
+    material.vertexColors = line.vertexColors !== null;
+    material.needsUpdate = true;
+  }
+  material.linewidth = line.width;
+  material.worldUnits = line.worldUnits;
+  material.dashed = line.dashed;
+  material.dashSize = line.dashSize;
+  material.gapSize = line.gapSize;
+  material.dashScale = line.dashScale;
+  material.dashOffset = line.dashOffset;
+  material.opacity = line.opacity;
+  material.transparent = line.transparent;
+};
+
+const draw = (line: LineNode, material: LineMaterial): LineSegments2 => {
+  const drawn = line.segments
+    ? new LineSegments2(fillLineGeometry(new LineSegmentsGeometry(), line), material)
+    : new Line2(fillLineGeometry(new LineGeometry(), line), material);
+  drawn.computeLineDistances();
+  drawn.visible = drawable(line);
+  return drawn;
+};
+
+export const hostLine = (first: LineNode): HostedLine => {
+  const object = new Group();
+  const material = new LineMaterial();
+  style(material, first);
+  let drawn = draw(first, material);
+  object.add(drawn);
+  return {
+    object,
+    update: (next) => {
+      style(material, next);
+      drawn.removeFromParent();
+      drawn.geometry.dispose();
+      drawn = draw(next, material);
+      object.add(drawn);
+    },
+    dispose: () => {
+      drawn.geometry.dispose();
+      material.dispose();
+    },
+  };
+};