@opsydyn/effect-three-foldkit 0.3.0 → 0.6.4

package/src/view.ts

@@ -44,11 +44,17 @@ export type DragDetail = typeof SceneSchema.DragDetail.Type;
  */
 export type Gesture = typeof SceneSchema.Gesture.Type;
 
+/** Detail of the end of a gesture that moved: the press's button, modifiers, mesh and view. */
+export type GestureEndDetail = typeof SceneSchema.GestureEndDetail.Type;
+
 /** Detail of collision events: the two bodies' keys, and whether they began touching. */
 export type CollisionDetail = typeof SceneSchema.CollisionDetail.Type;
 
 /** Detail of contact force events: the two bodies, and how hard they pushed. */
 export type ContactForceDetail = typeof SceneSchema.ContactForceDetail.Type;
+export type PhysicsReachedDetail = typeof SceneSchema.PhysicsReachedDetail.Type;
+export type AssetLoadedDetail = typeof SceneSchema.AssetLoadedDetail.Type;
+export type AssetFailedDetail = typeof SceneSchema.AssetFailedDetail.Type;
 
 /** Detail of measured events: a node's world bounding box. */
 export type MeasuredDetail = typeof SceneSchema.MeasuredDetail.Type;
@@ -119,6 +125,11 @@ export type ViewConfig<Message> = {
    * the camera stays in the Model.
    */
   readonly onGesture?: (gesture: Gesture) => Message;
+  /**
+   * A gesture that moved has ended (released, or the pointer left): finish what it drew,
+   * such as a `BoxSelect` box. Not after a press that never moved.
+   */
+  readonly onGestureEnd?: (detail: GestureEndDetail) => Message;
   /**
    * A gesture is about to begin on a camera turning by itself (`autoRotate`): keep where
    * it got to with `autoRotated(model.camera, detail)` (a view's camera when `view` names
@@ -136,6 +147,12 @@ export type ViewConfig<Message> = {
    * set the threshold high.
    */
   readonly onContactForce?: (detail: ContactForceDetail) => Message;
+  /**
+   * A world on `physics({ until })` reached that step and waits there, with its run and a
+   * checksum of its bodies' poses (ADR-014): the moment to apply the inputs due at that
+   * step and move `until` on. It follows the collisions of the steps that led there.
+   */
+  readonly onPhysicsReached?: (detail: PhysicsReachedDetail) => Message;
   /**
    * A node listed in the scene's `measure` has a new world bounding box (Drei's `Bounds`
    * measuring, as a Message): fit the camera to it with `fitCamera`.
@@ -189,6 +206,13 @@ export type ViewConfig<Message> = {
   readonly onPerformanceChange?: (detail: PerformanceDetail) => Message;
   /** A scene update was rejected; the scene keeps its last good state. */
   readonly onError?: (detail: { readonly error: SceneError }) => Message;
+  /**
+   * An asset the scene asks for (`scene({ assets })`) has loaded and is lent under its id:
+   * at once, for one another scene loaded already. A model's parts and clips come with it.
+   */
+  readonly onAssetLoaded?: (detail: AssetLoadedDetail) => Message;
+  /** An asset the scene asks for could not be loaded, and why. */
+  readonly onAssetFailed?: (detail: AssetFailedDetail) => Message;
   /**
    * What each scene update did (operations by kind) and the GPU resources held afterwards.
    * Fires at startup and after every update that changed something, never for no-ops.
@@ -226,6 +250,7 @@ export const view = <Message>(
     Option.map(given(config.onDragEnd), element.OnSceneDragEnd),
     Option.map(given(config.onCollision), element.OnSceneCollision),
     Option.map(given(config.onContactForce), element.OnSceneContactForce),
+    Option.map(given(config.onPhysicsReached), element.OnScenePhysicsReached),
     Option.map(given(config.onMeasured), element.OnSceneMeasured),
     Option.map(given(config.onLabelMeasured), element.OnSceneLabelMeasured),
     Option.map(given(config.onXRSession), element.OnSceneXr),
@@ -239,8 +264,11 @@ export const view = <Message>(
     Option.map(given(config.onGesture), (toMessage) =>
       element.OnSceneGesture((detail) => toMessage(detail.gesture)),
     ),
+    Option.map(given(config.onGestureEnd), element.OnSceneGestureEnd),
     Option.map(given(config.onPerformanceChange), element.OnScenePerformance),
     Option.map(given(config.onError), element.OnSceneError),
+    Option.map(given(config.onAssetLoaded), element.OnSceneAssetLoaded),
+    Option.map(given(config.onAssetFailed), element.OnSceneAssetFailed),
     Option.map(given(config.onReconciled), element.OnSceneReconciled),
     Option.map(given(config.className), h.Class),
   ]);

package/src/viewportGizmo.ts

@@ -0,0 +1,119 @@
+/**
+ * A viewport gizmo as a Foldkit submodel (roadmap, "Beyond parity" 5), after Drei's
+ * `GizmoHelper` with `GizmoViewport`: the core's `viewportGizmoNodes` in a scene's
+ * `hud`, its heads highlighted under the pointer, and a press on one turning the camera
+ * to look from that axis. The parent owns the camera; the submodel owns the highlight:
+ *
+ * - `Entered` and `Left` (the scene's pointer enter and leave, with the hit key)
+ *   highlight a head, and clear it;
+ * - `Pressed` (a pointer down, with the hit key and the camera) reports
+ *   `Turned { camera }`, the camera looking from that head's axis, for the parent to
+ *   keep. A camera with `damping` eases round to it, as Drei's tween does.
+ *
+ * `hud(model, camera)` is the scene's HUD with the gizmo in it; `nodes` the gizmo alone,
+ * for a HUD with more in it.
+ *
+ * @module
+ */
+import {
+  type Camera,
+  cameraAlong,
+  hud as describeHud,
+  type Hud,
+  type HudAlignment,
+  SceneSchema,
+  type SceneNode,
+  type ViewAxis,
+  viewportAxisOf,
+  viewportGizmoNodes,
+} from '@opsydyn/effect-three';
+import { Option, Schema } from 'effect';
+import { defineMessageUnion } from 'foldkit/message';
+import type { ReturnWithOutMessage } from 'foldkit/update';
+
+const Axis = Schema.Literals(['x', 'y', 'z', '-x', '-y', '-z']);
+
+export const Model = Schema.Struct({
+  /** The key its nodes are drawn under: `${key}:x`, `${key}:-y` and so on. */
+  key: Schema.String,
+  /** The head under the pointer. */
+  hovered: Schema.NullOr(Axis),
+  /** Leaves out the negative heads. */
+  hideNegativeAxes: Schema.Boolean,
+});
+export type Model = typeof Model.Type;
+
+export const Message = defineMessageUnion({
+  Entered: { key: Schema.String },
+  Left: { key: Schema.String },
+  Pressed: { key: Schema.String, camera: SceneSchema.Camera },
+});
+export type Message = typeof Message.Type;
+
+export const OutMessage = defineMessageUnion({
+  /** The camera, looking from the axis of the head pressed. */
+  Turned: { camera: SceneSchema.Camera },
+});
+export type OutMessage = typeof OutMessage.Type;
+
+/** A gizmo drawn under `key`, every head shown unless `hideNegativeAxes`. */
+export const init = (
+  key: string,
+  options: { readonly hideNegativeAxes?: boolean } = {},
+): Model => ({
+  key,
+  hovered: null,
+  hideNegativeAxes: options.hideNegativeAxes ?? false,
+});
+
+type Return = ReturnWithOutMessage<Model, Message, OutMessage>;
+
+/** Which head a hit `key` is on, if it is one of this gizmo's. */
+export const axisOf = (model: Model, key: string): Option.Option<ViewAxis> =>
+  Option.fromNullishOr(viewportAxisOf(model.key, key));
+
+const entered = (model: Model, key: string): Model =>
+  Option.match(axisOf(model, key), {
+    onNone: () => model,
+    onSome: (axis) => ({ ...model, hovered: axis }),
+  });
+
+/** Leaving a head clears the highlight; leaving anything else changes nothing. */
+const left = (model: Model, key: string): Model =>
+  Option.match(axisOf(model, key), {
+    onNone: () => model,
+    onSome: () => ({ ...model, hovered: null }),
+  });
+
+const pressed = (model: Model, key: string, camera: Camera): Return =>
+  Option.match(axisOf(model, key), {
+    onNone: () => ({ model }),
+    onSome: (axis) => ({
+      model,
+      outMessage: OutMessage.Turned({ camera: cameraAlong(camera, axis) }),
+    }),
+  });
+
+export const update = (model: Model, message: Message): Return =>
+  Message.match<Return>(message, {
+    Entered: ({ key }) => ({ model: entered(model, key) }),
+    Left: ({ key }) => ({ model: left(model, key) }),
+    Pressed: ({ key, camera }) => pressed(model, key, camera),
+  });
+
+/** The gizmo for `camera`, for a HUD. */
+export const nodes = (model: Model, camera: Camera): SceneNode =>
+  viewportGizmoNodes(model.key, camera, {
+    hovered: model.hovered,
+    hideNegativeAxes: model.hideNegativeAxes,
+  });
+
+/** A HUD holding only the gizmo, 80 pixels in from the bottom right unless placed. */
+export const hud = (
+  model: Model,
+  camera: Camera,
+  placement: {
+    readonly alignment?: HudAlignment;
+    readonly margin?: readonly [number, number];
+  } = {},
+): Hud => describeHud({ ...placement, children: [nodes(model, camera)] });