@solidrt/3d 0.0.56 → 0.0.57

package/src/index.ts

@@ -6,7 +6,7 @@
 // PerspectiveCamera) on top. See AGENTS.md for the model and the traps.
 
 export { add, createGroup, getRotation, getTransform, lookAt, remove, setTransform, setTransition, setVisible, worldPosition } from "./node.ts"
-export type { SceneNode, ScenePointerEvent, TransformUpdate, TransitionEndEvent } from "./node.ts"
+export type { NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneEventBase, SceneNode, ScenePointerEvent, ScenePointerListener, SceneTapEvent, SceneWheelEvent, TransformUpdate, TransitionEndEvent } from "./node.ts"
 export { addInstance, createInstancedMesh, createMesh, createRecordMesh, createSprite, disposeInstances, removeInstance, setCastShadow, setCulling, setGeometry, setInstanceStyle, setLayers, setMaterial, setMeshParams, setRecordCount, setRecords, setRenderOrder, INSTANCE_FLOATS } from "./mesh.ts"
 export type { InstancedMesh as InstancedMeshNode, InstancedMeshOptions, InstanceNode, InstanceSlots, InstanceStyle, Mesh as MeshNode, MeshInstances, RecordMesh as RecordMeshNode, RecordMeshOptions } from "./mesh.ts"
 export { createDirectionalLight, createHemisphereLight, createPointLight, createSpotLight, setLight, MAX_SHADOWS } from "./light.ts"
@@ -26,9 +26,10 @@ export type {
   SpotShadowOptions,
 } from "./light.ts"
 export { createScene } from "./scene.ts"
-export type { Capsule, EnvironmentOptions, FogOptions, Hit, Impact, OrientedBox, Overlap, QueryOptions, ReflectionProbe, ReflectionProbeOptions, Scene as SceneHandle, SceneHandlers, SceneOptions, ScreenRay, SkyboxOptions, Sphere, ToneMapping, View, ViewOptions, Volume } from "./scene.ts"
+export { feedPointer } from "./scene-pointer.ts"
+export type { Capsule, EnvironmentOptions, FogOptions, Hit, Impact, MoveOptions, MoveResult, OrientedBox, Overlap, QueryOptions, ReflectionProbe, ReflectionProbeOptions, Scene as SceneHandle, SceneHandlers, SceneOptions, ScreenRay, SkyboxOptions, Sphere, ToneMapping, ViewHandle, ViewOptions, Volume } from "./scene.ts"
 export { moveAndSlide } from "./collision.ts"
-export type { MoveOptions, MoveResult, MoveScene } from "./collision.ts"
+export type { MoveScene } from "./collision.ts"
 export { equirectToCube, loadEnvironment } from "./environment.ts"
 export { linearColor, linearToSrgb, srgbToLinear } from "./color.ts"
 export type { CameraState, CameraUpdate, OrthoExtent } from "./camera.ts"
@@ -42,8 +43,9 @@ export { extrude, lathe, pathFrames, sweep, tube } from "./sweep.ts"
 export type { ExtrudeOptions, LatheOptions, PathFrames, PathPoint, SweepPath, TubeOptions } from "./sweep.ts"
 export { lit, shaderMaterial, shaderMaterialClass, sprite, standard, unlit } from "./material.ts"
 export type { LitOptions, Material, ShaderMaterialClass, ShaderMaterialClassOptions, ShaderMaterialInstanceOptions, ShaderMaterialOptions, SpriteOptions, StandardOptions, UnlitOptions } from "./material.ts"
-export { DirectionalLight, FirstPersonCamera, Group, HemisphereLight, Instance, InstancedMesh, Mesh, OrbitCamera, PerspectiveCamera, PointLight, RecordMesh, Scene, SpotLight, Sprite, useScene } from "./components.tsx"
+export { DirectionalLight, FirstPersonCamera, Group, HemisphereLight, Instance, InstancedMesh, Mesh, OrbitCamera, PerspectiveCamera, PointLight, RecordMesh, Scene, SpotLight, Sprite, View3d, useScene } from "./components/index.ts"
 export type {
+  CameraTarget,
   DirectionalLightProps,
   FirstPersonCameraProps,
   HemisphereLightProps,
@@ -55,13 +57,13 @@ export type {
   PointerEventProps,
   PointLightProps,
   RecordMeshProps,
-  SceneInput,
-  SceneInputListener,
+  ScenePointerProps,
   SceneProps,
   SpotLightProps,
   SpriteProps,
   TransformProps,
-} from "./components.tsx"
+  View3dProps,
+} from "./components/index.ts"
 export { gltfExternalUris, isGlb, parseGltf } from "./gltf.ts"
 export type { ModelChannel, ModelClip, ModelData, ModelMaterial, ModelNode, ModelPart, ModelSkin, UriResolver } from "./gltf.ts"
 export { decodeModel, encodeModel } from "./model-file.ts"
