CIMCubeSDK v3.58.0 Class: ScenePhysics

new ScenePhysics(scene)

Parameters:

Name	Type	Description
`scene`	Glodon.CIMCube.Scene	场景实例

Members

coordinates

物理坐标转换（ENU ↔ 世界坐标）

<readonly> enabled :boolean

物理引擎是否已开启

Type:

boolean

Methods

addAfterStepListener(listener)

监听物理步进结束

Parameters:

Name	Type	Description
`listener`	function

addDistanceConstraint(bodyA, pivotA, bodyB, pivotB [, options])

添加距离约束：只限制两锚点间距落在区间内；不锁重合、不锁朝向（绳索 / 吊索 / 定长缆）

Parameters:

Name Type Argument Description

bodyA Object 刚体 A 句柄

pivotA Array.<number> A 模型局部锚点 [x, y, z]（米）

bodyB Object 刚体 B 句柄

pivotB Array.<number> B 模型局部锚点 [x, y, z]（米）

options

Object

Properties

Name	Type	Argument	Default	Description
`minDistance`	number	<optional>	0	最小间距（米）
`maxDistance`	number	<optional>		最大间距（米）；省略时取创建瞬间两锚点距离
`bias`	number	<optional>	0.1	越界校正强度（0~1）；越大越强力拉回区间
`stiffness`	number	<optional>		越界弹簧刚度（N/m）
`damping`	number	<optional>		沿缆绳方向的相对速度阻尼（N·s/m）；增大可减轻绷紧回弹

Returns:

约束句柄 `{ constraint, type:'distance', isDistance, limits }`

Type: Object | null

Example

// 定长缆：min = max
const cable = physics.addDistanceConstraint(crane, [0, -2, 0], hook, [0, 0.2, 0], {
  minDistance: 3,
  maxDistance: 3
});

// 可伸缩吊索：0 ~ 5 m
const sling = physics.addDistanceConstraint(bodyA, pivotA, bodyB, pivotB, {
  minDistance: 0,
  maxDistance: 5
});

// 低反弹绳索
const sling = physics.addDistanceConstraint(bodyA, pivotA, bodyB, pivotB, {
  minDistance: 0,
  maxDistance: 5
  bias: 0.1,
  stiffness: 200,
  damping: 40
});

addFixedJoint(bodyA, bodyB [, frameA] [, frameB] [, options])

添加固定关节（焊接）：锁定全部 6 自由度 —— 两刚体无相对位移、无相对旋转，运动学上等价于同一个刚体。 frame：刚体**局部**关节帧 `{ position?, rotation? }`（与 ScenePhysics#addSliderConstraint 同约定） - `position`：局部锚点 `[x, y, z]`（米） - `rotation`：关节帧姿态四元数 `[x, y, z, w]`；省略为单位帧帧的三种用法： - **双侧都传**：按传入帧建立关节；两侧帧在世界中不重合时，求解器会把它们拉到一起 - **只传一侧**：另一侧自动补出与该帧世界重合的帧（不改变当前相对位姿，锚点取传入帧） - **都不传**：锁定**当前**相对位姿（A 帧取单位帧，B 帧取 A 体原点在 B 局部中的当前位姿）注意： - 动态体 × 静态体 = 刚性锚（把部件钉在底座 / 世界上） - 焊接后两刚体之间默认不再产生碰撞（`disableCollisionsBetweenLinkedBodies`） - 过冲量超过 `breakingImpulseThreshold` 时 Bullet 会自动禁用该约束（即断焊，两部件散开）；主动拆焊 / 复焊请用 ScenePhysics#setFixedJointEnabled - 固定关节没有可驱动的自由度，故不提供交互 Gizmo（ScenePhysics#createJointGizmo 会返回 null） - 焊接为 Bullet 6DOF 限位求解，属"近似刚性"：默认 `stopErp = 0.2`，大负载下会有可见下垂（实测 50kg 悬吊 2m ≈ 2.7cm 下垂）。若要求焊接观感更刚，可传 `stopErp: 0.8 ~ 1.5` （实测同工况降到 ≈ 0.4 ~ 1.1cm，稳态无抖动）

Parameters:

Name Type Argument Description

bodyA Object 刚体 A 句柄（`createBox` / `setCollisionModel` 等返回值，或含 `body` 的对象）

bodyB Object 刚体 B 句柄（同上）

frameA Object <optional> A 局部关节帧

frameB Object <optional> B 局部关节帧

options

Object

Properties

