@volter/game-editor 0.5.81 → 0.5.83

package/template/src/lib/reflections/ReflectionProbe.tsx

@@ -1,8 +1,7 @@
 import { type ThreeElements, useFrame, useThree } from '@react-three/fiber';
-import type { ReflectionProbeConfig } from '@volter/threejs-runtime/adapter/reflection-probe';
 import { type ReactNode, useLayoutEffect, useRef, useState } from 'react';
 import type * as THREE from 'three';
-import { createReflectionProbeMark } from './probe-controller';
+import { createReflectionProbeMark, type VolumeReflectionProbeConfig } from './probe-controller';
 import {
   acquireReflectionProbeRegistry,
   type ReflectionProbeRegistryLease,
@@ -60,6 +59,15 @@ export type ReflectionProbeProps = Omit<ThreeElements['group'], 'children'> & {
   readonly blendDistance?: number;
   readonly priority?: number;
   readonly intensity?: number;
+  /**
+   * The diffuse light the volume material takes from this probe: its capture
+   * (default), the constant `diffuseColor`, or none. See `ReflectionProbeDiffuse`.
+   */
+  readonly diffuse?: 'capture' | 'color' | 'none';
+  /** Scales the probe's diffuse light in the volume material; defaults to `intensity`. */
+  readonly diffuseIntensity?: number;
+  /** Linear RGB of the `color` diffuse. */
+  readonly diffuseColor?: [number, number, number];
   readonly parallaxProjection?: boolean;
   /** Full local-space projection-box dimensions. */
   readonly parallaxSize?: [number, number, number];
@@ -73,6 +81,19 @@ export type ReflectionProbeProps = Omit<ThreeElements['group'], 'children'> & {
   readonly captureShadows?: boolean;
 };
 
+/** The diffuse fields a probe states, leaving out the ones it does not (they keep their defaults). */
+function diffuseConfig(
+  diffuse: ReflectionProbeProps['diffuse'],
+  diffuseIntensity: number | undefined,
+  diffuseColor: [number, number, number] | undefined,
+): Partial<VolumeReflectionProbeConfig> {
+  return {
+    ...(diffuse === undefined ? {} : { diffuse }),
+    ...(diffuseIntensity === undefined ? {} : { diffuseIntensity }),
+    ...(diffuseColor === undefined ? {} : { diffuseColor }),
+  };
+}
+
 export function ReflectionProbe({
   name = 'Reflection Probe',
   children,
@@ -82,6 +103,9 @@ export function ReflectionProbe({
   blendDistance = 1,
   priority = 0,
   intensity = 1,
+  diffuse,
+  diffuseIntensity,
+  diffuseColor,
   parallaxProjection = true,
   parallaxSize = [10, 6, 10],
   parallaxOffset = [0, 0, 0],
@@ -109,6 +133,7 @@ export function ReflectionProbe({
       blendDistance,
       priority,
       intensity,
+      ...diffuseConfig(diffuse, diffuseIntensity, diffuseColor),
       parallaxProjection,
       parallaxSize,
       parallaxOffset,
@@ -121,13 +146,14 @@ export function ReflectionProbe({
       captureShadows,
     }),
   );
-  const config: ReflectionProbeConfig = {
+  const config: VolumeReflectionProbeConfig = {
     shape,
     size,
     radius,
     blendDistance,
     priority,
     intensity,
+    ...diffuseConfig(diffuse, diffuseIntensity, diffuseColor),
     parallaxProjection,
     parallaxSize,
     parallaxOffset,
@@ -149,6 +175,9 @@ export function ReflectionProbe({
     blendDistance,
     priority,
     intensity,
+    diffuse,
+    diffuseIntensity,
+    diffuseColor,
     parallaxProjection,
     parallaxSize,
     parallaxOffset,
@@ -170,8 +199,8 @@ export function ReflectionProbe({
     unobserve.current = acquired.registry.observe((probes: readonly ReflectionProbeRuntime[]) => {
       const self = probes.find((probe) => probe.node === object);
       const published = self?.ready ? self.texture : null;
-      // Runs every update; React re-renders only when the published texture
-      // actually changes identity, which is once per capture at most.
+      // Runs whenever the registry changes; React re-renders only when the
+      // published texture actually changes identity, once per capture at most.
       setEnvMap((current) => (current === published ? current : published));
     });
     return () => {

package/template/src/lib/reflections/index.ts

@@ -3,6 +3,7 @@ export {
   type ReflectionProbeProps,
   type ReflectionProbePublication,
 } from './ReflectionProbe';
+export type { ReflectionProbeDiffuse, VolumeReflectionProbeConfig } from './probe-controller';
 export {
   acquireReflectionProbeRegistry,
   createReflectionProbeRegistry,

package/template/src/lib/reflections/probe-controller.ts

@@ -4,17 +4,53 @@ import type {
   ReflectionProbeSnapshot,
 } from '@volter/threejs-runtime/adapter/reflection-probe';
 
+/**
+ * How a probe lights the diffuse term of the volume material that blends it,
+ * carried in its mark's config beside the format-neutral fields. Every field
+ * is optional; left out, a probe lights the diffuse from its capture, scaled
+ * by its `intensity`, as the reflected term is.
+ */
+export interface ReflectionProbeDiffuse {
+  /**
+   * Where the probe's diffuse light comes from: its `capture` (the default), the
+   * constant `color` below, or `none` — the probe lights no diffuse, and a
+   * fragment that only it covers keeps the environment's.
+   */
+  readonly diffuse?: 'capture' | 'color' | 'none';
+  /** Scales the probe's diffuse light. Defaults to the probe's `intensity`. */
+  readonly diffuseIntensity?: number;
+  /** Linear RGB radiance of the `color` diffuse. */
+  readonly diffuseColor?: readonly [number, number, number];
+}
+
+/** A probe's config as the capability's own element states it. */
+export type VolumeReflectionProbeConfig = ReflectionProbeConfig & ReflectionProbeDiffuse;
+
 export interface MutableReflectionProbeMark extends ReflectionProbeMark {
   updateConfig(config: ReflectionProbeConfig): void;
   setCaptureStatus(snapshot: ReflectionProbeSnapshot): void;
 }
 
-/** One live projection of a component's JSX props and capture state. */
+/**
+ * The config as a capture sees it: everything but the diffuse fields, which
+ * only the volume material reads (from the probe's uniforms, not its capture).
+ */
+function captureSignature(config: ReflectionProbeConfig): string {
+  const { diffuse, diffuseIntensity, diffuseColor, ...captured } = config as VolumeReflectionProbeConfig;
+  return JSON.stringify(captured);
+}
+
+/**
+ * One live projection of a component's JSX props and capture state. A config
+ * change that a capture sees queues a recapture (outside Manual); one that
+ * only changes the diffuse fields takes effect without one.
+ */
 export function createReflectionProbeMark(
   initial: ReflectionProbeConfig,
 ): MutableReflectionProbeMark {
   let config = initial;
   let configSignature = JSON.stringify(initial);
+  let capturedSignature = captureSignature(initial);
   let revision = 0;
   let snapshot: ReflectionProbeSnapshot = {
     status: initial.captureMode === 'manual' ? 'idle' : 'queued',
@@ -47,12 +83,17 @@ export function createReflectionProbeMark(
       const signature = JSON.stringify(next);
       if (signature === configSignature) return;
       const previousMode = config.captureMode;
+      const nextCaptured = captureSignature(next);
+      const recapture = nextCaptured !== capturedSignature;
       config = next;
       configSignature = signature;
-      if (next.captureMode !== 'manual') {
+      capturedSignature = nextCaptured;
+      // A diffuse-only change needs no capture: the registry sees the new config
+      // and the volume material rewrites its uniforms.
+      if (recapture && next.captureMode !== 'manual') {
         revision += 1;
         snapshot = { status: 'queued', lastCapturedAt: snapshot.lastCapturedAt };
-      } else if (previousMode !== 'manual' && snapshot.status !== 'ready') {
+      } else if (next.captureMode === 'manual' && previousMode !== 'manual' && snapshot.status !== 'ready') {
         // Entering Manual never performs an implicit capture. A valid existing
         // result remains valid; otherwise the explicit Recapture button is the
         // only operation that advances the capture revision.

package/template/src/lib/reflections/reflection-probe-registry.ts

@@ -71,9 +71,17 @@ interface ProbeState extends ReflectionProbeRuntime {
   ready: boolean;
   capturedRevision: number;
   readonly capturedTransform: Matrix4;
+  /** The node's world matrix and the mark's config as observers were last told them. */
+  readonly publishedTransform: Matrix4;
+  publishedConfig: ReflectionProbeMark['config'] | null;
 }
 
-/** Called every update, and again the moment a capture window opens/closes. */
+/**
+ * Called when an observer starts observing, and again whenever what it reads
+ * changes: a probe added or removed, a capture window opening or closing (and
+ * the result it published), a probe's node moved or its config changed. A
+ * frame in which nothing changed calls no observer.
+ */
 export type ReflectionProbeObserver = (
   probes: readonly ReflectionProbeRuntime[],
   capturing: boolean,
@@ -129,6 +137,8 @@ function makeProbe(node: Object3D, mark: ReflectionProbeMark): ProbeState {
     parallaxOffset: new Vector3(),
     captureOffset: new Vector3(),
     capturedTransform: new Matrix4().makeScale(0, 0, 0),
+    publishedTransform: new Matrix4().makeScale(0, 0, 0),
+    publishedConfig: null,
     filtered: null,
     atlases: new Map(),
     texture: null,
@@ -174,6 +184,10 @@ function releaseProbeResources(probe: ProbeState): void {
   probe.ready = false;
 }
 
+/**
+ * Bring the probe's volume up to date with its node and config; true when
+ * that changed what an observer reads since it was last told.
+ */
 function refreshProbe(probe: ProbeState): boolean {
   const config = probe.mark.config;
   const cubeSize = cubeSizeOf(probe.mark);
@@ -194,9 +208,15 @@ function refreshProbe(probe: ProbeState): boolean {
   probe.parallaxExtents.fromArray(config.parallaxSize).multiplyScalar(0.5);
   probe.parallaxOffset.fromArray(config.parallaxOffset);
   probe.captureOffset.fromArray(config.captureOffset);
-  const moved = !probe.capturedTransform.equals(probe.node.matrixWorld);
-  if (moved && config.captureMode === 'on-change') probe.ready = false;
-  return moved;
+  if (config.captureMode === 'on-change' && movedSinceCapture(probe)) probe.ready = false;
+  const changed = probe.publishedConfig !== config || !probe.publishedTransform.equals(probe.node.matrixWorld);
+  probe.publishedConfig = config;
+  probe.publishedTransform.copy(probe.node.matrixWorld);
+  return changed;
+}
+
+function movedSinceCapture(probe: ProbeState): boolean {
+  return !probe.capturedTransform.equals(probe.node.matrixWorld);
 }
 
 /** The cube target and camera, created here because only a capture needs them. */
@@ -300,7 +320,7 @@ export function createReflectionProbeRegistry(
     for (let offset = 0; offset < probes.length; offset += 1) {
       const index = (cursor + offset) % probes.length;
       const probe = probes[index]!;
-      const moved = refreshProbe(probe);
+      const moved = movedSinceCapture(probe);
       const mode = probe.mark.config.captureMode;
       const due =
         mode === 'realtime' ||
@@ -336,10 +356,15 @@ export function createReflectionProbeRegistry(
     update(frameToken) {
       if (disposed || frameToken === lastFrame || !canCaptureEnvironment(renderer)) return;
       lastFrame = frameToken;
-      for (const probe of probes) refreshProbe(probe);
+      let changed = false;
+      for (const probe of probes) {
+        const ready = probe.ready;
+        if (refreshProbe(probe) || probe.ready !== ready) changed = true;
+      }
       const due = nextCapture();
       if (due) capture(due);
-      notify(false);
+      // A capture opened a window (and published a result): closing it tells every observer.
+      if (due || changed) notify(false);
     },
     dispose() {
       if (disposed) return;