react-three-fiber-game

React Three Fiber 游戏

概述

当 3D 运行时位于 React 应用中时，请使用此技能。这是插件中的默认 React 原生 3D 路径；如果应用外壳、设置、商店、编辑器界面或周边产品已使用 React，应优先选择此方案，而不是原生 Three.js。

推荐技术栈：

• @react-three/fiber
• three
• @react-three/drei
• @react-three/rapier
• @react-three/postprocessing
• 当交互对无障碍要求较高时，使用 @react-three/a11y
• 在常规 React 树中使用 DOM 叠加层

适用场景

• 项目已使用 React
• 3D 场景需要与应用其他部分共享状态
• 声明式场景组合能带来明显收益
• 团队希望使用 pmndrs 辅助工具，而不是手动构建每一层辅助功能

不适用场景

• 应用并非基于 React
• 项目需要更简洁的命令式运行时，并尽量减少与 React 的协调
• 问题在于资源打包，而非运行时组合

最适合的场景

• 3D 配置器和工具丰富的浏览器产品
• 嵌入游戏或场景界面的 React 应用
• 现有 React 应用中的 3D 菜单、编辑器或世界地图
• 依赖共享应用状态和非画布外壳的 3D 游戏 UI

核心规则

1. 将模拟状态保存在渲染组件之外。
   • React 组件应描述场景组合，而不应成为游戏规则的事实来源。
2. 有意地使用 React 状态和场景状态。
   • 共享 UI 状态可以放在应用状态中。
   • 高频模拟不应导致整个应用发生不必要的 React 更新。
3. 有目的地使用 pmndrs 辅助工具。
   • Drei 用于控件、加载器、辅助工具、环境和常见场景基元。
   • @react-three/rapier 用于物理集成。
   • @react-three/postprocessing 用于可选效果。
   • 当交互模型受益于具备无障碍支持的场景语义时，使用 @react-three/a11y。
4. 默认将 HUD、设置和菜单放在 DOM 中。
5. 保持起始脚手架的视觉设计克制。
   • 从一个紧凑的目标或状态界面以及临时提示开始。
   • 在打开笔记、地图和多步清单之前，先将它们折叠起来。
   • 不要在 Canvas 周围放置视觉权重相同的玻璃卡片。

架构指南

• 使用专用的场景根组件来管理 Canvas。
• 将摄像机装置和控制组件与游戏系统隔离。
• 让加载器和资源封装保持可预测。
• 通过明确的状态边界协调 DOM 叠加层与 3D 场景。
• 如果某个系统需要紧密的命令式控制，应将其隔离，而不是强迫所有内容都采用声明式模式。
• 如果场景可以立即游玩，应减少初始叠加层的数量，让游戏世界承担更多引导工作。

反模式

• 将 React 组件当作游戏状态存储
• 通过广泛的应用状态推动大量逐帧变更
• 仅仅因为可以使用 React 就采用 R3F，即使项目需要更简洁的命令式运行时
• 默认在 3D 场景中构建 HUD 或背包 UI
• 发布占据视口每一侧的大型卡片式起始脚手架

参考资料

• 共享架构：../web-game-foundations/SKILL.md
• 前端方向：../game-ui-frontend/SKILL.md
• 3D HUD 布局模式：../../references/three-hud-layout-patterns.md
• React Three Fiber 技术栈：../../references/react-three-fiber-stack.md
• React 起始模板：../../references/react-three-fiber-starter.md
• GLB 加载器起始模板：../../references/gltf-loading-starter.md
• Rapier 起始模板：../../references/rapier-integration-starter.md
• 3D 资源管线：../../references/web-3d-asset-pipeline.md
• WebGL 调试与性能：../../references/webgl-debugging-and-performance.md