用途
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] }。
使用方式
- 检查
iwsdk.config.json、活动场景,以及仅拥有所请求自定义行为的源文件。 - 在启动开发服务器前完成第一轮配置、资产与场景编辑。常见路径无需调用场景能力、CLI
--help、搜索node_modules或检查生成的声明,除非编辑后仍有具体构建或运行时错误。 - 仅按需阅读一份随附参考:组件字段与尺寸见
references/component-reference.md;实现模式见references/workflows.md;材质或系统调参见references/tuning-and-config.md。 - 物理选项对象可指定执行模式或模拟速率,默认使用 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 运行时;上述命令、字段与配置项以原始资料为准。除资料中明确描述的内容外,其他平台支持、收费方式、性能指标或额外功能暂未提供。