Name	Type	Argument	Default	Description
`useLinearReferenceFrameA`	boolean	<optional>	true	线性限位参考帧是否取 A；纯固定关节下两者等价
`disableCollisionsBetweenLinkedBodies`	boolean	<optional>	true	是否关闭两刚体间碰撞
`stopErp`	number	<optional>		限位纠偏系数（`BT_CONSTRAINT_STOP_ERP`）；默认 `0.2`，越高焊接越刚
`stopCfm`	number	<optional>		限位约束力混合（`BT_CONSTRAINT_STOP_CFM`）；默认 `0`
`breakingImpulseThreshold`	number	<optional>		断裂冲量阈值；超过后约束自动失效

See:

ScenePhysics#setFixedJointEnabled
ScenePhysics#addHinge
ScenePhysics#addSliderConstraint

Returns:

固定关节句柄；世界未加载时返回 `null`。字段： - `constraint`：Ammo `btGeneric6DofConstraint` - `type`：`'fixed'` - `isFixed`：`true` - `bodyA` / `bodyB`：两侧刚体句柄 - `frameA` / `frameB`：解析后的关节帧 `{ position, rotation }`（体局部） - `pivotABodyLocal` / `pivotBBodyLocal`：两侧体局部锚点 - `rotationABodyLocal` / `rotationBBodyLocal`：两侧体局部帧姿态 - `lockCurrentPose`：是否由「锁定当前相对位姿」自动推导所得 - `disableCollisionsBetweenLinkedBodies`：当前是否关闭两刚体间碰撞

Type: Object | null

Example

// 1) 焊接当前姿态（最常用）：子部件保持与父部件的当前相对位置 / 朝向
const weld = physics.addFixedJoint(root, part);

// 2) 指定焊接点：双侧局部帧
const weld2 = physics.addFixedJoint(parent, child, {
  position: [0, 1.2, 0],
  rotation: [0, 0, 0, 1]
}, {
  position: [0, 0, 0],
  rotation: [0, 0, 0, 1]
});

// 3) 钉在世界 / 底座上：静态体 + 固定关节 = 刚性锚
const anchor = physics.addFixedJoint(groundStatic, mast, {
  position: [0, 0, 0],
  rotation: [0, 0, 0, 1]
}, {
  position: [0, 0, 0],
  rotation: [0, 0, 0, 1]
});

// 4) 可断焊：冲量超过阈值后约束失效
const weld3 = physics.addFixedJoint(a, b, null, null, { breakingImpulseThreshold: 500 });

// 5) 运行时拆焊 / 复焊
physics.setFixedJointEnabled(weld, false);

addHinge(bodyA, bodyB, frameA, frameB [, options])

添加铰链约束（门、合页、翻盖、转臂） frame：刚体局部关节位姿 { position?, rotation?, axis? } - position：局部锚点 - rotation：关节帧姿态（相对刚体；模型/附件初始朝向、副轴零位） - axis：局部铰链轴（刚体局部系）

Parameters:

Name Type Argument Description

bodyA Object 刚体 A 句柄（或 btRigidBody）

bodyB Object 刚体 B 句柄（或 btRigidBody）

frameA Object A 局部关节帧

frameB Object B 局部关节帧

options

Object

角度限位等

Properties

Name	Type	Argument	Default	Description
`low`	number	<optional>		下限角（rad）
`high`	number	<optional>		上限角（rad）
`softness`	number	<optional>	0.9	软刚度（0~1）
`biasFactor`	number	<optional>	0.3	偏置因子（0~1）
`relaxationFactor`	number	<optional>	1.0	松弛因子（0~1）
`useReferenceFrameA`	boolean	<optional>	true	是否以 A 帧为参考

Returns:

铰链句柄 { constraint, isHinge, motor }

Type: Object | null

addPoint2PointJoint(bodyA, pivotA, bodyB, pivotB)

添加球铰 / 点对点约束：锚点强制重合；允许三轴自由旋转，禁止平移（链条、吊绳、摆）

Parameters:

Name	Type	Description
`bodyA`	Object	刚体 A 句柄
`pivotA`	Array.<number>	A 局部锚点 [x, y, z]（ENU，米）
`bodyB`	Object	刚体 B 句柄
`pivotB`	Array.<number>	B 局部锚点 [x, y, z]（ENU，米）

See:

ScenePhysics#createJointGizmo

Returns:

约束句柄 { constraint, type:'point2point', isPoint2Point }

Type: Object

addSliderConstraint(bodyA, bodyB, frameA, frameB [, options])

添加滑块（棱柱）约束：沿滑动轴平移，可限制行程；可选绕轴自转（升降、活塞、推拉门、伸缩臂）

Parameters:

Name Type Argument Description

bodyA Object 刚体 A 句柄（`createBox` 等返回值，或含 `body` 的对象）

bodyB Object 刚体 B 句柄（`createBox` 等返回值，或含 `body` 的对象）

