@arronqzy/view-scene3d 0.1.2

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@arronqzy/view-scene3d",
+  "version": "0.1.2",
+  "description": "Shared 3D scene types and React/Vue renderers for Abuilder (R3F + Three.js)",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./react": "./src/react/index.ts",
+    "./react/ecosystem": "./src/react/ecosystem.ts",
+    "./vue": "./src/vue/Scene3dNodeContent.vue"
+  },
+  "dependencies": {
+    "@react-spring/three": "^9.7.5",
+    "@react-three/a11y": "^3.0.0",
+    "@react-three/cannon": "^6.6.0",
+    "@react-three/csg": "^3.0.0",
+    "@react-three/drei": "^9.122.0",
+    "@react-three/fiber": "^8.17.14",
+    "@react-three/flex": "^1.0.1",
+    "@react-three/gpu-pathtracer": "^0.3.2",
+    "@react-three/p2": "^0.0.6",
+    "@react-three/postprocessing": "^2.19.1",
+    "@react-three/rapier": "^1.4.0",
+    "@react-three/xr": "^5.7.1",
+    "@use-gesture/react": "^10.3.1",
+    "lamina": "^1.1.1",
+    "leva": "^0.9.35",
+    "maath": "^0.10.8",
+    "miniplex": "^2.0.0",
+    "postprocessing": "^6.36.0",
+    "three": "^0.172.0",
+    "three-stdlib": "^2.35.0",
+    "valtio": "^2.3.2",
+    "@arronqzy/i18n": "0.1.7"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "vue": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@react-three/gltfjsx": "^4.3.4",
+    "@react-three/test-renderer": "^8.2.1",
+    "@types/react": "^19.0.1",
+    "@types/three": "^0.172.0",
+    "typescript": "^5.5.4",
+    "@arronqzy/typescript-config": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "build": "pnpm run typecheck"
+  }
+}

package/src/animation.ts

@@ -0,0 +1,26 @@
+import type { Scene3dCameraState } from "./types";
+
+export function lerpCamera(
+  from: Scene3dCameraState,
+  to: Scene3dCameraState,
+  t: number
+): Scene3dCameraState {
+  const clamp = Math.min(1, Math.max(0, t));
+  const lerp3 = (a: [number, number, number], b: [number, number, number]) =>
+    [
+      a[0] + (b[0] - a[0]) * clamp,
+      a[1] + (b[1] - a[1]) * clamp,
+      a[2] + (b[2] - a[2]) * clamp,
+    ] as [number, number, number];
+  return {
+    position: lerp3(from.position, to.position),
+    target: lerp3(from.target, to.target),
+    fov: from.fov + (to.fov - from.fov) * clamp,
+    near: from.near,
+    far: from.far,
+  };
+}
+
+export function easeInOutCubic(t: number): number {
+  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}

package/src/defaults.ts

