@pascal-app/editor 1.0.3 → 1.0.5

package/src/components/editor/first-person/ground-holes.ts

@@ -0,0 +1,130 @@
+/**
+ * Holes in the site ground's collision geometry.
+ *
+ * The walkthrough stands on one merged BVH mesh, and the site's ground (a flat slab, or the terrain)
+ * is a sheet across the whole lot. Where the house stands over a basement the ground is drawn open
+ * (`coveredBelowGradeFootprints`), but the sheet under the stairwell stayed: the player descending
+ * the stair met it at grade and could go no deeper. Cutting the collider by the same rings the
+ * ground is drawn open over lets the player follow the building's floors and stairs there.
+ *
+ * Every triangle that reaches a hole is cut against it in plan; the pieces keep the source
+ * triangle's plane (height and normal interpolated from its corners) and its facing, so the cut
+ * surface is exactly the one the uncut triangle was.
+ */
+
+import { difference, type Ring, union } from '@pascal-app/core'
+import { BufferAttribute, BufferGeometry, ShapeUtils, Vector2 } from 'three'
+
+/** Triangles flatter than this in plan (m²) are vertical faces: they hold nothing up. */
+const MIN_PLAN_AREA = 1e-9
+
+type Corner = { x: number; y: number; z: number; nx: number; ny: number; nz: number }
+
+/** Twice the signed plan area of `a b c` (x right, z down). */
+function orient(a: [number, number], b: [number, number], c: [number, number]): number {
+  return (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0])
+}
+
+/**
+ * `geometry` (non-indexed, `position` and `normal`, in the frame the rings are in) without the part
+ * of it that lies over `holes`. A triangle the clip fails on is kept whole: the ground closed is
+ * the safe side. The geometry is returned as it is when there are no holes.
+ */
+export function cutGroundCollider(
+  geometry: BufferGeometry,
+  holes: readonly Ring[],
+): BufferGeometry {
+  if (holes.length === 0) return geometry
+  const cutouts = union(holes)
+  if (cutouts.length === 0) return geometry
+  const boxes = cutouts.map(({ outer }) => ({
+    minX: Math.min(...outer.map(([x]) => x)),
+    maxX: Math.max(...outer.map(([x]) => x)),
+    minZ: Math.min(...outer.map(([, z]) => z)),
+    maxZ: Math.max(...outer.map(([, z]) => z)),
+  }))
+
+  const position = geometry.getAttribute('position')
+  const normal = geometry.getAttribute('normal')
+  const positions: number[] = []
+  const normals: number[] = []
+  const push = (corner: Corner) => {
+    positions.push(corner.x, corner.y, corner.z)
+    normals.push(corner.nx, corner.ny, corner.nz)
+  }
+
+  for (let i = 0; i + 2 < position.count; i += 3) {
+    const corners: Corner[] = [0, 1, 2].map((k) => ({
+      x: position.getX(i + k),
+      y: position.getY(i + k),
+      z: position.getZ(i + k),
+      nx: normal.getX(i + k),
+      ny: normal.getY(i + k),
+      nz: normal.getZ(i + k),
+    }))
+    const [a, b, c] = corners as [Corner, Corner, Corner]
+    const minX = Math.min(a.x, b.x, c.x)
+    const maxX = Math.max(a.x, b.x, c.x)
+    const minZ = Math.min(a.z, b.z, c.z)
+    const maxZ = Math.max(a.z, b.z, c.z)
+    const reached = boxes.some(
+      (box) => box.maxX > minX && box.minX < maxX && box.maxZ > minZ && box.minZ < maxZ,
+    )
+    const plan: [[number, number], [number, number], [number, number]] = [
+      [a.x, a.z],
+      [b.x, b.z],
+      [c.x, c.z],
+    ]
+    const determinant = orient(plan[0], plan[1], plan[2])
+    if (!reached || Math.abs(determinant) < MIN_PLAN_AREA) {
+      corners.forEach(push)
+      continue
+    }
+
+    let pieces: ReturnType<typeof difference>
+    try {
+      pieces = difference(plan, cutouts, { throwOnError: true })
+    } catch {
+      corners.forEach(push)
+      continue
+    }
+
+    const at = (x: number, z: number): Corner => {
+      const wa = ((b.z - c.z) * (x - c.x) + (c.x - b.x) * (z - c.z)) / determinant
+      const wb = ((c.z - a.z) * (x - c.x) + (a.x - c.x) * (z - c.z)) / determinant
+      const wc = 1 - wa - wb
+      const nx = a.nx * wa + b.nx * wb + c.nx * wc
+      const ny = a.ny * wa + b.ny * wb + c.ny * wc
+      const nz = a.nz * wa + b.nz * wb + c.nz * wc
+      const length = Math.hypot(nx, ny, nz) || 1
+      return {
+        x,
+        y: a.y * wa + b.y * wb + c.y * wc,
+        z,
+        nx: nx / length,
+        ny: ny / length,
+        nz: nz / length,
+      }
+    }
+
+    for (const piece of pieces) {
+      const rings = [piece.outer, ...piece.holes]
+      const points = rings.flat()
+      const contour = piece.outer.map(([x, z]) => new Vector2(x, z))
+      const voids = piece.holes.map((ring) => ring.map(([x, z]) => new Vector2(x, z)))
+      for (const [p, q, r] of ShapeUtils.triangulateShape(contour, voids)) {
+        const corner = [p, q, r].map((index) => points[index as number] as [number, number])
+        const swap =
+          Math.sign(orient(corner[0]!, corner[1]!, corner[2]!)) !== Math.sign(determinant)
+        const ordered = swap ? [corner[0]!, corner[2]!, corner[1]!] : corner
+        for (const [x, z] of ordered) push(at(x, z))
+      }
+    }
+  }
+
+  const cut = new BufferGeometry()
+  cut.setAttribute('position', new BufferAttribute(new Float32Array(positions), 3))
+  cut.setAttribute('normal', new BufferAttribute(new Float32Array(normals), 3))
+  geometry.dispose()
+  return cut
+}