frameA Object A 侧局部关节帧

frameB Object B 侧局部关节帧

options

Object

Properties

Name	Type	Argument	Default	Description
`slideDir`	Array.<number>	<optional>		滑动方向向量；`world` 默认 `[1,0,0]` ENU，`local` 默认参考体 A 局部 `[1,0,0]`
`slideDirSpace`	string	<optional>	'local'	`'world'` \| `'local'`
`lowerLinLimit`	number	<optional>	-1e30	沿滑动轴行程下限（米）
`upperLinLimit`	number	<optional>	1e30	沿滑动轴行程上限（米）
`allowRotation`	boolean	<optional>	false	是否允许绕滑动轴自转；`false` 时角限位默认锁为 `0`
`lowerAngLimit`	number	<optional>		自转下限（rad）；默认：`allowRotation ? -π : 0`
`upperAngLimit`	number	<optional>		自转上限（rad）；默认：`allowRotation ? π : 0`
`useLinearReferenceFrameA`	boolean	<optional>	true	线性参考帧是否取 A。`true`：轨道在锚点，拖滑块不会带走锚点；`false`：轨道在滑块，锚点会被拉着走

See:

ScenePhysics#createJointGizmo

Returns:

滑块约束句柄；世界未加载时返回 `null`。字段： - `constraint`：Ammo `btSliderConstraint` - `type`：`'slider'` - `isSlider`：`true` - `slideDirSpace` / `axisWorldEnu`：方向空间与创建时的世界方向 - `bodyA` / `bodyB`：两侧刚体句柄 - `frameA` / `frameB`：解析后的关节帧 `{ position, rotation, axis }` - `axisA` / `axisB`：两侧局部滑动轴 - `limits`：`{ lowerLinLimit, upperLinLimit, lowerAngLimit, upperAngLimit, allowRotation }`

Type: Object

Example

// 滑动方向用 options.slideDir / slideDirSpace
// - `local`（默认）：slideDir 为参考体 A 模型局部，默认 `[1,0,0]`，跟着 A 转
// - `world`：slideDir 为世界 ENU，箭头不跟模型偏航

// frame（刚体**模型局部**关节位姿）：`{ position?, rotation? }`
// - `position`：局部锚点 `[x,y,z]`（米）；物理坐标
// - `rotation`：副轴 / 角限位零位（可选）；物理旋转角度

const slider = physics.addSliderConstraint(anchor, sled, {
  position: [0, 0, 0],
  rotation: [0, 0, 0, 1]
}, {
  position: [0, 0, 0],
  rotation: [0, 0, 0, 1]
}, {
  slideDir: [1, 0, 0],
  slideDirSpace: 'world',
  lowerLinLimit: -1.5,
  upperLinLimit: 1.5,
  allowRotation: true,
  lowerAngLimit: -Math.PI / 2,
  upperAngLimit: Math.PI / 2
});
physics.enterPhysicsGizmoEditMode();
physics.createJointGizmo(slider, { mode: 'drive' });

anchorCloth(clothHandle, nodeIndex, bodyHandle [, influence] [, disableCollisionBetweenLinkedBodies])

将布料节点锚定到刚体

Parameters:

Name	Type	Argument	Default	Description
`clothHandle`	Object			createCloth 返回的布料句柄
`nodeIndex`	number			布料节点索引
`bodyHandle`	Object			刚体句柄（createBox 返回值，或含 body 的对象）
`influence`	number	<optional>	0.5	锚定影响系数（0~1）
`disableCollisionBetweenLinkedBodies`	boolean	<optional>	false	是否禁用锚定双方碰撞

bindVisual(handle, primitive)

将渲染 Primitive 绑定到刚体句柄，物理 step 后同步 modelMatrix

Parameters:

Name	Type	Description
`handle`	Object	create* 返回值
`primitive`	Object \| null	Primitive（需可写 modelMatrix）；传 null 解除绑定

Returns:

Type: void

collectContactImpulses()

采集当前帧接触冲量（穿透接触）

Returns:

Type: Array.<{handleA, handleB, maxImpulse, point, normal}>

createBox( [options])

创建程序化盒体刚体（仅物理，无渲染；坐标系 ENU：X 东、Y 北、Z 上）

Parameters:

Name Type Argument Description

options

Object

Properties

