CIMCubeSDK v3.56.0

Class: ScenePhysics

Glodon.CIMCube. ScenePhysics

场景物理引擎接口（通过 map.scene.physics 访问）

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

addHinge(bodyA, bodyB, pivotA, pivotB [, axisA] [, axisB] [, options])

添加铰链约束（仅允许绕单一转轴旋转；门、合页、翻盖），支持角度限位
Parameters:
Name Type Argument Default Description
bodyA Object 刚体 A 句柄（或 btRigidBody）
bodyB Object 刚体 B 句柄（或 btRigidBody）
pivotA Array.<number> A 局部支点 [x, y, z]（ENU，米）
pivotB Array.<number> B 局部支点 [x, y, z]（ENU，米）
axisA Array.<number> <optional>
 [0,0,1] A 局部铰链轴
axisB Array.<number> <optional>
 [0,0,1] B 局部铰链轴
options Object <optional>
 角度限位等
Properties
Name Type Argument Default Description
low number <optional>
 下限角（rad）；与 high 同时传入时启用限位
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）
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，米）
Returns:
约束句柄 { constraint }
Type
Object | null

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

添加滑块（棱柱）约束：仅允许沿局部 X 轴平移，可限制行程；可选是否允许绕轴自转 （升降、活塞、推拉门、伸缩臂）
Parameters:
Name Type Argument Description
bodyA Object 刚体 A 句柄
bodyB Object 刚体 B 句柄,可以为null
frameA Object 局部位姿 { position: [x,y,z], rotation: [x,y,z,w] }，X 轴为滑动轴
frameB Object 局部位姿
options Object <optional>
Properties
Name Type Argument Default Description
lowerLinLimit number <optional>
 -1e30 行程下限（米）
upperLinLimit number <optional>
 1e30 行程上限（米）
allowRotation boolean <optional>
 false 是否允许绕滑动轴自转
lowerAngLimit number <optional>
 自转下限（rad）
upperAngLimit number <optional>
 自转上限（rad）
useLinearReferenceFrameA boolean <optional>
 true
Returns:
约束句柄 { constraint, isSlider }
Type
Object | null

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 Cesium.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 <optional>
Properties
Name Type Argument Default Description
size Array.<number> <optional>
 [1,1,1] 全尺寸 [sx, sy, sz]（米）
position Array.<number> <optional>
 [0,0,0] 中心位置 [x, y, z]（米，ENU）
rotation Array.<number> <optional>
 [0,0,0,1] 姿态四元数 [x, y, z, w]
mass number <optional>
 0 质量（kg）；0 为静态
friction number <optional>
 0.5 摩擦系数
restitution number <optional>
 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 <optional>
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 <optional>
Properties
Name Type Argument Default Description
radius number <optional>
 0.5 底面半径（米）
height number <optional>
 1 全高（米，沿 Z）
position Array.<number> <optional>
 [0,0,0] 中心位置 [x, y, z]（米，ENU）
rotation Array.<number> <optional>
 [0,0,0,1] 姿态四元数 [x, y, z, w]
mass number <optional>
 0 质量（kg）；0 为静态
friction number <optional>
 0.5 摩擦系数
restitution number <optional>
 0 弹性系数
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 个）
position Array.<number> <optional>
 [0,0,0] 中心 [x,y,z]（米，ENU）
rotation Array.<number> <optional>
 [0,0,0,1] 四元数
mass number <optional>
 0 质量；0 为静态
friction number <optional>
 0.5
restitution number <optional>
 0.5
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 <optional>
Properties
Name Type Argument Default Description
radius number <optional>
 0.5 半径（米）
height number <optional>
 1 全高（米，沿 Z）
position Array.<number> <optional>
 [0,0,0] 中心位置 [x, y, z]（米，ENU）
rotation Array.<number> <optional>
 [0,0,0,1] 姿态四元数 [x, y, z, w]
mass number <optional>
 0 质量（kg）；0 为静态
friction number <optional>
 0.5 摩擦系数
restitution number <optional>
 0 弹性系数
collisionGroup number <optional>
 碰撞组码；不传则按刚体类型默认
collisionMask number <optional>
 碰撞掩码；默认排除同组
name string <optional>
 实体名称
Returns:
刚体句柄（含 entity / body / radius / height）
Type
Object | null

createHeightfield(options)

创建高度场地形刚体（静态；仅物理，无渲染） Bullet 会将高度场 AABB 中心对齐到刚体原点，故默认 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）
position Array.<number> <optional>
 刚体原点 [x,y,z]；默认 [0,0,(min+max)/2]
rotation Array.<number> <optional>
 [0,0,0,1] 姿态四元数 [x, y, z, w]
mass number <optional>
 0 质量；高度场应为 0（静态）
