r3f-geometry

React Three Fiber 几何体

复制构造函数参数或辅助工具属性前，请检查已安装的 Three.js、Fiber 和 Drei 版本。示例面向 Fiber 9 / React 19 和 Three.js r185。

选择表示方式

• 普通形状使用原生 JSX 几何体。args 与 Three.js 构造函数参数一致；更改它们会重建几何体，因此应动画化变换，而不是构造函数输入。
• 自定义拓扑使用 BufferGeometry；大型粒子集使用基于缓冲区的 points。保持生成的数组稳定；需要结果可复现时，使用确定性生成方式。
• 需要便捷声明式实例并支持事件时，使用 Drei Instances。对于大型或频繁更新的实例集，请阅读 原生实例化，以避免逐实例的 React 开销。
• 实例化会共享几何体和材质，并减少绘制调用。仅让多个独立网格共享几何体，并不会合并它们的绘制调用。
• Drei Merged 会从网格创建实例化抽象，而不是从 BufferGeometry 对象创建；它不会拼接任意静态几何体。若要实际合并，请查看 three/addons/utils/BufferGeometryUtils.js 中的 mergeGeometries，并确保属性和索引兼容。

声明式实例

在 Canvas 下挂载并添加光照。每个 Instance 都属于距离最近的 Instances 提供器。

import { Instance, Instances } from '@react-three/drei'

export default function Example() {
  return (
    <Instances limit={3} range={3}>
      <boxGeometry args={[0.7, 0.7, 0.7]} />
      <meshStandardMaterial />
      <Instance position={[-1.2, 0, 0]} color="coral" />
      <Instance position={[0, 0, 0]} color="skyblue" />
      <Instance position={[1.2, 0, 0]} color="gold" />
    </Instances>
  )
}

自定义缓冲区和更新

• position 和 normal 属性的项目大小通常为 3；UV 的项目大小为 2。使用 args={[typedArray, itemSize]} 和正确的 attach 构造 JSX 缓冲区属性，不要只设置没有构造函数参数的 array/count 属性。
• 索引引用顶点；绕序决定正面。在硬法线或 UV 接缝处复制顶点。带索引的顶点会共享所有属性，而不仅仅是位置。
• 受光照的几何体需要法线。适当时使用 computeVertexNormals()；如果着色器或解析法线能以更低成本表示形变，就不要每帧重新计算。
• CPU 写入缓冲区后，设置 attribute.needsUpdate = true。如果缓冲区会频繁变化，应在首次上传到 GPU 前选择动态用法。
• 更改几何体并影响边界框或边界球后，请重新计算它们。GPU 顶点位移不会自动更新 CPU 边界或射线检测。
• 在现代 Three.js 中，UV 选择是显式的：texture.channel 用于选择 uv、uv1、uv2 或 uv3。不要无条件将 uv 复制到 uv2 来处理 AO。
• 避免因指针移动而重建缓冲区。如果拓扑固定，请改为更改属性内容或 uniforms。

辅助工具和权衡

• Drei Line 支持实用的线宽；原生 WebGL 线宽受平台限制。选择屏幕空间或世界空间粗细时，请检查 worldUnits。
• 平面文本使用 Drei Text，挤出几何体使用 Text3D。当前的 TextGeometry 使用 depth，而非旧版的 height；请核对已安装的辅助工具类型和字体格式。
• 使用 Edges 绘制锐边轮廓，不要用它替代屏幕空间选择效果。
• Bounds 和 Center 会改变取景或变换；请确定它们是否应在资源加载、调整大小或交互后更新。
• 细分数应根据轮廓、形变和观看距离来定。固定的“高质量”细分数并非总是更好。
• 以声明方式创建的几何体可以由 R3F 管理。共享或缓存的几何体需要采用共享生命周期；只要其他实例仍处于挂载状态，就不要从某个实例将其释放。

验证

更新后检查边界和剔除、射线检测命中位置、资源清理及绘制调用。请按预期对象数量进行测试；三个实例的测试结果不能证明一万个实例时的性能。

Sources

• BufferGeometry, BufferAttribute, InstancedMesh.
• Drei Instances, Merged, Text3D.