Name	Type	Argument	Default	Description
`size`	Array.<number>	<optional>	[1,1,1]	全尺寸 [sx, sy, sz]（米）
`frame`	Object	<optional>		局部位姿（position ENU 米；rotation 四元数 xyzw）
`mass`	number	<optional>	0	质量（kg）；0 为静态
`friction`	number	<optional>	0.5	摩擦系数
`restitution`	number	<optional>	0	弹性系数
`linearDamping`	number	<optional>		线阻尼
`angularDamping`	number	<optional>		角阻尼
`disableGravity`	boolean	<optional>	false	关闭动态刚体自身重力
`centerOfMass`	Array.<number>	<optional>		质心（模型局部系，米）；未设置时为几何中心 [0,0,0]
`collisionGroup`	number	<optional>		碰撞组码（bitmask）；不传则按 static=2 / dynamic=1 / kinematic=4
`collisionMask`	number	<optional>		碰撞掩码；传了 collisionGroup 且未指定时默认排除同组（65535^group）
`name`	string	<optional>		实体名称

Returns:

刚体句柄（含 entity / body / halfExtents；可用 bindVisual 挂接渲染）

Type: Object | null

createCloth( [options])

创建布料 soft body 需先 enablePhysics(..., softBody=true) 或在添加刚体前调用 enableSoftBody() 仅物理数据：positionsEnu / indices / uvs；渲染由上层完成

Parameters:

Name Type Argument Description

options

Object

Properties

Name	Type	Argument	Default	Description
`width`	number	<optional>	4	布料宽度（米，沿 ENU -Y）
`height`	number	<optional>	3	布料高度（米，沿 ENU Z）
`segmentsW`	number	<optional>		宽度分段数；默认 round(width*5)
`segmentsH`	number	<optional>		高度分段数；默认 round(height*5)
`position`	Array.<number>	<optional>	[-3,2,3]	布料角点参考位置 [x,y,z]（ENU）
`mass`	number	<optional>	0.9	总质量（kg）
`margin`	number	<optional>	0.15	碰撞边距（米）

Returns:

布料句柄（含 softBody / positionsEnu / indices / uvs / segmentsW / segmentsH）

Type: Object | null

createCone( [options])

创建程序化圆锥刚体（轴线沿 ENU Z；仅物理，无渲染）

Parameters:

Name Type Argument Description

options

Object

Properties

Name	Type	Argument	Default	Description
`radius`	number	<optional>	0.5	底面半径（米）
`height`	number	<optional>	1	全高（米，沿 Z）
`frame`	Object	<optional>		局部位姿
`mass`	number	<optional>	0	质量（kg）；0 为静态
`friction`	number	<optional>	0.5	摩擦系数
`restitution`	number	<optional>	0	弹性系数
`linearDamping`	number	<optional>		线阻尼
`angularDamping`	number	<optional>		角阻尼
`centerOfMass`	Array.<number>	<optional>		质心（模型局部系，米）；未设置时为几何中心
`collisionGroup`	number	<optional>		碰撞组码；不传则按刚体类型默认
`collisionMask`	number	<optional>		碰撞掩码；默认排除同组
`name`	string	<optional>		实体名称

Returns:

刚体句柄（含 entity / body / radius / height）

Type: Object | null

createConvexHull(options)

创建凸包刚体（仅物理，无渲染；坐标系 ENU）

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Argument	Default	Description
`points`	Float32Array \| Array.<number> \| Array			局部顶点（至少 4 个）
`frame`	Object	<optional>		局部位姿
`mass`	number	<optional>	0	质量；0 为静态
`friction`	number	<optional>	0.5
`restitution`	number	<optional>	0.5
`linearDamping`	number	<optional>		线阻尼
`angularDamping`	number	<optional>		角阻尼
`centerOfMass`	Array.<number>	<optional>		质心（模型局部系，米）；未设置时为几何中心
`linearVelocity`	Array.<number>	<optional>		初速度 [vx,vy,vz]
`angularVelocity`	Array.<number>	<optional>		初角速度
`collisionGroup`	number	<optional>
`collisionMask`	number	<optional>
`userData`	Object	<optional>		自定义数据（如 breakable）
`name`	string	<optional>

Returns:

Type: Object | null

createCylinder( [options])

创建程序化圆柱刚体（轴线沿 ENU Z；仅物理，无渲染）

Parameters:

Name Type Argument Description

options

Object

Properties

Name	Type	Argument	Default	Description
`radius`	number	<optional>	0.5	半径（米）
`height`	number	<optional>	1	全高（米，沿 Z）
`frame`	Object	<optional>		局部位姿
`mass`	number	<optional>	0	质量（kg）；0 为静态
`friction`	number	<optional>	0.5	摩擦系数
`restitution`	number	<optional>	0	弹性系数
`linearDamping`	number	<optional>		线阻尼
`angularDamping`	number	<optional>		角阻尼
`centerOfMass`	Array.<number>	<optional>		质心（模型局部系，米）；未设置时为几何中心
`collisionGroup`	number	<optional>		碰撞组码；不传则按刚体类型默认
`collisionMask`	number	<optional>		碰撞掩码；默认排除同组
`name`	string	<optional>		实体名称