friction number <optional>
 0.5 摩擦系数
restitution number <optional>
 0 弹性系数
collisionGroup number <optional>
 碰撞组码；不传则按刚体类型默认
collisionMask number <optional>
 碰撞掩码；默认排除同组
name string <optional>
 实体名称
Returns:
刚体句柄（含 heightData / gridWidth / gridDepth 等元数据）
Type
Object | null

createSphere( [options])

创建程序化球体刚体（仅物理，无渲染；坐标系 ENU）
Parameters:
Name Type Argument Description
options Object <optional>
Properties
Name Type Argument Default Description
radius number <optional>
 0.5 半径（米）
position Array.<number> <optional>
 [0,0,0] 中心位置 [x, y, z]（米，ENU）
rotation Array.<number> <optional>
 [0,0,0,1] 姿态四元数 [x, y, z, w]
mass number <optional>
 0 质量（kg）；0 为静态
friction number <optional>
 0.5 摩擦系数
restitution number <optional>
 0 弹性系数
collisionGroup number <optional>
 碰撞组码；不传则按刚体类型默认
collisionMask number <optional>
 碰撞掩码；默认排除同组
name string <optional>
 实体名称
Returns:
刚体句柄（含 entity / body / radius）
Type
Object | null

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 须在添加任何刚体/软体之前调用

getAngularVelocity(handle [, result])

获取角速度（ENU，rad/s）
Parameters:
Name Type Argument Description
handle Object
result Array.<number> <optional>
Returns:
Type
Array.<number>

getGravity()

获取重力向量
Returns:
Type
Cesium.Cartesian3

getLinearVelocity(handle [, result])

获取线速度（ENU，m/s）
Parameters:
Name Type Argument Description
handle Object
result Array.<number> <optional>
Returns:
Type
Array.<number>

getWorldOrigin()

获取物理世界原点
Returns:
Type
Object

removeDebugCollisionBox()

清除调试碰撞包围盒线框

removeRigidBody(handle)

移除程序化刚体（不负责移除渲染 Primitive）
Parameters:
Name Type Description
handle Object
Returns:
Type
boolean

renderDebugCollisionBox( [options])

渲染当前帧物理刚体碰撞包围盒线框（重复调用会先清除旧线框）
Parameters:
Name Type Argument Description
options Object <optional>
Properties
Name Type Argument Description
color Cesium.Color <optional>
 统一线框颜色
staticColor Cesium.Color <optional>
 静态刚体 box 颜色，默认 RED
dynamicColor Cesium.Color <optional>
 动态刚体 box 颜色，默认 YELLOW
meshColor Cesium.Color <optional>
 三角网格 AABB 线框颜色，默认 LIME

resetCollisionModelNode(layer [, handles])

重置 mesh 级物理到 setCollisionModelNode 创建时的状态（刚体位姿、速度、节点 transform）
Parameters:
Name Type Argument Description
layer Glodon.CIMCube.Layer.GltfLayer glTF 图层
handles Array.<Object> <optional>
 setCollisionModelNode 返回的句柄；省略则重置该图层全部 mesh
Returns:
是否成功重置
Type
boolean

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

setCollisionModel(layer [, options])

为gltf图层创建一个物理刚体模型
Parameters:
Name Type Argument Description
layer Glodon.CIMCube.Layer.GltfLayer glTF 图层
options Object <optional>
 配置项
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 弹性系数
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创建物理刚体模型
Parameters:
Name Type Argument Description
layer Glodon.CIMCube.Layer.GltfLayer glTF 图层
options Object <optional>
 配置项
Properties
Name Type Argument Default Description
mass number <optional>
 1 动态节点质量
useTriangleMesh boolean <optional>
 false 各 mesh 节点使用三角网格碰撞（静态 BVH / 动态 GImpact，对齐 ammo demo 逐 Mesh）
staticNamePattern RegExp | string <optional>
 /^static$/i 静态节点名称匹配
friction number <optional>
 0.5 摩擦系数
restitution number <optional>
 0.1 弹性系数
collisionGroup number <optional>
 碰撞组码（bitmask）；不传则按刚体类型默认
collisionMask number <optional>
 碰撞掩码；传了 collisionGroup 且未指定时默认排除同组（65535^group）
Returns:
刚体句柄列表
Type
Array.<Object>

setGravity(gravity)

设置重力向量
Parameters:
Name Type Description
gravity number | Cesium.Cartesian3 重力加速度（ENU 坐标系 Z 轴向下为负, X 轴为东向, Y 轴为北向）

setHingeMotor(hingeHandle, enable, targetVelocity, maxImpulse)

设置铰链电机（目标角速度 / 最大冲量；在物理 step 前生效）
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