@@ -71,9 +73,11 @@ export { createMixer } from "./mixer.ts"
 export type { Mixer, MixerOptions, MixerPlayOptions } from "./mixer.ts"
 export { sampleChannel } from "./clip.ts"
 export { createOrbitCamera } from "./orbit.ts"
-export type { OrbitCamera as OrbitCameraHandle, OrbitCameraOptions, OrbitPose, OrbitTarget } from "./orbit.ts"
+export type { OrbitAxes, OrbitCamera as OrbitCameraHandle, OrbitCameraOptions, OrbitPose, OrbitTarget } from "./orbit.ts"
 export { createFirstPersonCamera } from "./first-person.ts"
-export type { FirstPersonCamera as FirstPersonCameraHandle, FirstPersonCameraOptions, FirstPersonPose, FirstPersonTarget } from "./first-person.ts"
+export type { FirstPersonAxes, FirstPersonCamera as FirstPersonCameraHandle, FirstPersonCameraOptions, FirstPersonPose, FirstPersonTarget } from "./first-person.ts"
+export { firstPersonActions, firstPersonBindings, orbitActions, orbitBindings } from "./input.ts"
+export type { CameraDevices } from "./input.ts"
 // math's lookAt (the camera view matrix) stays on the /math subpath: the
 // root's lookAt is the scene verb, the same split as `add`.
 export { rayBoxDistance, compose, copy, eulerFromQuat, identity, mat4, multiply, normalMatrix, orthographic, perspective, quat, quatFromAxisAngle, quatFromEuler, quatFromFrame, quatFromTo, quatMultiply, quatNormalize, quatSlerp } from "./math.ts"

package/src/input.ts

@@ -0,0 +1,70 @@
+// The standard input wiring for the 3d camera controls: the action
+// declarations each control consumes (its axes, by the shared vocabulary)
+// and a preset per control that binds the devices an app hands in. A
+// preset is plain data - the bindings the app could write by hand -
+// applied with `input.bind(orbitBindings({ pointer, gamepad }))` and
+// adjusted afterwards with unbind; nothing binds unless the app says so
+// (ARCHITECTURE.md).
+//
+// Devices are the nouns: `pointer` is the feed of the element showing the
+// scene (`createPointerFeed()`, handed to `<Scene pointer>`), `gamepad` a
+// core gamepad device (`gamepad(0)`, or `gamepad()` for any pad), and
+// `keyboard` the core keyboard device, whose key events reach the map
+// through `input.handlers` spread on the window.
+//
+// Keys and sticks move the CAMERA where a drag moves the content (the
+// stick right orbits the eye to the right; a drag right spins the scene
+// to the right), so the rotate and pan bindings of those devices go
+// through invert() and each axis keeps its one meaning. `look` is the
+// exception by nature: a drag and a stick both turn the eye.
+
+import { invert } from "@solidrt/core/input"
+import type { Binding, GamepadDevice, KeyboardDevice, PointerFeed } from "@solidrt/core"
+
+export type CameraDevices = {
+  pointer?: PointerFeed
+  gamepad?: GamepadDevice
+  keyboard?: KeyboardDevice
+}
+
+/** The orbit control's actions: `rotate`, `zoom`, `pan`. */
+export let orbitActions = { rotate: "vec2", zoom: "axis", pan: "vec2" } as const
+
+/**
+ * The orbit camera's standard bindings: a drag rotates, a pinch and the
+ * wheel zoom, two fingers pan; the right stick rotates, the triggers
+ * zoom, the left stick pans; the arrow keys rotate and minus/equals zoom.
+ */
+export function orbitBindings(devices: CameraDevices): Binding[] {
+  let out: Binding[] = []
+  let { pointer, gamepad, keyboard } = devices
+  if (pointer) {
+    out.push({ action: "rotate", source: pointer.drag }, { action: "zoom", source: pointer.pinch }, { action: "zoom", source: pointer.wheel }, { action: "pan", source: pointer.pan })
+  }
+  if (gamepad) {
+    out.push({ action: "rotate", source: invert(gamepad.rightStick) }, { action: "zoom", source: gamepad.triggers }, { action: "pan", source: invert(gamepad.leftStick) })
+  }
+  if (keyboard) {
+    out.push({ action: "rotate", source: invert(keyboard.arrows) }, { action: "zoom", source: keyboard.axis("Minus", "Equal") })
+  }
+  return out
+}
+
+/** The first-person control's actions: `look`, `move`, `rise`. */
+export let firstPersonActions = { look: "vec2", move: "vec2", rise: "axis" } as const
+
+/**
+ * The first-person camera's standard bindings: a drag looks around and so
+ * does mouse motion while the pointer is locked (the app locks it: see
+ * examples/first-person.tsx); the right stick looks, the left stick
+ * walks, the shoulders rise and sink in fly mode; WASD and the arrows
+ * walk, Q/E rise and sink.
+ */
+export function firstPersonBindings(devices: CameraDevices): Binding[] {
+  let out: Binding[] = []
+  let { pointer, gamepad, keyboard } = devices
+  if (pointer) out.push({ action: "look", source: pointer.drag }, { action: "look", source: pointer.mouseDelta })
+  if (gamepad) out.push({ action: "look", source: gamepad.rightStick }, { action: "move", source: gamepad.leftStick }, { action: "rise", source: gamepad.shoulders })
+  if (keyboard) out.push({ action: "move", source: keyboard.wasd }, { action: "move", source: keyboard.arrows }, { action: "rise", source: keyboard.axis("KeyQ", "KeyE") })
+  return out
+}