@@ -0,0 +1,149 @@
+import type {
+  Scene3dConfig,
+  Scene3dPresentation,
+  Scene3dPurpose,
+} from "./types";
+
+export function createDefaultPresentation(
+  purpose: Scene3dPurpose = "product"
+): Scene3dPresentation {
+  if (purpose === "twin") {
+    return {
+      purpose,
+      environmentPreset: "warehouse",
+      showContactShadows: true,
+      showGrid: true,
+      clickToFocus: true,
+      highlightOnHover: true,
+    };
+  }
+  if (purpose === "sandbox") {
+    return {
+      purpose,
+      environmentPreset: "none",
+      showContactShadows: false,
+      showGrid: true,
+      clickToFocus: true,
+      highlightOnHover: true,
+    };
+  }
+  return {
+    purpose: "product",
+    environmentPreset: "studio",
+    showContactShadows: true,
+    showGrid: false,
+    clickToFocus: true,
+    highlightOnHover: true,
+  };
+}
+
+export function purposePresetPatch(purpose: Scene3dPurpose): Partial<Scene3dConfig> {
+  const presentation = createDefaultPresentation(purpose);
+  if (purpose === "product") {
+    return {
+      presentation,
+      lighting: {
+        ambientIntensity: 0.35,
+        directionalIntensity: 1.4,
+        backgroundColor: "#0f1115",
+      },
+      orbit: {
+        enableMouseControl: true,
+        autoRotate: false,
+        autoRotateSpeed: 0.6,
+        enableDamping: true,
+      },
+      enableShadows: true,
+    };
+  }
+  if (purpose === "twin") {
+    return {
+      presentation,
+      lighting: {
+        ambientIntensity: 0.5,
+        directionalIntensity: 1.05,
+        backgroundColor: "#12161c",
+      },
+      orbit: {
+        enableMouseControl: true,
+        autoRotate: false,
+        autoRotateSpeed: 0.8,
+        enableDamping: true,
+      },
+      enableShadows: true,
+    };
+  }
+  return {
+    presentation,
+    lighting: {
+      ambientIntensity: 0.7,
+      directionalIntensity: 0.9,
+      backgroundColor: "#1a1f27",
+    },
+    orbit: {
+      enableMouseControl: true,
+      autoRotate: false,
+      autoRotateSpeed: 0.8,
+      enableDamping: true,
+    },
+    enableShadows: false,
+  };
+}
+
+export function createDefaultScene3dConfig(): Scene3dConfig {
+  return {
+    models: [],
+    camera: {
+      position: [4, 3, 6],
+      target: [0, 0.5, 0],
+      fov: 45,
+      near: 0.1,
+      far: 200,
+    },
+    orbit: {
+      enableMouseControl: true,
+      autoRotate: false,
+      autoRotateSpeed: 0.6,
+      enableDamping: true,
+    },
+    lighting: {
+      ambientIntensity: 0.35,
+      directionalIntensity: 1.4,
+      backgroundColor: "#0f1115",
+    },
+    presentation: createDefaultPresentation("product"),
+    modelAnimations: [],
+    cameraAnimations: [],
+    enableShadows: true,
+    hiddenObjectKeys: [],
+    soloObjectKey: null,
+    selectedObjectKey: null,
+    objectTags: [],
+  };
+}
+
+export function mergeScene3dConfig(
+  partial?: Partial<Scene3dConfig> | null
+): Scene3dConfig {
+  const base = createDefaultScene3dConfig();
+  if (!partial) return base;
+  return {
+    ...base,
+    ...partial,
+    camera: { ...base.camera, ...partial.camera },
+    orbit: { ...base.orbit, ...partial.orbit },
+    lighting: { ...base.lighting, ...partial.lighting },
+    presentation: { ...base.presentation, ...partial.presentation },
+    models: partial.models ?? base.models,
+    modelAnimations: partial.modelAnimations ?? base.modelAnimations,
+    cameraAnimations: partial.cameraAnimations ?? base.cameraAnimations,
+    hiddenObjectKeys: partial.hiddenObjectKeys ?? base.hiddenObjectKeys,
+    soloObjectKey:
+      partial.soloObjectKey === undefined ? base.soloObjectKey : partial.soloObjectKey,
+    selectedObjectKey:
+      partial.selectedObjectKey === undefined
+        ? base.selectedObjectKey
+        : partial.selectedObjectKey,
+    objectTags: partial.objectTags ?? base.objectTags,
+  };
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./types";
+export * from "./defaults";
+export * from "./model-names";
+export * from "./pivot";
+export * from "./animation";
+export * from "./object-state";

package/src/model-names.ts

@@ -0,0 +1,21 @@
+import type { Object3D } from "three";
+
+/** 收集 GLTF 场景中所有具名节点（mesh/group），供配置面板选择 */
+export function collectObjectNames(root: Object3D): string[] {
+  const names = new Set<string>();
+  root.traverse((obj) => {
+    if (obj.name && obj.name.trim()) {
+      names.add(obj.name.trim());
+    }
+  });
+  return Array.from(names).sort((a, b) => a.localeCompare(b));
+}
+
+export function inferModelFormat(fileName: string): "glb" | "gltf" | "obj" | "fbx" | "unknown" {
+  const lower = fileName.toLowerCase();
+  if (lower.endsWith(".glb")) return "glb";
+  if (lower.endsWith(".gltf")) return "gltf";
+  if (lower.endsWith(".obj")) return "obj";
+  if (lower.endsWith(".fbx")) return "fbx";
+  return "unknown";
+}

package/src/object-state.ts

@@ -0,0 +1,28 @@
+export const SCENE3D_OBJECT_KEY_SEP = "|||";
+
+export function makeScene3dObjectKey(modelId: string, objectName: string): string {
+  return `${modelId}${SCENE3D_OBJECT_KEY_SEP}${objectName}`;
+}
+
+export function parseScene3dObjectKey(
+  key: string | null | undefined
+): { modelId: string; objectName: string } | null {
+  if (!key) return null;
+  const index = key.indexOf(SCENE3D_OBJECT_KEY_SEP);
+  if (index < 0) return null;
+  return {
+    modelId: key.slice(0, index),
+    objectName: key.slice(index + SCENE3D_OBJECT_KEY_SEP.length),
+  };
+}
+
+export function isScene3dObjectVisible(options: {
+  modelId: string;
+  objectName: string;
+  hiddenObjectKeys?: string[];
+  soloObjectKey?: string | null;
+}): boolean {
+  const key = makeScene3dObjectKey(options.modelId, options.objectName);
+  if (options.soloObjectKey) return options.soloObjectKey === key;
+  return !options.hiddenObjectKeys?.includes(key);
+}

package/src/pivot.ts

@@ -0,0 +1,29 @@
+import { Box3, Vector3 } from "three";
+import type { Scene3dPivot } from "./types";
+
+export function getPivotWorldPoint(box: Box3, pivot: Scene3dPivot): Vector3 {
+  const center = new Vector3();
+  box.getCenter(center);
+  const { min, max } = box;
+  switch (pivot) {
+    case "left":
+      return new Vector3(min.x, center.y, center.z);
+    case "right":
+      return new Vector3(max.x, center.y, center.z);
+    case "front":
+      return new Vector3(center.x, center.y, max.z);
+    case "back":
+      return new Vector3(center.x, center.y, min.z);
+    case "top":
+      return new Vector3(center.x, max.y, center.z);
+    case "bottom":
+      return new Vector3(center.x, min.y, center.z);
+    case "center":
+    default:
+      return center.clone();
+  }
+}
+
+export function rotationSign(direction: "clockwise" | "counterclockwise"): number {
+  return direction === "clockwise" ? -1 : 1;
+}

package/src/react/Scene3dA11y.tsx

@@ -0,0 +1,23 @@
+import type { ReactNode } from "react";
+import { A11y, A11yAnnouncer } from "@react-three/a11y";
+
+type Scene3dA11yProps = {
+  description: string;
+  children: ReactNode;
+};
+
+/** 为 Canvas 内场景提供基础无障碍语义与播报。 */
+export function Scene3dA11y({ description, children }: Scene3dA11yProps) {
+  return (
+    <A11y role="contentinfo" description={description}>
+      {children}
+    </A11y>
+  );
+}
+
+/** A11yAnnouncer 会渲染 DOM，必须放在 Canvas 外。 */
+export function Scene3dA11yAnnouncer() {
+  return (
+    <A11yAnnouncer />
+  );
+}

package/src/react/Scene3dEffects.tsx

@@ -0,0 +1,14 @@
+import type { Scene3dPurpose } from "../types";
+
+type Scene3dEffectsProps = {
+  purpose: Scene3dPurpose;
+  enabled?: boolean;
+};
+
+/**
+ * 后处理会在切换场景用途时挂载/卸载 EffectComposer，容易把画布尺寸量错、画面缩到一角变空白。
+ * 产品展示的质感改由灯光和环境贴图承担，这里保持空实现以免切用途闪空白。
+ */
+export function Scene3dEffects(_props: Scene3dEffectsProps) {
+  return null;
+}