Returns:

刚体句柄（含 entity / body / radius / height）

Type: Object | null

createHeightfield(options)

创建高度场地形刚体（静态；仅物理，无渲染） Bullet 会将高度场 AABB 中心对齐到刚体原点，故默认 frame.position Z = (minHeight+maxHeight)/2

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Argument	Default	Description
`heightData`	Float32Array \| Array.<number>			高度采样，行优先，长度 = gridWidth * gridDepth
`gridWidth`	number			X 方向采样点数
`gridDepth`	number			Y 方向采样点数
`widthExtents`	number	<optional>		X 方向总宽（米）；默认 gridWidth-1
`depthExtents`	number	<optional>		Y 方向总深（米）；默认 gridDepth-1
`minHeight`	number	<optional>	0	高度最小值（米，ENU Z）
`maxHeight`	number	<optional>	1	高度最大值（米，ENU Z）
`frame`	Object	<optional>		局部位姿；默认 position [0,0,(min+max)/2]
`mass`	number	<optional>	0	质量；高度场应为 0（静态）
`friction`	number	<optional>	0.5	摩擦系数
`restitution`	number	<optional>	0	弹性系数
`linearDamping`	number	<optional>		线阻尼
`angularDamping`	number	<optional>		角阻尼
`centerOfMass`	Array.<number>	<optional>		质心（模型局部系，米）；未设置时为几何中心
`collisionGroup`	number	<optional>		碰撞组码；不传则按刚体类型默认
`collisionMask`	number	<optional>		碰撞掩码；默认排除同组
`name`	string	<optional>		实体名称

Returns:

刚体句柄（含 heightData / gridWidth / gridDepth 等元数据）

Type: Object | null

createJointGizmo(constraintHandle [, options])

为约束创建交互 Gizmo（铰链 / 球铰 / 滑块）需先 ScenePhysics#enterPhysicsGizmoEditMode；未进入时返回 null

Parameters:

Name Type Argument Description

constraintHandle Object ScenePhysics#addHinge / ScenePhysics#addPoint2PointJoint / ScenePhysics#addDistanceConstraint / ScenePhysics#addSliderConstraint 的返回句柄

options

Object

Properties

Name Type Argument Default Description

mode string <optional> 'visualize' - `visualize`：仅显示，不可拖拽 - `drive`：拖拽驱动刚体（平移 / 绕轴旋转 / 拉拽，随约束类型而定）

style

Object

视觉样式；未传字段使用默认值

Properties

Name	Type	Argument	Default	Description
`axisColor`	Color \| string	<optional>	'#00E5FF'	轴向虚线颜色（铰链转轴 / 滑块参考轴）
`ringColor`	Color \| string	<optional>	'#7CFFB2'	旋转扇形环颜色（铰链；滑块在 allowRotation 时）
`arrowColor`	Color \| string	<optional>	'#00E5FF'	滑块平移箭头颜色（PolylineArrow）
`anchorAColor`	Color \| string	<optional>	'#FF2D95'	球铰锚点 A 颜色
`anchorBColor`	Color \| string	<optional>	'#FFB020'	球铰锚点 B 颜色
`linkColor`	Color \| string	<optional>	'#FF2D95'	球铰 A–B 连线箭头颜色
`highlightColor`	Color \| string	<optional>	Color.AQUA	拖拽选中部件高亮色
`arrowLength`	number	<optional>	1.0	箭头总长（米）：线 + 箭头头
`arrowWidth`	number	<optional>	10	箭头线宽（屏幕像素）
`ringRadius`	number	<optional>	1.0	扇形环外半径（米）
`axisLength`	number	<optional>	1.0	轴向虚线长度（米）
`axisWidth`	number	<optional>	1.5	轴向虚线线宽（屏幕像素）
`anchorRadius`	number	<optional>	0.08	球铰锚点球半径（米）
`rangeBoxColor`	Color \| string	<optional>		滑块活动范围盒填充色（默认青、半透明）
`rangeBoxOutlineColor`	Color \| string	<optional>		滑块活动范围盒线框色

onChange function <optional> 交互回调。参数 payload： - `gizmo`：当前 JointGizmo 实例 - `handle`：约束句柄 - `mode`：当前模式 `visualize` | `drive` - `part`：命中部件（如 `sliderArrow` / `ring` / `anchorA`） - `phase`：可选，`'end'` 表示拖拽结束 - 滑块平移：`kind:'translate'`, `slide`, `slideDelta` - 滑块/铰链旋转：`kind:'rotate'` 或 `deltaAngle` / `angle` - 球铰：`fixedPosition`（地固坐标）