package/src/components/editor/first-person/mechanism-targets.test.ts

@@ -0,0 +1,162 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  nodeRegistry,
+  registerNode,
+  sceneRegistry,
+  useInteractive,
+  useScene,
+} from '@pascal-app/core'
+import { Object3D } from 'three'
+import {
+  hasNativeLeaf,
+  mechanismHudInteract,
+  mechanismTargetIds,
+  nativeOpeningIds,
+  watchScriptedDoors,
+} from './mechanism-targets'
+
+const switchMechanism = {
+  has: (node: AnyNode) => (node as unknown as { joints: number }).joints > 0,
+  isOn: (node: AnyNode, state: ReturnType<typeof useInteractive.getState>) =>
+    Boolean(state.mechanisms[node.id]),
+  set: (node: AnyNode, on: boolean) => useInteractive.getState().setMechanism(node.id, on),
+}
+
+const mounted: [string, string][] = []
+
+function mount(kind: string, id: string, fields: Record<string, unknown> = {}): AnyNode {
+  const node = { object: 'node', id, type: kind, ...fields } as unknown as AnyNode
+  useScene.setState((state) => ({ nodes: { ...state.nodes, [id]: node } }) as never)
+  sceneRegistry.nodes.set(id, new Object3D())
+  sceneRegistry.byType[kind]!.add(id)
+  mounted.push([kind, id])
+  return node
+}
+
+function registerKind(capabilities: Record<string, unknown>): string {
+  const kind = `test:walk-${crypto.randomUUID()}`
+  registerNode({
+    kind,
+    schemaVersion: 1,
+    category: 'furnish',
+    defaults: () => ({}),
+    capabilities,
+  } as never)
+  return kind
+}
+
+afterEach(() => {
+  for (const [kind, id] of mounted.splice(0)) {
+    sceneRegistry.nodes.delete(id)
+    sceneRegistry.byType[kind]!.delete(id)
+    useInteractive.getState().removeMechanism(id as AnyNodeId)
+  }
+})
+
+describe('walkthrough mechanism targets', () => {
+  test('any mounted node whose kind declares a mechanism is a target, once', () => {
+    const kind = registerKind({ mechanism: switchMechanism })
+    mount(kind, 'articulated_1', { joints: 2 })
+    mount(kind, 'articulated_still', { joints: 0 })
+    mount(registerKind({}), 'plain_1')
+    const covered = mount(kind, 'articulated_covered', { joints: 1 })
+
+    expect(mechanismTargetIds(new Set([covered.id]))).toEqual(['articulated_1' as AnyNodeId])
+  })
+
+  test('the HUD names the node and says what E will do', () => {
+    const kind = registerKind({ mechanism: switchMechanism })
+    const node = mount(kind, 'articulated_hud', { joints: 1, name: 'Desk lamp' })
+    expect(mechanismHudInteract(node)).toEqual({ label: 'Desk lamp', verb: 'turn on' })
+    useInteractive.getState().setMechanism(node.id, true)
+    expect(mechanismHudInteract(node)).toEqual({ label: 'Desk lamp', verb: 'turn off' })
+
+    const lid = mount(registerKind({ mechanism: { ...switchMechanism, verb: 'open' } }), 'lid_1', {
+      joints: 1,
+    })
+    expect(mechanismHudInteract(lid)).toEqual({ label: 'item', verb: 'open' })
+    expect(mechanismHudInteract(mount(registerKind({}), 'plain_hud'))).toBeNull()
+  })
+})
+
+// A door or window built from a script has no native leaf or sash: the walkthrough's own door and
+// window targets only start a native swing on it, which draws nothing. Its `open` clip runs
+// through its mechanism, as an authored object's does.
+describe('walkthrough doors and windows', () => {
+  const script = { source: { kind: 'script', script: 'b'.repeat(64), artifact: 'a'.repeat(64) } }
+
+  test('the doors and windows it swings itself are the ones with a native leaf', () => {
+    const native = mount('door', 'door_native')
+    const scripted = mount('door', 'door_scripted', script)
+    mount('window', 'window_native')
+    mount('window', 'window_scripted', script)
+
+    expect(nativeOpeningIds().sort()).toEqual(['door_native', 'window_native'] as AnyNodeId[])
+    expect(hasNativeLeaf(native)).toBe(true)
+    expect(hasNativeLeaf(scripted)).toBe(false)
+    expect(hasNativeLeaf(undefined)).toBe(true)
+  })
+})
+
+// The walkthrough's collider world is rebuilt when a native door's tween ends. A door built from a
+// script opens by a clip that no tween system reports: its collider follows its mechanism, so
+// the world has to be rebuilt when that flips.
+describe('walkthrough scripted doors', () => {
+  const mechanism = {
+    verb: 'open',
+    has: (node: AnyNode) => Boolean((node as unknown as { source?: unknown }).source),
+    isOn: (node: AnyNode, state: ReturnType<typeof useInteractive.getState>) =>
+      Boolean(state.items[node.id as AnyNodeId]?.controlValues[0]),
+    set: () => {},
+  }
+  let restoreRegistry = () => {}
+
+  beforeEach(() => {
+    restoreRegistry = nodeRegistry._snapshot()
+    registerNode({
+      kind: 'door',
+      schemaVersion: 1,
+      category: 'structure',
+      defaults: () => ({}),
+      capabilities: { mechanism },
+    } as never)
+  })
+
+  afterEach(() => {
+    useInteractive.setState({ items: {} } as never)
+    restoreRegistry()
+  })
+
+  test('a rebuild is asked for when a scripted door opens or closes, and for nothing else', () => {
+    mount('door', 'door_scripted_watch', { source: { kind: 'script' } })
+    mount('door', 'door_native_watch')
+    let rebuilds = 0
+    const stop = watchScriptedDoors(() => rebuilds++)
+    const setControls = (scripted: boolean, native: boolean) =>
+      useInteractive.setState({
+        items: {
+          door_scripted_watch: { controlValues: [scripted] },
+          door_native_watch: { controlValues: [native] },
+        },
+      } as never)
+    try {
+      // its model initialising the item closed is not a change
+      setControls(false, false)
+      expect(rebuilds).toBe(0)
+      setControls(true, false)
+      expect(rebuilds).toBe(1)
+      // the same state again, and a native door's control, are not its business
+      setControls(true, false)
+      setControls(true, true)
+      expect(rebuilds).toBe(1)
+      setControls(false, true)
+      expect(rebuilds).toBe(2)
+    } finally {
+      stop()
+    }
+    setControls(true, true)
+    expect(rebuilds).toBe(2)
+  })
+})

