@hello-terrain/react 0.0.0-alpha.10

package/README.md

@@ -0,0 +1,85 @@
+# @hello-terrain/react
+
+React bindings for Hello Terrain, built for [react-three/fiber](https://r3f.docs.pmnd.rs/) and WebGPU.
+
+`@hello-terrain/react` wraps the core terrain graph from `@hello-terrain/three` with a React-first API:
+
+- `Terrain` renders the terrain mesh and connects node materials
+- `useTerrain()` creates and owns a `TerrainHandle`
+- `TerrainProvider` and `useTerrainContext()` share terrain state with sibling systems
+- `terrain.ready` and `terrain.runtime` make it easier to coordinate rendering, queries, and raycasts
+
+## Installation
+
+```bash
+pnpm add @hello-terrain/react @react-three/fiber three react react-dom
+```
+
+`@hello-terrain/react` depends on WebGPU and expects a `three/webgpu` renderer.
+
+## Basic Example
+
+```tsx
+import { Terrain } from "@hello-terrain/react";
+import { Canvas } from "@react-three/fiber";
+import type { WebGPURendererParameters } from "three/src/renderers/webgpu/WebGPURenderer.js";
+import { float } from "three/tsl";
+import * as THREE from "three/webgpu";
+
+const elevation = () => float(0);
+
+export function App() {
+  return (
+    <Canvas
+      gl={async (props) => {
+        const renderer = new THREE.WebGPURenderer(
+          props as WebGPURendererParameters,
+        );
+        await renderer.init();
+        return renderer;
+      }}
+      camera={{ position: [0, 30, 60] }}
+    >
+      <ambientLight intensity={0.15} />
+      <directionalLight intensity={1} position={[1, 1, 1]} />
+
+      <Terrain rootSize={1024} maxLevel={6} elevation={elevation}>
+        {({ positionNode }) => (
+          <meshStandardNodeMaterial positionNode={positionNode} />
+        )}
+      </Terrain>
+    </Canvas>
+  );
+}
+```
+
+## When To Use `useTerrain()`
+
+Use `Terrain` by itself for the smallest setup. Reach for `useTerrain()` when you want to:
+
+- reuse the same terrain handle across multiple components
+- access `terrain.runtime.query` or `terrain.runtime.raycast`
+- share terrain state with sibling systems like controllers or cameras
+- inspect the underlying graph or provide custom graph tasks
+
+## Public API
+
+- `Terrain`
+- `useTerrain`
+- `TerrainProvider`
+- `useTerrainContext`
+- `TerrainHandle`
+- `TerrainOptions`
+- `TerrainRuntime`
+- `TerrainTask`
+
+## Docs
+
+- [Introduction](http://hello-terrain.kenny.wtf/docs)
+- [Installation](http://hello-terrain.kenny.wtf/docs/installation)
+- [React Overview](http://hello-terrain.kenny.wtf/docs/react)
+- [Examples](http://hello-terrain.kenny.wtf/examples)
+
+## Support
+
+For support, join the [Discord server](https://discord.gg/HgTd2B828n).

package/dist/index.cjs

@@ -0,0 +1,603 @@
+'use strict';
+
+const jsxRuntime = require('react/jsx-runtime');
+const three = require('@hello-terrain/three');
+const fiber = require('@react-three/fiber');
+const react = require('react');
+const work = require('@hello-terrain/work');
+const three$1 = require('three');
+
+const TerrainContext = react.createContext(null);
+function TerrainProvider({ value, children }) {
+  return /* @__PURE__ */ jsxRuntime.jsx(TerrainContext.Provider, { value, children });
+}
+function useTerrainContext() {
+  const value = react.useContext(TerrainContext);
+  if (!value) {
+    throw new Error("useTerrainContext must be used within a TerrainProvider");
+  }
+  return value;
+}
+
+function createSyncTerrainRuntimeTask(runtime) {
+  return work.task((get, work) => {
+    const query = get(three.terrainTasks.terrainQuery).query;
+    const raycast = get(three.terrainTasks.terrainRaycast);
+    return work(() => {
+      runtime.query = query;
+      runtime.raycast = raycast;
+      return runtime;
+    });
+  }).displayName("syncTerrainRuntimeTask").cache("none");
+}
+function createSyncTerrainNodesTask(getTerrainNodes, setTerrainNodes, getReady, setReady) {
+  return work.task((get, work) => {
+    const positionNode = get(three.terrainTasks.positionNode);
+    return work(() => {
+      const nextReady = positionNode != null;
+      const terrainNodes = getTerrainNodes();
+      if (terrainNodes.positionNode !== positionNode) {
+        setTerrainNodes({
+          positionNode
+        });
+      }
+      if (getReady() !== nextReady) {
+        setReady(nextReady);
+      }
+      return {
+        positionNode,
+        ready: nextReady
+      };
+    });
+  }).displayName("syncTerrainNodesTask").cache("none");
+}
+
+function resetOrSet(graph, ownedParamIds, ref, value, setValue) {
+  if (value === void 0) {
+    if (ownedParamIds.has(ref.id)) {
+      graph.reset(ref);
+      ownedParamIds.delete(ref.id);
+    }
+    return;
+  }
+  graph.set(ref, setValue);
+  ownedParamIds.add(ref.id);
+}
+function useTerrainParams(graph, options) {
+  const ownedParamIdsRef = react.useRef(/* @__PURE__ */ new Set());
+  const {
+    rootSize: nextRootSize,
+    origin: nextOrigin,
+    maxLevel: nextMaxLevel,
+    maxNodes: nextMaxNodes,
+    innerTileSegments: nextInnerTileSegments,
+    skirtScale: nextSkirtScale,
+    elevationScale: nextElevationScale,
+    elevation,
+    surface: nextSurface,
+    terrainFieldFilter: nextTerrainFieldFilter
+  } = options;
+  react.useLayoutEffect(() => {
+    ownedParamIdsRef.current.clear();
+  }, [graph]);
+  react.useLayoutEffect(() => {
+    const ownedParamIds = ownedParamIdsRef.current;
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      three.rootSize,
+      nextRootSize,
+      () => nextRootSize
+    );
+    resetOrSet(graph, ownedParamIds, three.origin, nextOrigin, () => ({
+      x: nextOrigin?.x ?? 0,
+      y: nextOrigin?.y ?? 0,
+      z: nextOrigin?.z ?? 0
+    }));
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      three.maxLevel,
+      nextMaxLevel,
+      () => nextMaxLevel
+    );
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      three.maxNodes,
+      nextMaxNodes,
+      () => nextMaxNodes
+    );
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      three.innerTileSegments,
+      nextInnerTileSegments,
+      () => nextInnerTileSegments
+    );
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      three.skirtScale,
+      nextSkirtScale,
+      () => nextSkirtScale
+    );
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      three.elevationScale,
+      nextElevationScale,
+      () => nextElevationScale
+    );
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      three.surface,
+      nextSurface,
+      () => nextSurface
+    );
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      three.terrainFieldFilter,
+      nextTerrainFieldFilter,
+      () => nextTerrainFieldFilter
+    );
+    if (elevation === void 0) {
+      if (ownedParamIds.has(three.elevationFn.id)) {
+        graph.reset(three.elevationFn);
+        ownedParamIds.delete(three.elevationFn.id);
+      }
+    } else {
+      graph.set(three.elevationFn, () => elevation);
+      ownedParamIds.add(three.elevationFn.id);
+    }
+  }, [
+    graph,
+    nextRootSize,
+    nextOrigin,
+    nextMaxLevel,
+    nextMaxNodes,
+    nextInnerTileSegments,
+    nextSkirtScale,
+    nextElevationScale,
+    elevation,
+    nextSurface,
+    nextTerrainFieldFilter
+  ]);
+}
+
+const WEBGPU_RENDERER_ERROR = "@hello-terrain/react requires a WebGPURenderer on <Canvas gl={...}>.";
+const GRAPH_RUN_ERROR = "@hello-terrain/react terrain graph run failed.";
+function toVector3Like(state, getCameraOrigin) {
+  return getCameraOrigin?.(state) ?? state.camera.position;
+}
+function getTerrainRunnerErrorKey(error) {
+  if (error instanceof Error) {
+    return `${error.name}:${error.message}`;
+  }
+  return String(error);
+}
+function isWebGpuRenderer(renderer) {
+  return typeof renderer === "object" && renderer !== null && "backend" in renderer;
+}
+function useTerrainRunner({
+  graph,
+  targets,
+  getCameraOrigin,
+  cameraHysteresis = 0.05
+}) {
+  const graphRef = react.useRef(graph);
+  const targetsRef = react.useRef(targets);
+  const getCameraOriginRef = react.useRef(getCameraOrigin);
+  const lastCameraOriginRef = react.useRef(null);
+  const runningRef = react.useRef(false);
+  const generationRef = react.useRef(0);
+  const runAbortControllerRef = react.useRef(null);
+  const runPromiseRef = react.useRef(null);
+  const lastErrorKeyRef = react.useRef(null);
+  const reportError = react.useCallback(
+    (error, errorKey) => {
+      const nextErrorKey = errorKey ?? getTerrainRunnerErrorKey(error);
+      if (lastErrorKeyRef.current === nextErrorKey) return;
+      lastErrorKeyRef.current = nextErrorKey;
+      console.error(error);
+    },
+    []
+  );
+  const clearError = react.useCallback(() => {
+    lastErrorKeyRef.current = null;
+  }, []);
+  const stopCurrentRun = react.useCallback(async () => {
+    const activeController = runAbortControllerRef.current;
+    if (activeController && !activeController.signal.aborted) {
+      activeController.abort(new Error("Terrain runner stopped"));
+    }
+    const activeRun = runPromiseRef.current;
+    if (activeRun) {
+      await activeRun.catch(() => {
+      });
+    }
+  }, []);
+  const updateCameraOrigin = react.useCallback(
+    (state, activeGraph) => {
+      const activeGetCameraOrigin = getCameraOriginRef.current;
+      const cameraOrigin = toVector3Like(state, activeGetCameraOrigin);
+      const nextOrigin = new three$1.Vector3(
+        cameraOrigin.x,
+        cameraOrigin.y,
+        cameraOrigin.z
+      );
+      const lastOrigin = lastCameraOriginRef.current;
+      const hysteresisSq = cameraHysteresis * cameraHysteresis;
+      if (!lastOrigin || lastOrigin.distanceToSquared(nextOrigin) >= hysteresisSq) {
+        activeGraph.set(three.quadtreeUpdate, (prev) => {
+          prev.cameraOrigin.x = nextOrigin.x;
+          prev.cameraOrigin.y = nextOrigin.y;
+          prev.cameraOrigin.z = nextOrigin.z;
+          return prev;
+        });
+        lastCameraOriginRef.current = nextOrigin;
+      }
+    },
+    [cameraHysteresis]
+  );
+  const finishRun = react.useCallback(
+    (activeRunController, activeGeneration) => {
+      if (runAbortControllerRef.current === activeRunController) {
+        runAbortControllerRef.current = null;
+        runPromiseRef.current = null;
+      }
+      if (generationRef.current === activeGeneration) {
+        runningRef.current = false;
+      }
+    },
+    []
+  );
+  react.useLayoutEffect(() => {
+    void stopCurrentRun();
+    graphRef.current = graph;
+    targetsRef.current = targets;
+    getCameraOriginRef.current = getCameraOrigin;
+    lastCameraOriginRef.current = null;
+    runningRef.current = false;
+    generationRef.current += 1;
+    clearError();
+    return () => {
+      generationRef.current += 1;
+      runningRef.current = false;
+      void stopCurrentRun();
+    };
+  }, [clearError, getCameraOrigin, graph, stopCurrentRun, targets]);
+  fiber.useFrame((state) => {
+    if (runningRef.current) return;
+    const renderer = state.gl;
+    if (!isWebGpuRenderer(renderer)) {
+      reportError(
+        new Error(WEBGPU_RENDERER_ERROR),
+        `renderer:${WEBGPU_RENDERER_ERROR}`
+      );
+      return;
+    }
+    const activeGeneration = generationRef.current;
+    const activeRunController = new AbortController();
+    runningRef.current = true;
+    runAbortControllerRef.current = activeRunController;
+    const runPromise = (async () => {
+      try {
+        const activeGraph = graphRef.current;
+        const activeTargets = targetsRef.current;
+        updateCameraOrigin(state, activeGraph);
+        const report = await activeGraph.run({
+          targets: activeTargets,
+          signal: activeRunController.signal,
+          resources: {
+            renderer
+          }
+        });
+        if (report.status === "error") {
+          reportError(new Error(GRAPH_RUN_ERROR), `graph:${GRAPH_RUN_ERROR}`);
+          return;
+        }
+        clearError();
+      } catch (error) {
+        if (activeRunController.signal.aborted) return;
+        reportError(error);
+      } finally {
+        finishRun(activeRunController, activeGeneration);
+      }
+    })();
+    runPromiseRef.current = runPromise;
+  });
+  return stopCurrentRun;
+}
+
+function useTerrain(options = {}) {
+  const runtime = react.useMemo(
+    () => ({
+      query: null,
+      raycast: null
+    }),
+    []
+  );
+  const isMountedRef = react.useRef(true);
+  const graphLifecycleRef = react.useRef(0);
+  const terrainNodesRef = react.useRef({
+    positionNode: null
+  });
+  const [terrainNodes, setTerrainNodes] = react.useState(terrainNodesRef.current);
+  const readyRef = react.useRef(false);
+  const [ready, setReady] = react.useState(false);
+  const emitTerrainNodes = react.useCallback(
+    (nextTerrainNodes) => {
+      if (!isMountedRef.current) return;
+      setTerrainNodes((prevTerrainNodes) => {
+        if (prevTerrainNodes.positionNode === nextTerrainNodes.positionNode) {
+          terrainNodesRef.current = prevTerrainNodes;
+          return prevTerrainNodes;
+        }
+        terrainNodesRef.current = nextTerrainNodes;
+        return nextTerrainNodes;
+      });
+    },
+    []
+  );
+  const getTerrainNodes = react.useCallback(
+    () => terrainNodesRef.current,
+    []
+  );
+  const emitReady = react.useCallback((nextReady) => {
+    if (!isMountedRef.current) return;
+    readyRef.current = nextReady;
+    setReady((prevReady) => prevReady === nextReady ? prevReady : nextReady);
+  }, []);
+  const getReady = react.useCallback(
+    () => readyRef.current,
+    []
+  );
+  const syncTerrainRuntimeTask = react.useMemo(
+    () => createSyncTerrainRuntimeTask(runtime),
+    [runtime]
+  );
+  const syncTerrainNodesTask = react.useMemo(
+    () => createSyncTerrainNodesTask(
+      getTerrainNodes,
+      emitTerrainNodes,
+      getReady,
+      emitReady
+    ),
+    [emitReady, emitTerrainNodes, getReady, getTerrainNodes]
+  );
+  const graph = react.useMemo(() => {
+    const nextGraph = three.terrainGraph();
+    for (const task of options.tasks ?? []) {
+      nextGraph.add(task);
+    }
+    nextGraph.add(syncTerrainRuntimeTask);
+    nextGraph.add(syncTerrainNodesTask);
+    return nextGraph;
+  }, [options.tasks, syncTerrainNodesTask, syncTerrainRuntimeTask]);
+  const runnerTargets = react.useMemo(
+    () => {
+      const userTasks = options.tasks ?? [];
+      return [
+        ...userTasks,
+        three.terrainTasks.executeCompute,
+        three.terrainTasks.terrainReadback,
+        syncTerrainRuntimeTask,
+        syncTerrainNodesTask
+      ];
+    },
+    [options.tasks, syncTerrainNodesTask, syncTerrainRuntimeTask]
+  );
+  const stopTerrainRunner = useTerrainRunner({
+    graph,
+    targets: runnerTargets,
+    getCameraOrigin: options.getCameraOrigin,
+    cameraHysteresis: options.cameraHysteresis
+  });
+  react.useEffect(() => {
+    graphLifecycleRef.current += 1;
+    const lifecycle = graphLifecycleRef.current;
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+      queueMicrotask(() => {
+        if (graphLifecycleRef.current !== lifecycle) return;
+        void stopTerrainRunner().finally(() => {
+          if (graphLifecycleRef.current !== lifecycle) return;
+          graph.dispose();
+        });
+      });
+    };
+  }, [graph, stopTerrainRunner]);
+  react.useLayoutEffect(() => {
+    runtime.query = null;
+    runtime.raycast = null;
+    const nextTerrainNodes = {
+      positionNode: null
+    };
+    terrainNodesRef.current = nextTerrainNodes;
+    readyRef.current = false;
+    setTerrainNodes(nextTerrainNodes);
+    setReady(false);
+  }, [graph, runtime]);
+  useTerrainParams(graph, options);
+  return react.useMemo(
+    () => ({
+      graph,
+      tasks: three.terrainTasks,
+      runtime,
+      ready,
+      ...terrainNodes
+    }),
+    [graph, ready, runtime, terrainNodes]
+  );
+}
+
+function useTerrainMesh(innerTileSegments, maxNodes) {
+  const [mesh] = react.useState(
+    () => new three.TerrainMesh({
+      innerTileSegments: innerTileSegments ?? 13,
+      maxNodes: maxNodes ?? 1024
+    })
+  );
+  react.useEffect(() => {
+    mesh.innerTileSegments = innerTileSegments ?? 13;
+  }, [mesh, innerTileSegments]);
+  react.useEffect(() => {
+    mesh.maxNodes = maxNodes ?? 1024;
+  }, [mesh, maxNodes]);
+  react.useEffect(() => {
+    return () => {
+      mesh.geometry.dispose();
+    };
+  }, [mesh]);
+  return mesh;
+}
+function syncTerrainMesh(mesh, terrain) {
+  const leaves = terrain.graph.peek(three.terrainTasks.quadtreeUpdate);
+  if (leaves && mesh.count !== leaves.count) {
+    mesh.count = leaves.count;
+    mesh.instanceMatrix.needsUpdate = true;
+  }
+  const raycast = terrain.runtime.raycast;
+  if (mesh.terrainRaycast !== raycast) {
+    mesh.terrainRaycast = raycast;
+  }
+}
+function attachTerrainMaterial(node, terrainNodes) {
+  if (!react.isValidElement(node)) return node;
+  const nextKey = `terrain-material-${terrainNodes.positionNode?.id ?? "null"}`;
+  if ("attach" in node.props && node.props.attach != null) {
+    return react.cloneElement(node, { key: nextKey });
+  }
+  return react.cloneElement(node, { attach: "material", key: nextKey });
+}
+function TerrainWithHandle({
+  terrain,
+  children,
+  innerTileSegments,
+  maxNodes,
+  ...primitiveProps
+}) {
+  const mesh = useTerrainMesh(innerTileSegments, maxNodes);
+  const { visible: primitiveVisible = true, ...restPrimitiveProps } = primitiveProps;
+  fiber.useFrame(() => {
+    syncTerrainMesh(mesh, terrain);
+  });
+  return /* @__PURE__ */ jsxRuntime.jsx(TerrainProvider, { value: terrain, children: /* @__PURE__ */ jsxRuntime.jsx(
+    "primitive",
+    {
+      object: mesh,
+      visible: terrain.ready && primitiveVisible,
+      ...restPrimitiveProps,
+      children: terrain.ready ? attachTerrainMaterial(
+        children({
+          positionNode: terrain.positionNode
+        }),
+        terrain
+      ) : null
+    }
+  ) });
+}
+function InternalTerrain(props) {
+  const {
+    children,
+    rootSize,
+    origin,
+    maxLevel,
+    innerTileSegments,
+    skirtScale,
+    elevationScale,
+    elevation,
+    surface,
+    terrainFieldFilter,
+    getCameraOrigin,
+    cameraHysteresis,
+    tasks,
+    maxNodes,
+    ...primitiveProps
+  } = props;
+  const terrain = useTerrain({
+    rootSize,
+    origin,
+    maxLevel,
+    innerTileSegments,
+    skirtScale,
+    elevationScale,
+    elevation,
+    surface,
+    terrainFieldFilter,
+    getCameraOrigin,
+    cameraHysteresis,
+    tasks,
+    maxNodes
+  });
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    TerrainWithHandle,
+    {
+      terrain,
+      innerTileSegments,
+      maxNodes,
+      ...primitiveProps,
+      children
+    }
+  );
+}
+function Terrain({
+  terrain: providedTerrain,
+  children,
+  rootSize,
+  origin,
+  maxLevel,
+  innerTileSegments,
+  skirtScale,
+  elevationScale,
+  elevation,
+  surface,
+  terrainFieldFilter,
+  getCameraOrigin,
+  cameraHysteresis,
+  tasks,
+  maxNodes,
+  ...primitiveProps
+}) {
+  if (providedTerrain) {
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      TerrainWithHandle,
+      {
+        terrain: providedTerrain,
+        innerTileSegments,
+        maxNodes,
+        ...primitiveProps,
+        children
+      }
+    );
+  }
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    InternalTerrain,
+    {
+      rootSize,
+      origin,
+      maxLevel,
+      innerTileSegments,
+      skirtScale,
+      elevationScale,
+      elevation,
+      surface,
+      terrainFieldFilter,
+      getCameraOrigin,
+      cameraHysteresis,
+      tasks,
+      maxNodes,
+      ...primitiveProps,
+      children
+    }
+  );
+}
+
+exports.Terrain = Terrain;
+exports.TerrainProvider = TerrainProvider;
+exports.useTerrain = useTerrain;
+exports.useTerrainContext = useTerrainContext;