Returns:

JointGizmo 实例；失败时 null

Type: Object | null

Example

physics.enterPhysicsGizmoEditMode();
const gizmo = physics.createJointGizmo(sliderHandle, {
  mode: 'drive',
  style: {
    arrowLength: 0.8,
    arrowWidth: 10,
    arrowColor: '#2E7D32',
    ringColor: '#7CFFB2',
    axisColor: '#00E5FF'
  },
  onChange: (e) => console.log(e.kind, e.slide, e.angle)
});

// 球铰：拖两个锚点球
physics.createJointGizmo(p2pHandle, {
  mode: 'drive',
  style: { anchorRadius: 0.12 }
});

createSphere( [options])

创建程序化球体刚体（仅物理，无渲染；坐标系 ENU）

Parameters:

Name Type Argument Description

options

Object

Properties

Name	Type	Argument	Default	Description
`radius`	number	<optional>	0.5	半径（米）
`frame`	Object	<optional>		局部位姿
`mass`	number	<optional>	0	质量（kg）；0 为静态
`friction`	number	<optional>	0.5	摩擦系数
`restitution`	number	<optional>	0	弹性系数
`linearDamping`	number	<optional>		线阻尼
`angularDamping`	number	<optional>		角阻尼
`centerOfMass`	Array.<number>	<optional>		质心（模型局部系，米）；未设置时为几何中心
`collisionGroup`	number	<optional>		碰撞组码；不传则按刚体类型默认
`collisionMask`	number	<optional>		碰撞掩码；默认排除同组
`name`	string	<optional>		实体名称

Returns:

刚体句柄（含 entity / body / radius）

Type: Object | null

debugCollisionBoxCount()

当前调试碰撞包围盒绘制的刚体数量（0 表示未绘制或没有可绘制的碰撞体）

Returns:

Type: number

debugCollisionBoxStats()

调试绘制统计：刚体数、质心/原点标记数，以及质心与节点原点真正分离的数量

Returns:

Type: Object

destroyJointGizmo(idOrGizmoOrHandle)

销毁指定关节 Gizmo

Parameters:

Name	Type	Description
`idOrGizmoOrHandle`	string \| Object

disablePhysics()

关闭物理引擎

<async> enablePhysics( [worldOrigin] [, gravity] [, softBody])

开启物理引擎（异步加载，物理模块同步初始化）

Parameters:

Name	Type	Argument	Default	Description
`worldOrigin`	Array.<number> \| Object	<optional>		物理世界原点（经纬度）
`gravity`	number \| Object	<optional>	-9.81	重力加速度（ENU 坐标系 Z 轴向下为负）
`softBody`	boolean	<optional>	false	是否启用软体世界（布料等）；默认仅刚体世界

Returns:

Type: Promise.<void>

enableSoftBody()

启用软体世界。也可在 enablePhysics 时传 softBody = true。须在添加任何刚体或软体之前调用。

Returns:

世界尚未加载时返回 false

Type: boolean

enterPhysicsGizmoEditMode()

进入物理关节约束 Gizmo 编辑模式

Returns:

Type: PhysicsGizmoManager | null

exitPhysicsGizmoEditMode()

退出物理关节约束 Gizmo 编辑模式并释放全部 Gizmo 资源

getAngularVelocity(handle [, result])

获取角速度（ENU，rad/s）

Parameters:

Name	Type	Argument	Description
`handle`	Object
`result`	Array.<number>	<optional>

Returns:

Type: Array.<number>

getCenterOfMass(handle [, result])

获取质心（模型局部系），距离旋转中心的偏移量（米）

Parameters:

Name	Type	Argument	Description
`handle`	Object
`result`	Array.<number>	<optional>

Returns:

Type: Array.<number> | null

getDamping(handle [, result])

获取刚体阻尼

Parameters:

Name	Type	Argument	Description
`handle`	Object
`result`	Object	<optional>

Returns:

Type: Object | null

getGravity()

获取重力向量

Returns:

Type: Cartesian3

getLinearVelocity(handle [, result])

获取线速度（ENU，m/s）

Parameters:

Name	Type	Argument	Description
`handle`	Object
`result`	Array.<number>	<optional>

Returns:

Type: Array.<number>

getModelJoints(layer)

获取指定 layer 对应的 USD 关节列表。

Parameters:

Name	Type	Description
`layer`	Glodon.CIMCube.Layer.GltfLayer \| Glodon.CIMCube.Layer.USDLayer

Returns:

关节列表

Type: Array.<{joint:Object, parent:Object, child:Object}>

getWorldOrigin()

获取物理世界原点

Returns:

Type: Object

isPhysicsGizmoEditMode()

是否处于物理 Gizmo 编辑模式