package/src/components/editor/first-person/mechanism-targets.ts

@@ -0,0 +1,88 @@
+import {
+  type AnyNode,
+  type AnyNodeId,
+  isScriptedNode,
+  nodeMechanism,
+  nodeRegistry,
+  sceneRegistry,
+  useInteractive,
+  useScene,
+} from '@pascal-app/core'
+import type { WalkthroughInteract } from '../../../store/use-first-person-hud'
+
+/**
+ * Whether the walkthrough swings this door or window itself, through the native `operationState`
+ * its door and window systems draw. One built from a script has no native leaf or sash: a swing
+ * would draw nothing, so its clips run through its mechanism, as an authored object's do.
+ */
+export function hasNativeLeaf(node: AnyNode | undefined): boolean {
+  return !isScriptedNode(node)
+}
+
+/** Mounted doors and windows the walkthrough's own door and window targets cover. */
+export function nativeOpeningIds(): AnyNodeId[] {
+  const nodes = useScene.getState().nodes
+  const ids: AnyNodeId[] = []
+  for (const kind of ['door', 'window'] as const) {
+    for (const id of sceneRegistry.byType[kind] ?? []) {
+      if (hasNativeLeaf(nodes[id as AnyNodeId])) ids.push(id as AnyNodeId)
+    }
+  }
+  return ids
+}
+
+/**
+ * Mounted nodes the walkthrough runs through `capabilities.mechanism`, any kind
+ * included. `covered` holds the nodes a finer target already tested (procedural
+ * parts, catalog item toggles), so no node is targeted twice.
+ */
+export function mechanismTargetIds(covered: ReadonlySet<string>): AnyNodeId[] {
+  const nodes = useScene.getState().nodes
+  const ids: AnyNodeId[] = []
+  for (const [kind, kindIds] of Object.entries(sceneRegistry.byType)) {
+    if (!nodeRegistry.get(kind)?.capabilities.mechanism) continue
+    for (const id of kindIds) {
+      if (!covered.has(id) && nodeMechanism(nodes[id as AnyNodeId])) ids.push(id as AnyNodeId)
+    }
+  }
+  return ids
+}
+
+/** The walkthrough prompt for a mechanism target: its name and what E does next. */
+export function mechanismHudInteract(node: AnyNode): WalkthroughInteract {
+  const mechanism = nodeMechanism(node)
+  if (!mechanism) return null
+  const on = mechanism.isOn(node, useInteractive.getState())
+  const verb = mechanism.verb === 'open' ? (on ? 'close' : 'open') : on ? 'turn off' : 'turn on'
+  return { label: node.name ?? 'item', verb }
+}
+
+/** Ids of the mounted doors built from a script that are open, by their mechanism. */
+function openScriptedDoors(): string {
+  const nodes = useScene.getState().nodes
+  const state = useInteractive.getState()
+  const open: string[] = []
+  for (const id of sceneRegistry.byType.door ?? []) {
+    const node = nodes[id as AnyNodeId]
+    if (isScriptedNode(node) && nodeMechanism(node)?.isOn(node, state)) open.push(id)
+  }
+  return open.sort().join(',')
+}
+
+/**
+ * Calls `onChange` when a mounted door built from a script opens or closes. The walkthrough's
+ * collider follows the door's mechanism, and its model's clip is moved by no tween system that
+ * would report the end, as a native door's does: without this the world keeps the leaf that was
+ * there when it was last built. It fires at the toggle: the doorway is passable as the leaves
+ * start to move, and solid again as they start to close.
+ */
+export function watchScriptedDoors(onChange: () => void): () => void {
+  let known = openScriptedDoors()
+  return useInteractive.subscribe((state, previous) => {
+    if (state.items === previous.items) return
+    const next = openScriptedDoors()
+    if (next === known) return
+    known = next
+    onChange()
+  })
+}