package/src/node.ts

@@ -10,12 +10,14 @@ import * as spatial from "flux:spatial"
 import type { NodeId, NodeTransition } from "flux:spatial"
 import { on } from "srt:events"
 import type { ShaderParams, TextureId } from "@solidrt/core/gpu"
+import type { PointerEvent as ElementPointerEvent, WheelEvent as ElementWheelEvent } from "@solidrt/core"
 // The scene's lookAt() aims a node; math's builds a camera's view matrix -
 // the same pairing (and the same name) as Three's Object3D/Matrix4.
 import { compose, eulerFromQuat, identity, mat4, multiply, quat, quatFromFrame, transformPoint, updateRotation, updateScale } from "./math.ts"
 import type { Mat4, Quat, TransformUpdate, Vec3, Vec4 } from "./math.ts"
 import type { CastingLight, Light } from "./light.ts"
 import type { InstancedMesh, InstanceNode, Mesh } from "./mesh.ts"
+import type { Scene, ViewHandle } from "./scene.ts"
 
 // lookAt()'s default roll reference. Read-only: quatFromFrame never
 // writes its inputs, so one shared vector is safe.
@@ -107,15 +109,23 @@ export type SceneNode = {
   visible: boolean
   /** Pointer event handlers - plain fields, assign freely (they touch no
    * GPU state, so they need no setTransform-style write path; components
-   * sync their props here). Down/move/up dispatch on the hit mesh and
-   * bubble through its ancestors (stopPropagation stops the walk);
-   * enter/leave fire on the mesh alone. Events flow once the element
-   * showing the scene carries `scene.handlers`. */
-  onPointerDown?: (event: ScenePointerEvent) => void
-  onPointerMove?: (event: ScenePointerEvent) => void
-  onPointerUp?: (event: ScenePointerEvent) => void
-  onPointerEnter?: (event: ScenePointerEvent) => void
-  onPointerLeave?: (event: ScenePointerEvent) => void
+   * sync their props here). Down/move/up/wheel/tap dispatch on the
+   * nearest hit - the struck instance of an instanced mesh, else the mesh
+   * - bubble through its ancestors and end at the scene's listeners
+   * (stopPropagation stops the walk, and a stopped down claims the whole
+   * press); enter/leave fire on the struck node alone. Events flow once
+   * the element showing the scene carries `scene.handlers`. */
+  onPointerDown?: (event: NodePointerEvent) => void
+  onPointerMove?: (event: NodePointerEvent) => void
+  onPointerUp?: (event: NodePointerEvent) => void
+  onPointerEnter?: (event: NodePointerEvent) => void
+  onPointerLeave?: (event: NodePointerEvent) => void
+  /** The wheel over the node (NodeWheelEvent: `deltaX`/`deltaY`), bubbling
+   * like down/move/up. */
+  onWheel?: (event: NodeWheelEvent) => void
+  /** A press released on this node within the slop, alone for its whole
+   * press (NodeTapEvent: `tapCount`); bubbles like down/move/up. */
+  onTap?: (event: NodeTapEvent) => void
   /** A declared transition (setTransition) settled naturally on one
    * component; a cancel, snap or scene leave never fires. */
   onTransitionEnd?: (event: TransitionEndEvent) => void
@@ -146,26 +156,19 @@ export type TransitionEndEvent = {
   component: "position" | "rotation" | "scale"
 }
 