Returns:

Type: boolean

removeAfterStepListener(listener)

移除物理步进结束监听

Parameters:

Name	Type	Description
`listener`	function	与 addAfterStepListener 传入的是同一个函数

removeDebugCollisionBox()

清除调试碰撞包围盒线框

removeModelPhysics(layer)

移除指定 layer 的物理绑定：拆约束 + 销毁刚体 + 停止同步。图层切换 / 卸载前必须调用，否则旧刚体仍留在物理世界继续模拟（受重力下落），并每帧把结果写回节点，切回来时模型已被写飞

Parameters:

Name	Type	Description
`layer`	Glodon.CIMCube.Layer.GltfLayer \| Glodon.CIMCube.Layer.USDLayer

Returns:

是否移除了绑定

Type: boolean

removeRigidBody(handle)

移除程序化刚体（不负责移除渲染 Primitive）

Parameters:

Name	Type	Description
`handle`	Object

Returns:

Type: boolean

renderDebugCollisionBox( [options])

渲染当前帧物理刚体碰撞包围盒线框（重复调用会先清除旧线框）

Parameters:

Name Type Argument Description

options

Object

Properties

Name	Type	Argument	Default	Description
`color`	Color	<optional>		统一线框颜色
`staticColor`	Color	<optional>		静态刚体 box 颜色，默认 RED
`dynamicColor`	Color	<optional>		动态刚体 box 颜色，默认 YELLOW
`meshColor`	Color	<optional>		三角网格 AABB 线框颜色，默认 LIME
`showCom`	boolean	<optional>		是否同时绘制质心标记（立方体）
`showOrigin`	boolean	<optional>		是否同时绘制刚体 Xform 原点标记（立方体）
`comColor`	Color	<optional>		质心标记颜色，默认 MAGENTA
`originColor`	Color	<optional>		原点标记颜色，默认 CYAN
`markerSize`	number	<optional>	0.4	质心标记立方体边长（米）
`originMarkerSize`	number	<optional>		原点标记立方体边长（米），默认 markerSize×2

setAngularVelocity(handle, velocity)

设置角速度（ENU，rad/s）

Parameters:

Name	Type	Description
`handle`	Object
`velocity`	Array.<number> \| Object

setCCDEnabled(enable)

启用/禁用 CCD（连续碰撞检测）

Parameters:

Name	Type	Description
`enable`	boolean

setCCDThreshold(speed)

设置 CCD 速度阈值

Parameters:

Name	Type	Description
`speed`	number

setCenterOfMass(handle, centerOfMass)

设置质心（模型/实体局部系，米），未设置时默认等于旋转中心。

Parameters:

Name	Type	Description
`handle`	Object	刚体句柄
`centerOfMass`	Array.<number> \| Object

setCollisionModel(layer [, options])

为gltf图层创建一个物理刚体模型

Parameters:

Name Type Argument Description

layer Glodon.CIMCube.Layer.GltfLayer | Glodon.CIMCube.Layer.USDLayer glTF / USD 图层（USDLayer 亦支持）

options

Object

配置项

Properties

Name	Type	Argument	Default	Description
`type`	string	<optional>	"static"	刚体类型 static \| dynamic
`mass`	number	<optional>	1	动态刚体质量，dynamic 时有效
`useTriangleMesh`	boolean	<optional>	false	使用 glTF 三角网格碰撞（静态 BVH / 动态 GImpact）；位姿对齐 model.modelMatrix
`friction`	number	<optional>	0.5	摩擦系数
`restitution`	number	<optional>	0.1	弹性系数
`linearDamping`	number	<optional>		线阻尼（越大减速越快）
`angularDamping`	number	<optional>		角阻尼
`disableGravity`	boolean	<optional>	false	关闭动态刚体自身重力
`centerOfMass`	Array.<number>	<optional>		质心（模型局部系，米）；未设置时等于旋转中心（包围盒中心）
`halfExtents`	Array.<number>	<optional>		盒体半长宽高，默认取包围球半径
`collisionGroup`	number	<optional>		碰撞组码（bitmask）；不传则按刚体类型默认
`collisionMask`	number	<optional>		碰撞掩码；传了 collisionGroup 且未指定时默认排除同组（65535^group）

Returns:

刚体句柄 { entity, rigidBody, body, model, isWholeModel }

Type: Object

setCollisionModelNode(layer [, options])

为 glTF 图层的每个 mesh 分别创建物理刚体。默认，每个 mesh 自动以自身节点局部 AABB 中心为质心

Parameters:

Name Type Argument Description

layer Glodon.CIMCube.Layer.GltfLayer | Glodon.CIMCube.Layer.USDLayer glTF / USD 图层（USDLayer 亦支持）

