@hello-terrain/react 0.0.0-alpha.10

package/dist/index.mjs

@@ -0,0 +1,598 @@
+import { jsx } from 'react/jsx-runtime';
+import { terrainTasks, elevationFn, rootSize, origin, maxLevel, maxNodes, innerTileSegments, skirtScale, elevationScale, surface, terrainFieldFilter, quadtreeUpdate, terrainGraph, TerrainMesh } from '@hello-terrain/three';
+import { useFrame } from '@react-three/fiber';
+import { createContext, useContext, useRef, useLayoutEffect, useCallback, useMemo, useState, useEffect, isValidElement, cloneElement } from 'react';
+import { task } from '@hello-terrain/work';
+import { Vector3 } from 'three';
+
+const TerrainContext = createContext(null);
+function TerrainProvider({ value, children }) {
+  return /* @__PURE__ */ jsx(TerrainContext.Provider, { value, children });
+}
+function useTerrainContext() {
+  const value = useContext(TerrainContext);
+  if (!value) {
+    throw new Error("useTerrainContext must be used within a TerrainProvider");
+  }
+  return value;
+}
+
+function createSyncTerrainRuntimeTask(runtime) {
+  return task((get, work) => {
+    const query = get(terrainTasks.terrainQuery).query;
+    const raycast = get(terrainTasks.terrainRaycast);
+    return work(() => {
+      runtime.query = query;
+      runtime.raycast = raycast;
+      return runtime;
+    });
+  }).displayName("syncTerrainRuntimeTask").cache("none");
+}
+function createSyncTerrainNodesTask(getTerrainNodes, setTerrainNodes, getReady, setReady) {
+  return task((get, work) => {
+    const positionNode = get(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 = 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;
+  useLayoutEffect(() => {
+    ownedParamIdsRef.current.clear();
+  }, [graph]);
+  useLayoutEffect(() => {
+    const ownedParamIds = ownedParamIdsRef.current;
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      rootSize,
+      nextRootSize,
+      () => nextRootSize
+    );
+    resetOrSet(graph, ownedParamIds, origin, nextOrigin, () => ({
+      x: nextOrigin?.x ?? 0,
+      y: nextOrigin?.y ?? 0,
+      z: nextOrigin?.z ?? 0
+    }));
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      maxLevel,
+      nextMaxLevel,
+      () => nextMaxLevel
+    );
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      maxNodes,
+      nextMaxNodes,
+      () => nextMaxNodes
+    );
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      innerTileSegments,
+      nextInnerTileSegments,
+      () => nextInnerTileSegments
+    );
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      skirtScale,
+      nextSkirtScale,
+      () => nextSkirtScale
+    );
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      elevationScale,
+      nextElevationScale,
+      () => nextElevationScale
+    );
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      surface,
+      nextSurface,
+      () => nextSurface
+    );
+    resetOrSet(
+      graph,
+      ownedParamIds,
+      terrainFieldFilter,
+      nextTerrainFieldFilter,
+      () => nextTerrainFieldFilter
+    );
+    if (elevation === void 0) {
+      if (ownedParamIds.has(elevationFn.id)) {
+        graph.reset(elevationFn);
+        ownedParamIds.delete(elevationFn.id);
+      }
+    } else {
+      graph.set(elevationFn, () => elevation);
+      ownedParamIds.add(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 = useRef(graph);
+  const targetsRef = useRef(targets);
+  const getCameraOriginRef = useRef(getCameraOrigin);
+  const lastCameraOriginRef = useRef(null);
+  const runningRef = useRef(false);
+  const generationRef = useRef(0);
+  const runAbortControllerRef = useRef(null);
+  const runPromiseRef = useRef(null);
+  const lastErrorKeyRef = useRef(null);
+  const reportError = useCallback(
+    (error, errorKey) => {
+      const nextErrorKey = errorKey ?? getTerrainRunnerErrorKey(error);
+      if (lastErrorKeyRef.current === nextErrorKey) return;
+      lastErrorKeyRef.current = nextErrorKey;
+      console.error(error);
+    },
+    []
+  );
+  const clearError = useCallback(() => {
+    lastErrorKeyRef.current = null;
+  }, []);
+  const stopCurrentRun = 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 = useCallback(
+    (state, activeGraph) => {
+      const activeGetCameraOrigin = getCameraOriginRef.current;
+      const cameraOrigin = toVector3Like(state, activeGetCameraOrigin);
+      const nextOrigin = new Vector3(
+        cameraOrigin.x,
+        cameraOrigin.y,
+        cameraOrigin.z
+      );
+      const lastOrigin = lastCameraOriginRef.current;
+      const hysteresisSq = cameraHysteresis * cameraHysteresis;
+      if (!lastOrigin || lastOrigin.distanceToSquared(nextOrigin) >= hysteresisSq) {
+        activeGraph.set(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 = useCallback(
+    (activeRunController, activeGeneration) => {
+      if (runAbortControllerRef.current === activeRunController) {
+        runAbortControllerRef.current = null;
+        runPromiseRef.current = null;
+      }
+      if (generationRef.current === activeGeneration) {
+        runningRef.current = false;
+      }
+    },
+    []
+  );
+  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]);
+  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 = useMemo(
+    () => ({
+      query: null,
+      raycast: null
+    }),
+    []
+  );
+  const isMountedRef = useRef(true);
+  const graphLifecycleRef = useRef(0);
+  const terrainNodesRef = useRef({
+    positionNode: null
+  });
+  const [terrainNodes, setTerrainNodes] = useState(terrainNodesRef.current);
+  const readyRef = useRef(false);
+  const [ready, setReady] = useState(false);
+  const emitTerrainNodes = 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 = useCallback(
+    () => terrainNodesRef.current,
+    []
+  );
+  const emitReady = useCallback((nextReady) => {
+    if (!isMountedRef.current) return;
+    readyRef.current = nextReady;
+    setReady((prevReady) => prevReady === nextReady ? prevReady : nextReady);
+  }, []);
+  const getReady = useCallback(
+    () => readyRef.current,
+    []
+  );
+  const syncTerrainRuntimeTask = useMemo(
+    () => createSyncTerrainRuntimeTask(runtime),
+    [runtime]
+  );
+  const syncTerrainNodesTask = useMemo(
+    () => createSyncTerrainNodesTask(
+      getTerrainNodes,
+      emitTerrainNodes,
+      getReady,
+      emitReady
+    ),
+    [emitReady, emitTerrainNodes, getReady, getTerrainNodes]
+  );
+  const graph = useMemo(() => {
+    const nextGraph = terrainGraph();
+    for (const task of options.tasks ?? []) {
+      nextGraph.add(task);
+    }
+    nextGraph.add(syncTerrainRuntimeTask);
+    nextGraph.add(syncTerrainNodesTask);
+    return nextGraph;
+  }, [options.tasks, syncTerrainNodesTask, syncTerrainRuntimeTask]);
+  const runnerTargets = useMemo(
+    () => {
+      const userTasks = options.tasks ?? [];
+      return [
+        ...userTasks,
+        terrainTasks.executeCompute,
+        terrainTasks.terrainReadback,
+        syncTerrainRuntimeTask,
+        syncTerrainNodesTask
+      ];
+    },
+    [options.tasks, syncTerrainNodesTask, syncTerrainRuntimeTask]
+  );
+  const stopTerrainRunner = useTerrainRunner({
+    graph,
+    targets: runnerTargets,
+    getCameraOrigin: options.getCameraOrigin,
+    cameraHysteresis: options.cameraHysteresis
+  });
+  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]);
+  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 useMemo(
+    () => ({
+      graph,
+      tasks: terrainTasks,
+      runtime,
+      ready,
+      ...terrainNodes
+    }),
+    [graph, ready, runtime, terrainNodes]
+  );
+}
+
+function useTerrainMesh(innerTileSegments, maxNodes) {
+  const [mesh] = useState(
+    () => new TerrainMesh({
+      innerTileSegments: innerTileSegments ?? 13,
+      maxNodes: maxNodes ?? 1024
+    })
+  );
+  useEffect(() => {
+    mesh.innerTileSegments = innerTileSegments ?? 13;
+  }, [mesh, innerTileSegments]);
+  useEffect(() => {
+    mesh.maxNodes = maxNodes ?? 1024;
+  }, [mesh, maxNodes]);
+  useEffect(() => {
+    return () => {
+      mesh.geometry.dispose();
+    };
+  }, [mesh]);
+  return mesh;
+}
+function syncTerrainMesh(mesh, terrain) {
+  const leaves = terrain.graph.peek(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 (!isValidElement(node)) return node;
+  const nextKey = `terrain-material-${terrainNodes.positionNode?.id ?? "null"}`;
+  if ("attach" in node.props && node.props.attach != null) {
+    return cloneElement(node, { key: nextKey });
+  }
+  return cloneElement(node, { attach: "material", key: nextKey });
+}
+function TerrainWithHandle({
+  terrain,
+  children,
+  innerTileSegments,
+  maxNodes,
+  ...primitiveProps
+}) {
+  const mesh = useTerrainMesh(innerTileSegments, maxNodes);
+  const { visible: primitiveVisible = true, ...restPrimitiveProps } = primitiveProps;
+  useFrame(() => {
+    syncTerrainMesh(mesh, terrain);
+  });
+  return /* @__PURE__ */ jsx(TerrainProvider, { value: terrain, children: /* @__PURE__ */ 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__ */ 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__ */ jsx(
+      TerrainWithHandle,
+      {
+        terrain: providedTerrain,
+        innerTileSegments,
+        maxNodes,
+        ...primitiveProps,
+        children
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    InternalTerrain,
+    {
+      rootSize,
+      origin,
+      maxLevel,
+      innerTileSegments,
+      skirtScale,
+      elevationScale,
+      elevation,
+      surface,
+      terrainFieldFilter,
+      getCameraOrigin,
+      cameraHysteresis,
+      tasks,
+      maxNodes,
+      ...primitiveProps,
+      children
+    }
+  );
+}
+
+export { Terrain, TerrainProvider, useTerrain, useTerrainContext };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@hello-terrain/react",
+  "description": "High performance terrain system for three.js and react-three/fiber",
+  "homepage": "http://hello-terrain.kenny.wtf",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kenjinp/hello-terrain.git"
+  },
+  "version": "0.0.0-alpha.10",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@hello-terrain/three": "0.0.0-alpha.10",
+    "@hello-terrain/work": "0.3.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.2.0",
+    "@types/react": "^18.0.0 || ^19.0.0",
+    "@types/react-dom": "^18.0.0 || ^19.0.0",
+    "@types/three": ">=0.182.0",
+    "jsdom": "^26.0.0",
+    "unbuild": "^3.5.0",
+    "vitest": "^4.0.17",
+    "@config/oxfmt": "0.1.0",
+    "@config/typescript": "0.1.0",
+    "@config/oxlint": "0.1.0"
+  },
+  "peerDependencies": {
+    "@react-three/fiber": "^8.0.0 || ^9.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "three": ">=0.182.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "release": "pnpm run build && pnpm publish --access=public",
+    "test": "vitest",
+    "lint": "oxlint -c node_modules/@config/oxlint/react.json",
+    "format": "oxfmt -c node_modules/@config/oxfmt/base.json --write ."
+  }
+}