SuperAPI AI 工具集

iwsdk-physics

编程与开发

查看项目

更新于 11-17 00:29

技能介绍

用途

iwsdk-physics 是针对 IWSDK WebXR 项目的物理技能,用于添加或修复刚体模拟,包括重力、下落、碰撞、弹跳、运动学(kinematic)移动平台,以及物理感知的抓取(grab)行为。该技能以当前请求作为规格说明,优先使用脚手架的项目清单和原生场景组件,而非在 TypeScript 中重建物理系统。

主要能力

  • 世界物理开关:在 iwsdk.config.json 中将 world.features.physics 设为 true。脚手架已注册 PhysicsSystem、PhysicsBody、PhysicsShape 与 PhysicsManipulation,除非项目有意替换引导流程,否则不应重复注册。
  • 刚体与碰撞形状:每个参与碰撞的实体都需要同时具备 PhysicsBody 和 PhysicsShape。模拟下运动的物体使用 PhysicsBody.state: "DYNAMIC";固定地板或墙壁使用 "STATIC";由代码驱动的移动平台使用 "KINEMATIC"。形状需与可见几何一致:基本几何使用带明确尺寸的 Sphere、Box 或 Cylinder;动态复杂网格使用 ConvexHull,静态几何使用 TriMesh。
  • 材质调参:仅添加请求所需的材质调整,从低恢复系数和中等摩擦开始,避免用极端阻尼补偿缺失的碰撞体。
  • 可投掷与抓取:可投掷对象由动态刚体和形状配合请求的抓取组件构成。OneHandGrabbable 为近距离捏合抓取;距离抓取还需 RayInteractable 和 DistanceGrabbable。
  • 力与速度:通过 PhysicsManipulation 施加一次性力或速度。重置或传送已有刚体时使用 PhysicsSystem.setBodyTransform,使 Havok 与渲染变换保持同步。
  • 基本几何资产:从 @iwsdk/core 导入 Mesh、SphereGeometry、BoxGeometry、MeshStandardMaterial,构建无父级网格并加入现有 defineAssets({...}) 映射。渲染几何与碰撞体尺寸须一致:半径为 r 的球体使用 PhysicsShape: { shape: "Sphere", dimensions: [r, 0, 0] };尺寸为 [w, h, d] 的盒体使用 { shape: "Box", dimensions: [w, h, d] }。

使用方式

  1. 检查 iwsdk.config.json、活动场景,以及仅拥有所请求自定义行为的源文件。
  2. 在启动开发服务器前完成第一轮配置、资产与场景编辑。常见路径无需调用场景能力、CLI --help、搜索 node_modules 或检查生成的声明,除非编辑后仍有具体构建或运行时错误。
  3. 仅按需阅读一份随附参考:组件字段与尺寸见 references/component-reference.md;实现模式见 references/workflows.md;材质或系统调参见 references/tuning-and-config.md。
  4. 物理选项对象可指定执行模式或模拟速率,默认使用 Worker 执行;useWorker: false 在主线程上运行相同物理运行时与协议,用于兼容性和诊断。例如:
"physics": {
  "useWorker": true,
  "updateFrequency": 60,
  "interpolation": true
}

仅在需要时启用物理;若无对象需要动态模拟则省略以避免开销。

验证流程

运行一次生产构建,启动应用一次并检查指定的活动实体。对于下落、碰撞、力或运动学行为,在关键转变前暂停,拍摄前快照,步进少量固定帧,拍摄后快照并对比差异,查询最终变换和物理状态;空间布局重要时截取最终运行时图像。使用文档化的 CLI 形状直接执行:

npx @iwsdk/cli ecs pause --input-json '{}'
npx @iwsdk/cli ecs snapshot --input-json '{"label":"before"}'
npx @iwsdk/cli ecs step --input-json '{"count":8,"delta":0.016}'
npx @iwsdk/cli ecs snapshot --input-json '{"label":"after"}'
npx @iwsdk/cli ecs diff --input-json '{"from":"before","to":"after"}'
npx @iwsdk/cli ecs resume --input-json '{}'

若重力物体在桥接就绪时已静止,其静止变换加零运动步进差异可作为有效碰撞证据,不应仅为重现下落而传送该物体。

对于新组合的测试套件,对编写的 hero 视图运行一次场景渲染文件并最多检查该图像。有效可读的 hero 视图后,不再调用场景打开、场景状态或场景截图,也不创建替代编辑器视图。将最终实时浏览器截图保存到文件,但当 ECS 测量已证明所请求运动时不要回读。纯刚体验证无需进入 XR;编写的 hero 视图是构图证据,实时浏览器相机可能不同,不应仅为让截图匹配 hero 视图而临时编辑 iwsdk.config.json、重启运行时或渲染额外相机角度。使用 npx @iwsdk/cli browser screenshot --output-file <path> 直接保存实时截图,让编写的渲染负责有意取景。

最多进行一次聚焦修正,然后重放相同观察。当所请求的刚体、碰撞和最终状态均有证据时停止,恢复 ECS 时间并让应用保持稳定状态。

适用场景

适用于 IWSDK 构建的 WebXR 场景中需要刚体物理的交互,例如物体下落与堆叠、碰撞与弹跳、可推动的移动平台、可抓取并投掷的物品,以及通过力或速度驱动的物理交互。

限制

该技能依赖 IWSDK 脚手架及其已注册的物理组件与 Havok 运行时;上述命令、字段与配置项以原始资料为准。除资料中明确描述的内容外,其他平台支持、收费方式、性能指标或额外功能暂未提供。