options

Object

配置项

Properties

Name	Type	Argument	Default	Description
`mass`	number	<optional>	1	动态节点质量。USD 刚体写了 physics:mass 时以 USD 为准
`friction`	number	<optional>	0.5	摩擦系数。USD 碰撞体写了 PhysicsMaterialAPI 时以 USD 为准
`restitution`	number	<optional>	0.1	弹性系数。USD 写了 physics:restitution 时以 USD 为准
`linearDamping`	number	<optional>		线阻尼（越大减速越快）
`angularDamping`	number	<optional>		角阻尼
`disableGravity`	boolean	<optional>	false	关闭动态刚体自身重力
`staticNamePattern`	RegExp \| string	<optional>	/^static$/i	静态节点名称匹配
`usdJoints`	boolean	<optional>	true	USD 关节约束：仅 USDLayer 生效，传 false 可完全关闭
`collisionGroup`	number	<optional>		碰撞组码（bitmask）；不传则按刚体类型默认
`collisionMask`	number	<optional>		碰撞掩码；传了 collisionGroup 且未指定时默认排除同组（65535^group）
`useTriangleMesh`	boolean	<optional>	false	各 mesh 节点使用三角网格碰撞（静态 BVH / 动态 GImpact，对齐 ammo demo 逐 Mesh）

Returns:

刚体句柄列表

Type: Array.<Object>

setDamping(handle [, linearDamping] [, angularDamping])

设置刚体线阻尼 / 角阻尼

Parameters:

Name	Type	Argument	Description
`handle`	Object		刚体句柄
`linearDamping`	number	<optional>	线阻尼；省略则不改
`angularDamping`	number	<optional>	角阻尼；省略则不改

setDistanceConstraintEnabled(distanceHandle, enabled)

启用/禁用距离约束求解（Gizmo 拖拽期间可暂时关闭）

Parameters:

Name	Type	Description
`distanceHandle`	Object	addDistanceConstraint 返回句柄
`enabled`	boolean

setFixedJointEnabled(fixedHandle, enabled [, options])

运行时拆焊 / 复焊固定关节（不销毁约束对象，随时可切回） - `enabled = false`：**拆焊**。关节移出物理世界，两体恢复独立；句柄保留，可随时复焊 - `enabled = true`：**复焊**。关节重新加入世界并唤醒两体。默认以两体**当前**相对位姿为新锚点传 `{ relockCurrentPose: false }` 则回到最初建立关节时的相对位姿，部件会被求解器拉回原位

Parameters:

Name Type Argument Description

fixedHandle Object ScenePhysics#addFixedJoint 返回的句柄

enabled boolean `false` 拆焊，`true` 复焊

options

Object

Properties

Name	Type	Argument	Default	Description
`relockCurrentPose`	boolean	<optional>	true	复焊时是否以两体当前相对位姿重新锚定

Returns:

是否真的发生了状态切换（重复调用 / 句柄非法 / 世界未加载时返回 `false`）

Type: boolean

Example

// 拆焊 → 拖走部件 → 在拖到的新位置复焊
physics.setFixedJointEnabled(weld, false);
physics.setFixedJointEnabled(weld, true);

// 复焊并弹回最初建立的相对位姿
physics.setFixedJointEnabled(weld, true, { relockCurrentPose: false });

setGravity(gravity)

设置重力向量

Parameters:

Name	Type	Description
`gravity`	number \| Cartesian3	重力加速度（ENU 坐标系 Z 轴向下为负, X 轴为东向, Y 轴为北向）

setHingeMotor(hingeHandle, enable, targetVelocity, maxImpulse)

设置铰链电机 (门、合页、翻盖、转臂)

Parameters:

Name	Type	Description
`hingeHandle`	Object	addHinge 返回的铰链句柄
`enable`	boolean	是否启用电机
`targetVelocity`	number	目标角速度（rad/s）
`maxImpulse`	number	最大冲量

setLinearVelocity(handle, velocity)

设置线速度（ENU，m/s）

Parameters:

Name	Type	Description
`handle`	Object
`velocity`	Array.<number> \| Object

setPoint2PointConstraintEnabled(p2pHandle, enabled)

启用/禁用球铰约束求解

Parameters:

Name	Type	Description
`p2pHandle`	Object	addPoint2PointJoint 返回句柄
`enabled`	boolean

syncDistanceLimits()

把距离约束的 maxDistance 收成当前两锚点间距。minDistance 不动。先吸收帧动画刚写进场景图的位姿再量距离，否则量到的是上一帧刚体。 Gizmo 拖动中直接返回，避免拖拽改写绳长区间。不要放进物理步进：每步都改上限等于约束永不施力。