-/**
- * The event a mesh, instance or ancestor group handler receives: the
- * element pointer vocabulary carried over, plus the 3D fields.
- * `point`/`distance` are null exactly when the ray misses the dispatch
- * target - which happens only during a captured drag or on a leave.
- */
-export type ScenePointerEvent = {
-  /** The mesh the event is about (the hit, or the captured mesh during a
-   * drag) - constant while the event bubbles. */
-  mesh: Mesh
+/** What every scene pointer event carries, whichever handler sees it:
+ * the element pointer vocabulary carried over, plus the 3D fields. */
+export type SceneEventBase = {
   /** The instance struck when `mesh` is an instanced mesh (the walk
    * starts there), null otherwise - constant while the event bubbles. */
   instance: InstanceNode | null
-  /** Node whose handler is running; changes as the event bubbles. */
-  currentTarget: SceneNode
-  /** World-space hit point on `mesh`, or null when the ray misses it. */
+  /** World-space hit point on `mesh`, or null when there is no mesh or
+   * the ray misses it (a captured drag off the mesh, a leave). */
   point: Vec3 | null
   /** Camera-ray distance to `point` in world units, or null with it. */
   distance: number | null
-  /** Pointer position in scene pixels - project()'s coordinate space. */
+  /** Pointer position in scene pixels - project()'s coordinate space
+   * (a view's own pixels under a view leaf). */
   x: number
   y: number
   pointerId: number
@@ -175,10 +178,77 @@ export type ScenePointerEvent = {
   ctrlKey: boolean
   altKey: boolean
   metaKey: boolean
-  /** Stops the bubble walk after the current handler. */
+  /**
+   * The element event the scene's leaf received, in the leaf's own frame
+   * (localX/localY, clientX/clientY, movementX/Y): what core's
+   * recognizers consume, so a mesh drags itself through `createPan` and
+   * a camera control's feed rides the same events the walk carries.
+   */
+  native: ElementPointerEvent
+  /**
+   * Stops the walk after the current handler: no ancestor and none of the
+   * scene's listeners see the event. Stopping a DOWN claims the whole
+   * press - that pointer's move, up and tap never reach the scene either,
+   * so a mesh that drags itself stops its down once and an orbit control
+   * fed at the root never turns under it.
+   */
   stopPropagation(): void
 }
 
+/**
+ * The event a mesh, instance or ancestor group handler receives: `mesh`
+ * is the hit (or the captured mesh during a drag), constant while the
+ * event bubbles; `currentTarget` the node whose handler is running.
+ */
+export type NodePointerEvent = SceneEventBase & {
+  mesh: Mesh
+  currentTarget: SceneNode
+}
+
+/**
+ * The event as the SCENE's listeners see it (scene.listen, the `<Scene>`
+ * pointer props; a view's under its own leaf), the last stop of the walk:
+ * `mesh` is the hit it bubbled from, or null over empty space, where the
+ * scene is the only target.
+ */
+export type ScenePointerEvent = SceneEventBase & {
+  mesh: Mesh | null
+  currentTarget: Scene | ViewHandle
+}
+
+type WheelFields = {
+  /** The wheel delta as the element event reports it. */
+  deltaX: number
+  deltaY: number
+  native: ElementWheelEvent
+}
+type TapFields = {
+  /** 1 for a tap, 2 for the second of a double tap (the same target,
+   * within the repeat interval and distance), and so on - DOM's `detail`,
+   * Unity's `clickCount`. */
+  tapCount: number
+}
+
+export type NodeWheelEvent = NodePointerEvent & WheelFields
+export type SceneWheelEvent = ScenePointerEvent & WheelFields
+/**
+ * A press that released on the target it pressed without travelling past
+ * the slop, the only pointer down for its whole press (a pinch never
+ * taps). Dispatched after the up, bubbling the same way; `x`/`y` and
+ * `point` are the release point.
+ */
+export type NodeTapEvent = NodePointerEvent & TapFields
+export type SceneTapEvent = ScenePointerEvent & TapFields
+
+/** A listener at the scene's (or a view's) root; see Scene.listen. */
+export type ScenePointerListener = {
+  onPointerDown?: (event: ScenePointerEvent) => void
+  onPointerMove?: (event: ScenePointerEvent) => void
+  onPointerUp?: (event: ScenePointerEvent) => void
+  onWheel?: (event: SceneWheelEvent) => void
+  onTap?: (event: SceneTapEvent) => void
+}
+
 /** A bare node record (internal: the mesh and light constructors build on it). */
 export function makeNode(kind: SceneNode["kind"]): SceneNode {
   return {
@@ -245,7 +315,10 @@ export function enterScene(node: SceneNode, scene: SceneHooks): void {
     }
   }
   if (node._cullBounds !== null) spatial.setCullBounds(node._node, node._cullBounds)
-  if (node.kind === "mesh") scene._attach(node as Mesh)
+  if (node.kind === "mesh") {
+    spatial.setLayers(node._node, (node as Mesh).layers)
+    scene._attach(node as Mesh)
+  }
   else if (node.kind === "light") scene._attachLight(node as Light)
   else if (node.kind === "instance") scene._attachInstance(node as InstanceNode)
   for (let c of node.children) enterScene(c, scene)