XRift World 是用于在 XRift 平台上创建和修改 WebXR 世界的开发指南。
用途 该指南面向需要为 XRift 平台构建 WebXR 世界的开发者，说明如何创建、开发、配置并上传世界。世界会被上传至 CDN，并由前端动态加载。
技术栈 项目使用 React Three Fiber、Rapier 物理引擎与 Module Federation。XRift 相关能力由 @xrift/world-components 提供。
参考资料 指南提供以下参考：API Reference（@xrift/world-components 中所有 hooks、组件与常量的完整规范）、Code Templates（GLB 模型、纹理、Skybox、交互等实现模式）、Type Definitions（User、PlayerMovement、VRTrackingData、TeleportDestination、WorldInfo、InstanceInfo、ConfirmOptions、Tag、VideoState、LogEntry、PhysicsConfig、CameraConfig、VoiceVolumeOverrideContextValue 等类型定义）。
关键规则 加载资源时必须使用 useXRift() 提供的 baseUrl；资源文件放在 public/ 目录；baseUrl 末尾已包含 /，因此应拼接为 ${baseUrl}path，而不是 ${baseUrl}/path。
项目结构 模板目录包含 public/（资源文件，直接放置，无需子目录）、src/（components/ 3D 组件、World.tsx 主世界组件、dev.tsx 开发入口、index.tsx 生产导出、constants.ts 常量）、.triplex/（Triplex 3D 编辑器配置）、xrift.json（XRift CLI 配置）、vite.config.ts（Module Federation 构建配置）与 package.json。
xrift.json 配置 physics：gravity（重力强度，默认 9.81，地球 9.81、月球 1.62、木星 24.79）、allowInfiniteJump（是否允许无限跳跃，默认 true）。 camera：near（近裁剪距离）、far（远裁剪距离）。 outputBufferType：UnsignedByteType（8 位整数，默认）、HalfFloatType（16 位浮点，用于 HDR 与后处理）、FloatType（32 位浮点，最高精度，GPU 开销更高）。 items：通过 <Item itemId> 放置的用户创建物品 ID 列表，仅此处列出的 ID 会在生产环境加载，最多 50 个，只能声明自己创建或加入库的物品。 permissions：allowedDomains（世界通信的外部域名）、allowedCodeRules（放宽的代码安全规则）。
allowedCodeRules 由 @xrift/code-security 分析器定义，默认阻止不安全操作，可按需放宽，涵盖动态代码（no-eval、no-new-function、no-string-timeout、no-javascript-blob）、混淆（no-obfuscation）、网络（no-network-without-permission、no-unauthorized-domain、no-rtc-connection、no-external-import）、存储（no-storage-access、no-cookie-access、no-indexeddb-access、no-storage-event）、DOM（no-dangerous-dom）、浏览器 API（no-navigator-access）、全局（no-sensitive-api-override、no-global-override、no-prototype-pollution）等类别。
本地开发 在 vite.config.ts 中加入来自 @xrift/sdk/vite 的 xriftDev() 并运行 xrift login；DevEnvironment 会通过开发服务器代理（/__xrift）加载与生产相同的 bundle。若要同时开发物品与世界，可通过 <DevEnvironment items={{ [itemId]: Component }}> 传入本地组件。
命令 开发：npm run dev（启动开发服务器 http://localhost:5173）、npm run build（生产构建）、npm run typecheck（类型检查）。XRift CLI：xrift login（认证）、xrift create world（创建新世界项目）、xrift upload（上传，从 xrift.json 自动检测）、xrift whoami（查看登录用户）、xrift logout（登出）。
开发环境操作 运行 npm run dev 启动开发服务器，可以第一人称视角导航和测试世界。操作：点击锁定鼠标后移动鼠标环顾；W/A/S/D 移动；E 或 Space 上升、Q 下降；瞄准准星并点击交互；ESC 释放鼠标锁定。Interactable 组件的点击行为也可在开发环境测试（中心 Raycaster 检测 LAYERS.INTERACTABLE 层）。Grabbable 同样可用：G 抓取与放置，鼠标滚轮调整距离，点击确认。Seat 与 Vehicle 仅在开发环境注册自身，坐下需要 avatar、相机与物理，因此在世界运行于 XRift 之前不会生效。
dev.tsx 结构 src/dev.tsx 是仅用于开发的入口，不包含在生产构建中。生产环境不需要 XRiftProvider（前端会自动包裹）。
依赖 必需（peerDependencies）：react / react-dom ^19.0.0、three ^0.182.0、@react-three/fiber ^9.3.0、@react-three/drei ^10.7.3、@react-three/rapier ^2.1.0。XRift 专用：@xrift/world-components。
Module Federation 共享包 与宿主（xrift.net）通过 shared 共享的包。在世界 vite.config.ts 中声明为 shared 后，不会打包进世界 chunk，而由宿主提供。包括 react、react-dom、react-dom/client、react/jsx-runtime、three、three/addons/loaders/GLTFLoader.js、DRACOLoader.js、KTX2Loader.js、@react-three/fiber、@react-three/rapier、@react-three/drei、@react-three/uikit、@pmndrs/uikit、@xrift/world-components。注意：three/addons 的 barrel 若设为 shared 会把 Lottie 来源的 eval 包含进 bundle，因此按子路径声明 shared；世界侧也应按子路径 import 并声明 shared。
常见问题 “useXRift must be used within XRiftProvider”：未用 XRiftProvider 包裹，检查 src/dev.tsx 是否使用 XRiftProvider，使用 Triplex 时检查 .triplex/provider.tsx。资源加载失败：未使用 baseUrl 或路径拼接错误。物理不工作：未用 Physics 组件包裹或缺少 RigidBody。
示例实现 GLB 模型：src/components/Duck/index.tsx；Skybox：src/components/Skybox/index.tsx；动画：src/components/RotatingObject/index.tsx；交互：src/components/InteractableButton/index.tsx；用户追踪：src/components/RemoteUserHUDs/index.tsx；传送：src/components/TeleportPortal/index.tsx；主世界：src/World.tsx。
限制 资料未提供收费、价格、平台支持范围或效果保证等信息。