EVEngine/docs/usr/modules/physics.md

物理模块（Box2D + Box3D + 布料 + 流体）

脚本入口： eve.Physics()

创建 World、Body、Fixture（Box2D 2D 刚体）、World3D / Body3D / Shape3D（Box3D 3D 刚体），以及可交互的 Cloth（2D Verlet 布料）、Cloth3D（3D Verlet 布料）与 Fluid2D（2D 粒子流体）。2D 脚本使用像素坐标并按 meter 换算；3D 使用米（Box3D 原生单位）；2D 布料/流体在像素空间模拟，3D 布料在米制空间模拟。

基本用法

刚体（Box2D，2D）

local physics = eve.Physics();
physics.setMeter(30.0);
local world = physics.newWorld(0, 980, true);
local body = world.newBody("dynamic", 100, 60);
body.newRectangleFixture(32, 32, 1.0, 0.3, 0.1);
world.update(dt);

刚体（Box3D，3D）

local physics = eve.Physics();
local world3 = physics.newWorld3D(0, -9.8, 0, true); // 米 / s²，+Y 向上
local ground = world3.newBody("static", 0, -1, 0);
ground.newBoxShape(20, 2, 20, 0.0, 0.5, 0.0);       // 全尺寸宽高深（米）
local box = world3.newBody("dynamic", 0, 4, 0);
box.newBoxShape(1, 1, 1, 1.0, 0.3, 0.1);
box.newSphereShape(0.5, 1.0);                        // 或球体
box.newCapsuleShape(1.0, 0.25, 1.0);                 // 或胶囊（沿局部 Y）
world3.update(dt);
// 姿态用四元数：box.setRotation(qx, qy, qz, qw); box.getRotX/Y/Z/W()

// 精确形状重叠查询，结果通过 getQueryCount/getQueryBodyId 读取。
world3.querySphere(0, 1, 0, 0.5);
world3.queryCapsule(0, 0.5, 0, 0, 1.5, 0, 0.3); // 两端球心 + 半径
world3.queryBox(0, 1, 0, 2, 1, 3, qx, qy, qz, qw); // 中心、完整尺寸、旋转

// 连续扫描可避免高速物体跨帧穿过薄墙；返回最早命中的 body id。
local hit = world3.castCapsule(0, 0.5, 0, 0, 1.5, 0, 0.3, 8, 0, 0);
local boxHit = world3.castBox(0, 1, 0, 2, 1, 3, qx, qy, qz, qw, 8, 0, 0);
if (hit >= 0) {
    local safeFraction = world3.getShapeCastFraction();
    local nx = world3.getShapeCastNormalX();
    local colliderId = world3.getShapeCastShapeId();
    local colliderTag = world3.getShapeCastShapeTag();
}

// 点到当前过滤层中最近碰撞表面的距离、位置和朝向目标点的法线。
local nearest = world3.closestPoint(listenerX, listenerY, listenerZ, 20);
if (nearest >= 0) {
    local distance = world3.getClosestDistance();
    local surfaceX = world3.getClosestX();
    local colliderId = world3.getClosestShapeId();
}

3D 符号距离场地图

DistanceField3D 保存规则网格顶点上的符号距离（负值为实体、正值为空间），适合体素地形、 程序化洞穴和预烘焙距离场。世界坐标查询使用三线性插值；碰撞后可读取最小间隙、接触位置和 由中心差分估计的表面法线。

// 16³ 个网格顶点，间距 0.5m，原点在 (-4,-4,-4)，地图外视为空间。
local sdf = physics.newDistanceField3D(16, 16, 16, 0.5, -4, -4, -4, 1000);
// 批量数组按 x 最快、其次 y、最后 z 的顺序排列；长度必须等于 getSampleCount()。
sdf.setDistances(bakedDistances);
sdf.setDistance(8, 8, 8, -0.5); // 也可局部更新单个样本
// 流式地图只替换变化区块；区域数组同样是 x -> y -> z 顺序。
sdf.setDistanceRegion(chunkX, chunkY, chunkZ, chunkW, chunkH, chunkD, chunkDistances);
local mapRevision = sdf.getRevision(); // 每次成功修改只递增一次，失败保持不变

if (sdf.checkSphere(playerX, playerY, playerZ, 0.4)) {
    local penetration = -sdf.getCollisionDistance();
    local nx = sdf.getNormalX();
    // Surface 是距离场表面投影；ShapeContact 是球/胶囊表面上的对应接触点。
    local terrainY = sdf.getSurfaceY();
    local shapeY = sdf.getShapeContactY();
}

// 端点是胶囊两端半球的球心，可为任意方向。
if (sdf.checkCapsule(ax, ay, az, bx, by, bz, radius)) {
    local hitY = sdf.getCollisionY();
}

// 连续碰撞检测：高速移动也会返回沿 delta 的最早接触点，避免跨帧穿过薄墙。
if (sdf.castCapsule(ax, ay, az, bx, by, bz, radius, dx, dy, dz)) {
    local safeFraction = sdf.getCastFraction();
    local travelDistance = sdf.getCastDistance();
    local startedPenetrating = sdf.didCastStartInside();
}

// 角色移动：返回是否受阻；把最终位移同时应用到胶囊两个端点和角色 Transform。
sdf.setMoverUp(0, 1, 0);
sdf.setMoverSlopeLimit(50); // 最大可站立坡度
sdf.setMoverSkinWidth(0.002); // 与表面保留的小间隔，降低浮点抖动
sdf.setMoverGroundSnap(0.15); // 移动后向下吸附到可行走表面，0 表示关闭
sdf.setMoverStepHeight(0.35); // 自动跨越不高于该值的台阶，0 表示关闭
local blocked = sdf.moveCapsule(ax, ay, az, bx, by, bz, radius, dx, dy, dz);
playerX += sdf.getMoverDeltaX();
playerY += sdf.getMoverDeltaY();
playerZ += sdf.getMoverDeltaZ();
local grounded = sdf.isMoverGrounded();

距离场至少为 2 × 2 × 2，cellSize > 0。fill(distance) 可快速重置整个网格； getWidth/Height/Depth、getCellSize 和 getOriginX/Y/Z 可用于校验地图资源。批量替换会先 校验全部数据，因此无效长度或 NaN/Infinity 不会导致地图只更新一部分。setDistanceRegion 和 fillRegion 适合按区块流式加载或卸载大型地图，越界区域同样不会产生部分写入。胶囊轴按半个网格单元的最大步长采样， Sweep Cast 沿运动方向使用四分之一网格单元的最大步长并对首次命中做二分细化。因此中段穿入而 两个端点均在实体外，或物体单帧跨过障碍时也能检出；地图分辨率仍应覆盖最薄的可碰撞特征。

布料（2D，像素空间）

local clothModule = eve.Cloth();
local cloth = clothModule.newCloth(18, 12, 14.0, 48.0, 36.0); // cols, rows, spacing, origin
cloth.setGravity(0, 980);
cloth.setBounds(0, 0, 800, 600);
cloth.setStiffness(0.9);
// 鼠标拖拽
local idx = cloth.grabAt(mx, my, 28.0);
if (idx >= 0) cloth.moveGrab(mx, my);
else cloth.releaseGrab();
cloth.update(dt);
cloth.draw(gfx);

2D 布料默认开启自碰撞（非相邻粒子保持至少 2×particleSize 距离），并带折角限制（setMaxFoldAngle，默认 90°）防止过锐褶皱。setCollideWorld(world) 可让自由粒子与 Box2D 非 sensor fixture 碰撞；碰撞按粒子/刚体折合质量交换动量，动态刚体越轻被推得越明显（粒子质量用 setParticleMass 调节，默认 0.1 kg）。

布料 3D（米制空间）

local clothModule = eve.Cloth();
local cloth3 = clothModule.newCloth3D(16, 12, 0.4, -3.0, 3.2, -2.0); // cols, rows, spacing, origin(X,Y,Z)
cloth3.setGravity(0, -9.8, 0);       // 米 / s²，+Y 向上
cloth3.setCollideWorld(world3);      // 与 Box3D 非 sensor shape 碰撞
cloth3.setParticleSize(0.12);        // 自碰撞半径 / 碰撞厚度
cloth3.setParticleMass(0.1);         // 碰撞动量交换的粒子质量（kg）
cloth3.setStretchCompliance(0.0001); // XPBD 拉伸柔顺度（m/N，0 为旧 PBD）
cloth3.setShearCompliance(0.0002);   // XPBD 剪切柔顺度
cloth3.setBendCompliance(0.001);     // XPBD 距离弯曲柔顺度
cloth3.setTetherScale(1.0);          // 启用到固定粒子的测地线 tether
cloth3.setTetherCompliance(0.0001);  // tether XPBD 柔顺度
// 闭合网格可用 setPressure(1.0) 保持烘焙体积，>1 充气；开放布料会忽略。
cloth3.setVolumeCompliance(0.00001);
cloth3.setWindVelocity(4, 0, 1);     // 世界空间空气速度（m/s）
cloth3.setAerodynamics(1.225, 1.1, 0.2); // 空气密度、阻力系数、升力系数
cloth3.setMaxFoldAngle(130);         // 相邻三角面最大折叠角（度），默认 120
cloth3.setSelfCollision(true);
cloth3.setBounds(-4, -1, -3, 8, 5.5, 6);  // 原点 + 宽高深
// 鼠标拾取（射线与 y=2 平面求交后）：
// local idx = cloth3.grabAt(x, y, z, 0.5);
// if (idx >= 0) cloth3.moveGrab(x, y, z);
cloth3.applyForce(1.0, 0, 0);         // 均匀风
cloth3.interactAt(x, y, z, 1.1, -14); // 指针场：正吸引 / 负排斥（与 Fluid2D 相同语义）
cloth3.update(dt);
cloth3.draw(gfx);                     // 需要处于 3D 帧内（gfx.render3D 之后）

setWindVelocity + setAerodynamics 使用当前变形后三角形的面积、法线和布料相对风速计算双面阻力/升力；因此折叠、转向后的受力会随表面姿态变化。两个系数都设为 0 即关闭气动力。applyForce 仍是一帧性均匀加速度，适合爆炸/阵风脉冲；持续风应使用新 API。

ClothModel（C++）

ClothModel 是可复用的静态布料资产，Cloth3D 是独立的运行时状态。模型负责验证并烘焙粒子、三角形、结构/弯曲距离约束和相邻三角面的折叠关系；它不持有渲染对象、碰撞世界或逐帧位置。规则网格和任意三角网格最终都进入相同运行时路径：

auto modelResult = eve::physics::ClothModel::grid(18, 12, 0.5f, 0.f, 5.f, 0.f);
if (!modelResult) {
    // 读取 modelResult.error() 的结构化诊断。
    return;
}

auto cloth = physics.createCloth(modelResult.value());
cloth->setWindVelocity(2.f, 0.f, 1.f);
cloth->update(dt);

任意网格使用 ClothModel::fromTriangles(positions, indices, inverseMasses)；positions 是紧密排列的 XYZ，inverseMasses 中的 0 表示固定粒子。输入索引越界、退化三角形、负质量或非流形边会整体拒绝，不会发布半成品模型。模型可序列化为严格版本化的 eve.cloth-model/1 Definition，并由 asset/physics 的 EvpackClothModelLoader 从 .evpack 加载；未知字段和未知版本都会拒绝。Squirrel 的规范入口是独立的 eve.Cloth() 子模块，newCloth3D(...) 在内部走同一个 ClothModel 网格烘焙路径。

Obi Cloth 6.4 核心覆盖边界

以下矩阵按参考包 ObiCloth_v6.4.unitypackage 内的 actor、blueprint、constraint batch、attachment 与 renderer 源码核对。这里的“80%”指 15 组核心运行时/资产能力按“完整=1、部分=0.5、缺失=0”计分达到 12/15；不是宣称 API、Unity Inspector 或 Burst/Oni 后端逐项兼容。

能力组	状态	EVEngine 对应实现 / 边界
Blueprint/任意网格资产	完整	ClothModel、eve.cloth-model/1、.evpack loader、严格验证
拉伸/剪切距离约束	完整	分类型 XPBD compliance，保留零 compliance 旧 PBD 行为
弯曲	部分	bend distance + 二面角 fold clamp；尚无 Obi 的 plastic yield/creep
气动力	完整	变形三角形面积/法线、双面 drag/lift、相对风速
Tether	完整	从固定粒子测地烘焙、scale、XPBD compliance
Volume/pressure	完整	封闭流形检测、静止体积、XPBD 保形与充气
Skin/backstop	完整	动画参考点/法线、skin radius、backstop sphere、compliance
Particle attachment	部分	动态世界目标、软/硬 attachment、更新/解绑；尚无跨 actor/刚体局部锚点对象
刚体世界碰撞	完整	World3D 非 sensor shape probe、动态体动量交换
自碰撞	完整	粒子空间哈希 + 非相邻三角面厚度约束
Collision filter	完整	cloth category/mask 与 Shape3D category/mask 双向过滤
摩擦/回弹	完整	cloth/shape 合并材质、切向速度摩擦、法向回弹
Runtime tearing	部分	阈值、单步预算、手动撕裂及权威表面拓扑更新；尚无 Obi 式顶点分裂/容量池
Skinned/proxy renderer	缺失	可逐帧更新 skin reference，但没有独立的 barycentric proxy renderer
GPU backend	部分	supportsFeature 明示能力；GPU 目前是 2D grid compute，3D 高级约束走 CPU，不静默伪装等价

运行时可用 getBackendName() 与 supportsFeature(name) 做显式后端选择。CPU 稳定 feature 名包括 arbitrary_topology、xpbd_material、tether、volume_pressure、skin_backstop、attachment、world_collision、collision_filter、friction、self_collision、aerodynamics、runtime_tearing。getTriangleCount、getDistanceConstraintCount、getTetherConstraintCount、getSkinConstraintCount、getAttachmentCount 与 getTornConstraintCount 提供编辑器/调试面板所需的只读数据。

高级材质与约束脚本 API：setStretchCompliance / getStretchCompliance、setShearCompliance / getShearCompliance、setBendCompliance / getBendCompliance；setTetherScale / getTetherScale、setTetherCompliance / getTetherCompliance；setPressure / getPressure、setVolumeCompliance / getVolumeCompliance、getCurrentVolume；setParticleInverseMass / getParticleInverseMass；setSkinConstraint、updateSkinReference、clearSkinConstraint、hasSkinConstraint；attachParticle、updateAttachment、detachParticle、isAttached；setCollisionMaterial、getCollisionFriction、getCollisionRestitution、setCollisionFilter、getCollisionCategoryBits、getCollisionMaskBits；setTearThreshold / getTearThreshold、setMaxTearsPerStep / getMaxTearsPerStep、tearConstraint。

模型可通过 toJson() / fromJson() 保存和恢复，规范标识为 eve.cloth-model/1。v1 使用严格未知字段策略：缺少字段、额外字段和未知版本都会被拒绝；约束不作为第二份真相保存，而是在加载并验证粒子与三角拓扑后确定性重建。规则网格额外保存并校验网格元数据，以保持旧求解器的约束顺序和有限迭代行为。

网格位于 XZ 平面、顶行默认钉住；pin / unpin / pinTopRow、grabAt / moveGrab / releaseGrab、reset、setColor 等与 2D 布料一致。3D 布料的折角约束基于相邻三角面的二面角：折叠超过 maxFoldAngle 时会绕共享边旋转两个三角面、把折角精确开回极限值，避免布料折成死褶或扭曲过高。3D 自碰撞除粒子级近邻外还带三角面级处理：非相邻三角面保持至少 2×particleSize 厚度，顶点穿透三角面会被沿面法线推出，布料不会在粒子间隙中互相穿过。

示例：examples/softbody3d/（窗帘 + 平台/球体碰撞 + 自碰撞 + 折角限制）

体积软体 3D（形状匹配）

SoftBody3D 是真正的体积软体，而不是加厚的布料。规则粒子格的每个体素单元 构成一个重叠八粒子 shape-matching cluster；相邻 cluster 共享粒子，因此局部体积和 朝向会恢复，同时仍允许挤压、扭转和回弹。该实现独立编写，只借鉴了 Obi Softbody 公开展示的组件分层与材料参数概念。

local body = physics.newSoftBody3D(4, 4, 4, 0.38, 0.9, 2.2, -0.6);
local renderer = physics.newSoftBody3DRenderer(body);
body.setGravity(0, -9.8, 0);
body.setDeformationResistance(0.78); // 0 很软，1 强形状恢复
body.setIterations(6);
body.setParticleRadius(0.11);
body.setPlasticity(0.32, 0.18, 0.25, 0.45); // yield, creep, recovery, max
body.setCollideWorld(world3);        // 借用 World3D；world 必须活得更久
body.update(dt);
renderer.setColor(0.96, 0.36, 0.20, 1.0);
renderer.draw(gfx);

运行时可用 getDeformationResistance()、getParticleRadius()、 getPlasticYield()、getPlasticCreep()、getPlasticRecovery() 和 getMaxDeformation() 回读材料参数；getCols()、getRows()、getLayers() 描述体积格分辨率。

getVolumeRatio() 返回当前 cell 总体积与初始体积之比，可用于测试、调试 UI 和 破坏判定。C++ 应优先使用 SoftBody3D::create() 的 Result<std::unique_ptr<SoftBody3D>>；Physics::newSoftBody3D() 是为脚本 VM 所有权模型保留的兼容工厂。求解由注入的 dt/SimulationStep 驱动，在同平台同 设置下提供容差有界确定性，不读取墙钟或随机源。当前版本使用 CPU cluster solver； 尚未包含任意网格体素化、蒙皮权重烘焙或 GPU backend。

创建配置由 SoftBody3DDefinition 统一拥有。其稳定 schema id 为 physics:softbody3d，当前版本为 1；toValue() / fromValue() 用于持久化边界， 版本 1 拒绝未知字段和未来版本。由于这是首个发布版本，没有旧版本迁移路径。 SoftBody3D::create(definition) 会先完整验证候选，再一次性创建运行时对象，不会在 验证失败时发布部分状态。编辑器侧使用 physics_editing::softBody3DDefinitionSchema()，其中包含全部 20 个可编辑字段的 默认值、数值范围、步长、单位、分类和说明；默认值直接取自 SoftBody3DDefinition，不是第二份配置真源。首次创建时还会幂等注册同版本的 Eve Schema，工具可通过 SchemaRegistry::resolve("physics:softbody3d", 1) 查询，并用 注册表执行通用 JSON 校验；聚合粒子数等跨字段约束仍由强类型 validate() 负责。

软体实现按 physics 宿主包内 satellite 拆分：physics/softbody 只包含 definition、 固定步长求解和窄碰撞接口；physics/softbody/graphics 负责动态表面网格； physics/softbody/editing 负责属性 schema。通用固定步长协议位于 physics/backend。主 physics 模块仅保留 World3D 接触适配、脚本绑定和旧工厂， 因此自定义无渲染组合可以只构建 EVPhysics_softbody，不拉入 graphics 或 editing； 现有预设 headless / server profile 并不默认启用软体。

颜色、动态 Mesh 缓存和绘制生命周期全部由 SoftBody3DRenderer 所有；它只借用 SoftBody3D，销毁软体前应调用 renderer.setBody(null)。核心 SoftBody3D 的公共头 不包含或前置声明任何 Graphics/Mesh 类型。renderer.getBody() 返回当前借用对象； physics.newSoftBody3DRenderer(body) 创建由脚本 VM 拥有的 renderer。

真实网格的离线生成入口使用 SoftBodyModelDefinition，稳定 schema id 为 physics:softbody-model、版本为 1。它记录 sourceMesh、surface/volume 采样模式、 三种分辨率、各向异性上限和位置平滑率；未知字段、未来版本、空资源引用以及同时关闭 surface/volume 采样都会被事务性拒绝。该能力统一使用 Model 命名。 physics/softbody/cook 将资产模块的 CanonicalMeshData 转为拥有全部数组的 cooked SoftBodyModel。v1 已支持按源顶点采样、保留三角形表面、生成直接粒子绑定以及基于一环邻域的 重叠 shape clusters；体素 surface/volume recipe 当前返回明确的 Unsupported，不会隐式改用顶点模式。

布料 GPU（2D，compute shader 加速）

newClothGPU(cols, rows, spacing, originX, originY) 创建与 Cloth 同接口的 GPU 布料：Verlet 积分和距离约束全部跑在 Vulkan compute shader 里（每粒子一个线程 + 双缓冲 Jacobi 约束迭代），每帧回读位置用于绘制。适合大批量粒子：

local clothModule = eve.Cloth();
local clothG = clothModule.newClothGPU(40, 30, 8.0, 40.0, 30.0); // 1200 粒子
clothG.setGravity(0, 980);
clothG.setBounds(0, 0, 800, 600);
clothG.setStiffness(0.9);
clothG.setIterations(4);
clothG.setSelfCollision(true);   // GPU 粒子级自碰撞（非相邻粒子 ≥ 2×particleSize）
clothG.setColor(0.6, 0.9, 0.7, 1.0);
clothG.update(dt);
clothG.draw(gfx);

接口与 2D Cloth 对齐（setGravity / setStiffness / setIterations / setDamping / setParticleSize / setSelfCollision / setBounds / pin / unpin / pinTopRow / applyForce / interactAt / setColor / reset）。自碰撞在 GPU 上做：设置了 setBounds 时用空间哈希（atomicExchange 每 cell 链表、无溢出，3×3 邻居遍历），可支持数万粒子；没有 bounds 时回退 O(n²) 扫描。默认关闭。约束求解是双缓冲 Jacobi：每次 dispatch 一 pass、外层按 setIterations 重复收敛，大网格需要更多迭代（如 100×80 建议 16–24）。注意粒子级自碰撞在极端压缩（如全部粒子被挤进角落）时无法保证完全分离——这是位置修正类自碰撞的共性限制；没有折角限制（需要时用 CPU 版）。每帧的积分 + 约束 + 哈希 + 回读通过 Gpgpu.Sequence 合成一次 GPU 提交（Sequence 自动在 dispatch 间插内存屏障，双缓冲因此正确）。需要 Gpgpu 模块和可用的 compute 后端；不可用时 newClothGPU 抛异常。

流体

local fluid = physics.newFluid2D(600);
fluid.setBounds(400, 48, 360, 500);
fluid.setGravity(0, 980);
fluid.emit(520, 100, 120, 0, 40);          // x, y, count, vx, vy
fluid.interactAt(mx, my, 70.0, -4200.0);   // 负值排斥，正值吸引
fluid.update(dt);
fluid.draw(gfx);

对象关系与调用时机

示例：examples/softbody/（2D 布料 + 流体）、examples/softbody3d/（3D 布料）

Physics 保存 2D 像素/米比例并创建 World / World3D / DistanceField3D / Cloth / Cloth3D / Fluid2D。World 管理 Body 与 Fixture；World3D 管理 Body3D、Shape3D 和 Joint3D。 布料、流体和距离场可按需组合；Cloth.setCollideWorld(world) / Cloth3D.setCollideWorld(world3) 可将布料接到刚体世界做碰撞。2D 碰撞消息为 begincontact / endcontact；3D 普通碰撞为 begincontact3d / endcontact3d，Sensor 重叠为 begintrigger3d / endtrigger3d，显著撞击为 hit3d。3D 消息的六个整数参数依次是 A/Sensor Body ID、B/Visitor Body ID、A/Sensor Shape ID、B/Visitor Shape ID、两个 Shape Tag； Hit 的浮点反馈从 World3D 当帧缓冲读取。查询结果对应上一次查询写入的缓存。

每帧：world.update / world3.update / cloth.update / cloth3.update / fluid.update 各调用一次；绘制在 eve_render 中用 draw / drawDebug。

目标导向指南

创建会落地的角色（2D）

1. 用 setMeter(30) 定义像素与米的比例。
2. 创建向下重力的 World。
3. 地面用 static Body，角色用 dynamic Body。
4. 给 Body 创建矩形或圆形 Fixture，配置密度、摩擦和弹性。
5. 每帧只调用一次 world.update(dt)，渲染位置从 body.getX/Y() 读取。

创建会落地的物体（3D）

1. newWorld3D(0, -9.8, 0)：坐标与重力均以米为单位。
2. 地面 static + newBoxShape；动态体用 box / sphere / capsule。
3. 每帧 world3.update(dt)；位置 getX/Y/Z，姿态四元数 getRotX/Y/Z/W。
4. 拾取：shape.testPoint(x,y,z)、world3.rayCast、world3.queryAABB(min…, max…)。

精细控制 3D 刚体

Body3D 提供逐刚体的线性/角阻尼、重力倍率、睡眠开关和睡眠阈值。角色可用 setGravityScale(0) 暂停重力，水下物体可配合较高 setLinearDamping()；阻尼和睡眠阈值 必须是有限非负数，重力倍率允许为负。getMass() 返回 Shape 密度和体积计算出的千克质量， getLocalCenterX/Y/Z() 与 getWorldCenterX/Y/Z() 可用于施力、相机跟随和特效定位。

动态刚体还可用 setMassProperties(mass, centerX,centerY,centerZ, inertiaXX,inertiaYY,inertiaZZ, inertiaXY,inertiaXZ,inertiaYZ) 覆盖自动质量、局部质心和关于质心的对称惯性张量；这适用于 车辆配重、偏心道具以及碰撞外形不等同于质量分布的复合体。质量必须为正，惯性张量必须有限且 正定。六个惯性分量可由 getInertiaXX/YY/ZZ/XY/XZ/YZ() 读取；调用 resetMassProperties() 会重新按当前 Shape 的密度和几何计算全部质量属性。添加/删除 Shape 或 切换 Body 类型也会触发 Box3D 自动重算，因此应在这些结构变更完成后再设置自定义质量属性。

player.setLinearDamping(3.0);
player.setAngularDamping(6.0);
player.setGravityScale(1.0);
player.setSleepEnabled(false);

// 直立角色：锁定水平外的位移轴按项目需要配置，并禁止所有自转。
player.setMotionLocks(false, false, false, true, true, true);

setMotionLocks(linearX, linearY, linearZ, angularX, angularY, angularZ) 原子设置六个自由度， 对应状态由 isLinear*Locked() / isAngular*Locked() 查询；setFixedRotation(true) 仍可作为 锁定三个角轴的快捷方式。applyTorque() 施加持续一帧的世界空间力矩， applyLinearImpulseAt() 在指定世界坐标施加瞬时冲量，因此可同时改变线速度和角速度。

车辆、炮塔和布娃娃通常在自身坐标系中工作。localToWorldPoint() / worldToLocalPoint() 转换 位置，localToWorldVector() / worldToLocalVector() 只旋转方向；它们均返回三元素数组。 getLocalPointVelocity(localX,localY,localZ) 与 getWorldPointVelocity(worldX,worldY,worldZ) 返回指定刚体点的世界速度，其中包含角速度产生的切向速度，适合轮胎滑移、接触音效和平台载人。

applyLocalForce()、applyLocalLinearImpulse() 的力/冲量与作用点都使用刚体局部坐标； applyLocalForceToCenter()、applyLocalLinearImpulseToCenter() 是质心快捷方式， applyLocalTorque() 和 applyLocalAngularImpulse() 同样会把局部轴旋转到世界空间。所有新接口 拒绝 NaN 和无穷值，避免无效数进入求解器。

移动平台应使用 kinematic Body，并在物理更新前调用 setTargetTransform(x,y,z,qx,qy,qz,qw,timeStep)；引擎会计算到达目标所需的线速度和角速度， 从而让接触物体获得正确的平台速度。timeStep 必须大于零，四元数会归一化。

3D 距离关节与旋转铰链

world3.newDistanceJoint(bodyA, bodyB, anchorAX,anchorAY,anchorAZ, anchorBX,anchorBY,anchorBZ, length, collideConnected) 用两个世界空间锚点创建绳索/拉杆约束。 刚性模式保持固定长度；setDistanceSpring(true,hertz,damping) 启用弹簧， setDistanceLimits() 设置伸缩范围，setDistanceMotor() 可驱动长度变化。实时长度由 getDistanceCurrentLength() 读取。

local rope = world3.newDistanceJoint(ceiling, crate,
    0, 5, 0,       // ceiling 世界锚点
    0, 2, 0,       // crate 世界锚点
    3.0, false);
rope.setDistanceSpring(true, 4.0, 0.7);
rope.setDistanceLimits(true, 2.5, 3.5);

world3.newRevoluteJoint(bodyA,bodyB, anchorX,anchorY,anchorZ, axisX,axisY,axisZ, collideConnected) 创建世界空间轴向的门轴/转轴。轴会归一化；零长度或非有限轴会抛出异常。 角度和角速度使用弧度：setRevoluteLimits() 配置转角范围，setRevoluteMotor() 配置目标转速 及最大扭矩，setRevoluteSpring() 可将转轴拉回目标角度。

local hinge = world3.newRevoluteJoint(frame, door, 0, 1, 0, 0, 1, 0, false);
hinge.setRevoluteLimits(true, -1.57, 1.57);
hinge.setRevoluteMotor(true, 1.0, 40.0);

newPrismaticJoint() 使用同样的世界锚点和世界轴参数创建滑轨。连接体只能沿轴平移且不能 相对旋转；setPrismaticLimits() 适合行程边界，setPrismaticMotor() 适合电梯、活塞和自动门， setPrismaticSpring() 可制作悬挂或缓冲器。当前位置、速度和电机力分别由 getPrismaticTranslation()、getPrismaticSpeed()、getPrismaticMotorForce() 读取。

local lift = world3.newPrismaticJoint(frame, platform, 0, 0, 0, 0, 1, 0, false);
lift.setPrismaticLimits(true, 0, 6);
lift.setPrismaticMotor(true, 2, 5000);

newSphericalJoint() 创建球窝/点对点关节，常用于肩、髋和吊挂物。传入的世界轴定义圆锥中心 和扭转轴；setSphericalConeLimit() 限制摆角，setSphericalTwistLimits() 限制扭转， setSphericalMotor() 用三轴角速度和最大扭矩驱动。当前圆锥角与扭转角可实时查询，用于 动画混合或关节受伤判定。

local shoulder = world3.newSphericalJoint(torso, arm, 0, 1.5, 0, 0, 1, 0, false);
shoulder.setSphericalConeLimit(true, 1.0);
shoulder.setSphericalTwistLimits(true, -0.5, 0.5);

newWheelJoint(chassis,wheel, anchor, suspensionAxis, wheelAxis, collideConnected) 是车辆专用 复合约束。悬挂轴决定轮毂上下行程和转向轴，轮轴决定自转方向；两轴不能平行。 setWheelSuspension() 配置弹簧与阻尼，setWheelSuspensionLimits() 限制压缩/回弹行程， setWheelSpinMotor() 驱动车轮，setWheelSteering() 以弹簧伺服追踪目标转角， setWheelSteeringLimits() 限制最大舵角。

// Y 向悬挂，Z 向轮轴。
local wheel = world3.newWheelJoint(chassis, frontLeft,
    -0.9, -0.4, 1.2,
    0, 1, 0,
    0, 0, 1,
    false);
wheel.setWheelSuspension(true, 5.0, 0.7);
wheel.setWheelSuspensionLimits(true, -0.25, 0.15);
wheel.setWheelSpinMotor(true, 20.0, 800.0);
wheel.setWheelSteering(true, steeringAngle, 8.0, 0.9, 1200.0);
wheel.setWheelSteeringLimits(true, -0.6, 0.6);

getWheelSpinSpeed() / getWheelSpinTorque() 可用于轮胎音效和牵引控制， getWheelSteeringAngle() / getWheelSteeringTorque() 可驱动视觉轮毂和反馈方向盘。

所有关节均提供稳定 ID、连接 Body ID、getConstraintForce*()、 getConstraintTorque*() 和分离误差，适合调试约束、声音与破坏判定。销毁任一连接 Body 或 World 会使 Joint3D 包装器安全失效；也可显式调用 joint.destroy()。默认连接体互不碰撞， 可在创建时或通过 setCollideConnected(true) 开启。

需要可破坏结构时，用 setForceThreshold(newtons) 和 setTorqueThreshold(newtonMetres) 配置关节应力事件。任一阈值被超过的物理帧会发送 jointstress3d，四个整数参数依次为 Joint ID、Body A ID、Body B ID、关节类型代码 （0 Distance、1 Revolute、2 Prismatic、3 Spherical、4 Wheel）。同一帧的精确求解器力和扭矩从 getJointStressForceX/Y/Z()、getJointStressTorqueX/Y/Z() 读取；事件缓冲会在下一次 world3.update() 前清空。

rope.setForceThreshold(2500);
rope.setTorqueThreshold(1000);

world3.update(dt);
for (local i = 0; i < world3.getJointStressCount(); ++i) {
    local id = world3.getJointStressJointId(i);
    local fx = world3.getJointStressForceX(i);
    local fy = world3.getJointStressForceY(i);
    local fz = world3.getJointStressForceZ(i);
    local force = sqrt(fx * fx + fy * fy + fz * fz);
    // 按 ID 找到游戏侧关节；达到项目断裂强度时调用 joint.destroy()。
}

事件本身不会自动销毁关节，游戏可以根据材质、耐久度或短时峰值过滤决定是否断裂，避免 单帧冲击造成不可控破坏。

制作触发区域

把 Fixture / Shape3D 设为 sensor。2D 监听 begincontact / endcontact；3D 监听独立的 begintrigger3d / endtrigger3d，或逐帧读取 getBeginTrigger* / getEndTrigger* 缓冲。Sensor 不产生碰撞推力，适合传送门、拾取物和区域检测。Trigger API 明确区分 Sensor 与 Visitor，不依赖底层碰撞器顺序。调试时调用 world.drawDebug(gfx) 核对 2D 形状。

组合 3D 碰撞体

一个 Body3D 可以挂多个具有独立局部变换的 Shape3D，用于角色头部/躯干/脚底、车辆车身或 武器碰撞区。setLocalTransform(px, py, pz, qx, qy, qz, qw) 会原子设置相对 Body 的米制 位移和四元数旋转；也可分别调用 setLocalPosition() / setLocalRotation()。四元数会自动 归一化，零长度或非有限参数会抛出异常。

local body = world3.newBody("dynamic", 0, 2, 0);
local torso = body.newCapsuleShape(1.2, 0.35);
torso.setTag(1);
torso.setLocalPosition(0, 0.9, 0);

local head = body.newSphereShape(0.3);
head.setTag(2);
head.setLocalPosition(0, 1.8, 0);

local footSensor = body.newBoxShape(0.5, 0.1, 0.5);
footSensor.setTag(3);
footSensor.setLocalPosition(0, 0.05, 0);
footSensor.setSensor(true);

局部 Transform 更新会安全重建底层 Box3D 几何，但 wrapper 的稳定 Shape ID、Tag、碰撞过滤、 材质、Sensor 状态和 Hit Event 偏好保持不变；由重建产生的 End Contact/Trigger 仍携带正确 快照。Box 支持完整局部旋转，Capsule 的轴随局部四元数旋转，Sphere 只使用局部平移。

Primitive 尺寸也可在运行时原子修改：Box 使用 setBoxSize(width, height, depth)，Sphere 使用 setSphereRadius(radius)，Capsule 使用 setCapsuleSize(height, radius)；Capsule 的 height 是两个半球中心之间的线段长度，因此总高度为 height + 2 * radius。getKind() 返回 "box" / "sphere" / "capsule" / "convexHull"，对应 Primitive 尺寸可通过 getBoxWidth/Height/Depth()、 getRadius() 和 getCapsuleHeight() 读取。错误类型、非有限值、非正尺寸会在修改前抛出异常。

// 蹲伏：保持脚底位置不变，同时缩短角色胶囊。
playerCapsule.setCapsuleSize(0.7, 0.35);
playerCapsule.setLocalPosition(0, 0.35 + 0.35, 0);

// 站起前先用 queryCapsule 检查头顶空间，再一次性恢复尺寸。
if (world3.queryCapsule(ax, ay, az, bx, by, bz, 0.35) == 0) {
    playerCapsule.setCapsuleSize(1.4, 0.35);
}

尺寸重建与局部 Transform 使用相同的配置保持规则，并自动重新计算动态 Body 的质量和惯性。 如果需要同时修改尺寸与局部位置以固定脚底，建议先做空间查询，再连续完成两项修改，避免在 物理步进之间留下中间状态。

任意凸包碰撞体

Body3D.newConvexHullShape(vertices, maxVertices) 从扁平的局部空间 XYZ 数组建立凸包，适合 斜坡、岩石、道具和低多边形动态物体。至少需要四个有限且不共面的点；maxVertices 为 4–254 的简化预算，常用 16–64。输入点不必按面排序，也不需要三角形索引。

local wedge = body.newConvexHullShape([
    -2, -0.5, -2,   2, -0.5, -2,
    -2, -0.5,  2,   2, -0.5,  2,
    -2,  0.5, -2,   2,  0.5, -2
], 32);
wedge.setTag(20);
wedge.setFriction(0.8);

运行时可用 setConvexHullVertices(vertices, maxVertices) 原子替换源点；退化、非有限或格式错误 的输入会在旧碰撞体被修改前抛出异常。稳定 Shape ID、Tag、材质、Layer、Sensor、Hit Event、 单向配置和局部 Transform 均保持不变。getConvexHullPointCount() 返回源点数， getConvexHullMaxVertices() 返回当前预算。

凸包始终填充点集内部，不能表达洞穴、门框或内凹地形。动态凹物体应拆为多个凸包并挂到 同一个 Body3D；大型静态环境使用下一节的 Triangle Mesh Collider。不要把数万渲染顶点直接 交给单个凸包。凸包源点上限为 100000，但实时内容应先离线简化，以控制烘焙和窄相成本。

静态三角网格碰撞体

Body3D.newTriangleMeshShape(vertices, indices) 创建可表达空洞和内凹结构的静态网格碰撞器。 vertices 是局部 XYZ 数组，indices 每三个值组成一个三角形；从可碰撞一侧观察，顶点应按 逆时针排列。网格只能挂在 static Body 上，创建后该 Body 也不能改为 dynamic/kinematic。

local level = world3.newBody("static", 0, 0, 0);
local floor = level.newTriangleMeshShape([
    -10, 0, -10,   10, 0, -10,
     10, 0,  10,  -10, 0,  10
], [0, 2, 1, 0, 3, 2]); // +Y 一侧可碰撞

默认会以 0.001m 容差焊接邻近顶点并识别共享边，减少相邻三角形接缝处的幽灵碰撞。 newTriangleMeshShapeFull(vertices, indices, weld, tolerance, identifyEdges, medianSplit) 可控制 烘焙：规则地形网格可开启 medianSplit 加快 BVH 构建；非规则关卡通常保留 SAH 默认值。 运行时对应 setTriangleMeshData() / setTriangleMeshDataFull()，并保持稳定 ID、Tag、Layer、 材质、Sensor、Hit Event、单向配置和局部 Transform。局部 Transform 会烘焙到网格顶点。

引擎会在调用 Box3D 前验证数组格式、索引范围、有限坐标、焊接容差和零面积三角形；失败时 旧碰撞器保持不变。getTriangleMeshVertexCount() / getTriangleMeshTriangleCount() 返回源数据 规模。当前硬上限为 100 万顶点、200 万三角形；生产关卡仍应分块并离线简化，以改善流式加载、 BVH 重建和宽相更新成本。需要移动的复杂物体应使用复合凸包，而不是移动 Triangle Mesh。

高度场地形碰撞体

规则地形使用 newHeightFieldShape(countX, countZ, cellSizeX, cellSizeZ, heights)。高度按 z * countX + x 行优先排列，单位为米；网格从 Body 局部原点向 +X/+Z 展开。简单版本自动 从数据求量化范围，完整版本可显式指定共享范围和三角形朝向：

local terrainBody = world3.newBody("static", originX, originY, originZ);
local terrain = terrainBody.newHeightFieldShapeFull(
    257, 257, 1.0, 1.0, heights,
    -256.0, 256.0, false
);

相邻地形块应使用完全相同的 globalMin/globalMax，这样边界顶点经过 16 位压缩后仍能精确对齐， 避免接缝。所有源高度必须位于该范围内；引擎不会静默裁剪。clockwise=false 默认从上方碰撞， 设为 true 会反转可碰撞侧。

setHeightFieldHeights(values) 可全量更新，setHeightFieldRegion(x, z, width, depth, values) 可更新矩形采样区；修改会原子重建压缩数据，同时保持稳定 Shape ID、Tag、Layer、材质、Sensor、 Hit Event 和单向配置。可通过 getHeightFieldHeight()、getHeightFieldCountX/Z()、 getHeightFieldCellSizeX/Z() 和 getHeightFieldGlobalMin/Max() 读取源元数据。

HeightField 只能挂在 static Body 上，定位和旋转使用 Body Transform。Box3D 不提供 HeightField 子形状 Transform，因此该类型的 setLocalPosition/Rotation/Transform 只接受单位变换并在其他 输入时报错。每个地形块通常使用独立 Body。区域更新目前会重建整块压缩数据，频繁雕刻应使用 较小分块并把多次编辑合并到一帧；单块上限为 1600 万采样点。

单向 3D 平台

Shape3D.setOneWay(nx, ny, nz, planeOffset, margin, minNormalDot) 为碰撞器配置局部空间的 单向接触平面。法线指向允许站立的一侧并会自动归一化；planeOffset 是平面沿该法线相对 Shape 原点的距离。以中心位于原点、高度为 0.5m 的 Box 平台为例，其上表面偏移为 0.25m：

local platform = world3.newBody("static", 0, 0, 0).newBoxShape(10, 0.5, 10);
platform.setOneWay(0, 1, 0, 0.25, 0.05, 0.2);

// 暂时恢复双面碰撞；原配置直到再次 setOneWay 前保持在 wrapper 中。
platform.disableOneWay();

margin 为允许侧的位置容差，通常使用 0.02–0.08m；minNormalDot 限制接触外法线与平台 法线的夹角，常用 0.1–0.3，可避免侧边接触阻挡从下方穿越。局部/Body 旋转和平移后，平面 会在每次物理步进前更新。过滤发生在 Box3D 的线程安全 pre-solve 阶段，不调用脚本。Sensor 期间不产生求解接触，恢复普通 Shape 后单向配置仍生效；isOneWay() 可查询状态。

单向规则只影响刚体求解，Ray、Overlap、Closest Point 和 Shape Cast 仍把几何视为双面；游戏 逻辑可根据命中法线和移动方向自行忽略查询结果。极高速运动建议同时使用 Shape Cast 预测， 因为底层连续碰撞的 pre-solve 回调在极端速度下可能暂停运动，而不是可靠穿过平台。

物理体拾取与视线

• fixture.testPoint(x, y) / shape3.testPoint(x, y, z) — 点是否在形状内
• world.rayCast / world3.rayCast — 段上最近命中，返回 body id（未命中 -1）
• world3.rayCastAll(x1, y1, z1, x2, y2, z2, maxHits) — 收集指定容量内最近的全部射线命中
• world.queryAABB(x, y, w, h) — 2D 轴对齐盒（原点+宽高）
• world3.queryAABB(minX, minY, minZ, maxX, maxY, maxZ) — 3D AABB（角点）
• world3.querySphere(x, y, z, radius) — 精确球体重叠查询
• world3.queryCapsule(ax, ay, az, bx, by, bz, radius) — 精确任意朝向胶囊重叠查询
• world3.queryBox(x, y, z, width, height, depth, qx, qy, qz, qw) — 精确有向盒重叠查询
• world3.castSphere(x, y, z, radius, dx, dy, dz) — 沿位移连续扫描球体
• world3.castSphereAll(..., maxHits) — 有界收集最近的全部球体扫描命中
• world3.castCapsule(ax, ay, az, bx, by, bz, radius, dx, dy, dz) — 连续扫描胶囊体
• world3.castCapsuleAll(..., maxHits) — 有界收集最近的全部胶囊扫描命中
• world3.castBox(x, y, z, width, height, depth, qx, qy, qz, qw, dx, dy, dz) — 连续扫描有向盒
• world3.castBoxAll(..., maxHits) — 有界收集最近的全部有向盒扫描命中
• world3.closestPoint(x, y, z, maxDistance) — 查询过滤层内最近碰撞表面、法线和距离

形状扫描返回最早命中的 body id；接触点、法线和 [0,1] 位移分数分别通过 getShapeCastX/Y/Z、getShapeCastNormalX/Y/Z 和 getShapeCastFraction 读取。 Box3D 形状扫描忽略起始重叠，因此直接使用 cast 组合移动逻辑时，应先用 querySphere / queryCapsule 处理已经发生的穿透。

三个 cast*All 与 rayCastAll 使用相同的 [1,4096] 容量、近邻保留和确定排序规则。 返回结果通过 getShapeCastResultCount()、getShapeCastResultBodyId()、 getShapeCastResultShapeId()、getShapeCastResultShapeTag()、getShapeCastResultX/Y/Z()、 getShapeCastResultNormalX/Y/Z() 和 getShapeCastResultFraction() 读取。旧的单命中 cast* 使用容量 1 的同一实现，因此 getShapeCast* 始终与结果 index 0 一致。

local count = world3.castCapsuleAll(ax, ay, az, bx, by, bz, radius,
                                    attackDx, attackDy, attackDz, 16);
for (local i = 0; i < count; ++i) {
    local hurtboxTag = world3.getShapeCastResultShapeTag(i);
    local fraction = world3.getShapeCastResultFraction(i);
    // 宽体穿透攻击、相机防穿或预测路径响应。
}

重叠查询的返回值和 getQueryBodyId() 仍按唯一 Body 统计；当一个 Body 含有多个碰撞器时， 使用 getQueryShapeCount() / getQueryShapeId() 读取全部命中 Shape。Shape ID 在其生命周期内 稳定，setSensor() 导致底层碰撞形状重建时也不会改变。Ray、Shape Cast 和最近点查询分别通过 getRayHitShapeId()、getShapeCastShapeId()、getClosestShapeId() 返回具体碰撞器。 Shape3D.setTag(integer) 可保存游戏定义的碰撞器用途（如头部、弱点、攀爬面）；对应的 get*ShapeTag() 或 getQueryShapeTag(index) 无需额外 ID 映射即可读取，Tag 同样跨 Sensor 重建保留。

Triangle Mesh 或 HeightField 命中还可读取具体面索引：最近 Ray 使用 getRayHitTriangleIndex()，Ray All 使用 getRayResultTriangleIndex(i)；Shape Cast 对应 getShapeCastTriangleIndex() 和 getShapeCastResultTriangleIndex(i)。Primitive 或未命中返回 -1。该索引可用于弹孔、脚步声、地形编辑和导航面定位。

Triangle Mesh 返回 Box3D 烘焙后的三角形索引，BVH 烘焙可能重排源面；HeightField 返回压缩 网格的三角形索引。索引在碰撞数据不变时稳定，但调用 setTriangleMeshData*()、 setHeightFieldHeights() 或 setHeightFieldRegion() 重建后应重新查询，不能把旧 face index 当作 长期资源 ID。需要关联渲染面或材质时，应在烘焙阶段保存显式映射。

rayCastAll 返回缓存数量，结果用 getRayResultCount() 和 getRayResultBodyId()、 getRayResultShapeId()、getRayResultShapeTag()、getRayResultX/Y/Z()、 getRayResultNormalX/Y/Z()、getRayResultFraction() 逐项读取。maxHits 必须在 [1,4096]； 缓存只保留最近的 N 项，并在遍历中用当前最远结果裁剪 broad-phase，不会先无限收集再截断。 结果按 fraction 升序排列，相同 fraction 按稳定 Shape ID 排列。rayCast() 复用相同缓存并将 容量设为 1，因此旧的 getRayHit* 与新的 index 0 始终表示同一个最近命中。

local count = world3.rayCastAll(muzzleX, muzzleY, muzzleZ, endX, endY, endZ, 8);
for (local i = 0; i < count; ++i) {
    local bodyId = world3.getRayResultBodyId(i);
    local materialTag = world3.getRayResultShapeTag(i);
    local distanceFraction = world3.getRayResultFraction(i);
    // 穿透射击、遮挡层或沿线材质处理。
}

World3D.update() 每次调用会清空上一帧并收集新的事件。普通碰撞通过 getBeginContactCount() / getEndContactCount() 和对应的 BodyA/BId、ShapeA/BId、 ShapeA/BTag getter 读取；双方按稳定 Shape ID 排序，结果不依赖 Box3D 内部遍历顺序。 Trigger 使用 getBeginTriggerCount() / getEndTriggerCount()，并提供明确命名的 Sensor* 与 Visitor* getter。事件保存稳定 ID/Tag 快照，所以由移动、过滤器修改、 Sensor 重建或销毁引发的 end 事件仍可安全读取。clearContactEvents() 可提前清空全部事件缓冲。

Begin/End 适合状态切换，持续贴地、轮胎抓地或墙面摩擦则可调用 queryBodyContacts(bodyId, maxPoints) 查询当前仍在 touching 的 manifold point，容量范围为 [1,4096]。结果统一以被查询 Body 为自身：getContactPointShapeId/Tag() 是自身 Shape， getContactPointOtherBodyId() 与 getContactPointOtherShapeId/Tag() 是对方；法线始终从自身 指向对方，不受 Box3D 内部 A/B 顺序影响。

getContactPointX/Y/Z() 返回自身表面上的世界点，getContactPointNormalX/Y/Z() 返回重定向 后的法线，getContactPointSeparation() 返回有符号间距（负数为穿透）。 getContactPointNormalImpulse() 是最终子步冲量，getContactPointTotalNormalImpulse() 是整次 World step 全部子步的累计冲量，getContactPointNormalVelocity() 是预求解法向相对速度 （负数表示接近），isContactPointPersisted() 表示该 feature 是否从上一物理步延续。 结果按自身 Shape ID、对方 Shape ID 和 feature ID 确定排序后截断。

local count = world3.queryBodyContacts(playerBody.getId(), 16);
for (local i = 0; i < count; ++i) {
    local upDot = world3.getContactPointNormalY(i); // 默认 Y-up 时，自身→地面通常为负
    local supportImpulse = world3.getContactPointTotalNormalImpulse(i);
    local surfaceTag = world3.getContactPointOtherShapeTag(i);
    // 识别支撑面、落地强度、摩擦材质或车轮抓地。
}

这是按需诊断/玩法查询；大量对象的常规状态切换仍应优先消费 Begin/End/Hit 事件，避免每帧为 所有 Body 提取 manifold。

需要碰撞音效、落地强度或撞击伤害时，在相关碰撞器调用 shape.setHitEventsEnabled(true)，并可用 world3.setHitEventThreshold(speed) 设置全局最低接近 速度（m/s）。Hit 默认按 Shape 关闭以避免不需要的事件开销；开关偏好跨 Sensor 重建保留， 但 Sensor 本身不会生成物理撞击。每帧用 getHitCount() 遍历，通过 getHitBodyA/BId()、 getHitShapeA/BId() 和 getHitShapeA/BTag() 识别对象；getHitPointX/Y/Z() 返回世界接触点， getHitNormalX/Y/Z() 返回由稳定 A 侧指向 B 侧的法线，getHitApproachSpeed() 返回正的预求解 接近速度，getHitNormalImpulse() 返回所有接触 manifold 在全部子步累积的总法向冲量。

crateShape.setHitEventsEnabled(true);
world3.setHitEventThreshold(2.0);
world3.update(dt);
for (local i = 0; i < world3.getHitCount(); ++i) {
    local strength = world3.getHitNormalImpulse(i);
    local speed = world3.getHitApproachSpeed(i);
    // 按 strength / speed 选择音量、粒子规模或伤害。
}

角色控制器可直接调用 world3.moveCapsule(...)。它将穿透恢复、多接触平面约束和连续 扫描组合在最多五轮求解中；最终安全位移通过 getMoverDeltaX/Y/Z 读取，主要阻挡法线、 参与约束的平面数和迭代数可通过 getMoverNormalX/Y/Z、getMoverPlaneCount、 getMoverIterations 获取。调用方应把返回位移加到角色位置，而不是直接应用原始输入位移。

用 setMoverUp(x,y,z) 配置重力反方向，用 setMoverSlopeLimit(degrees) 设置最大可行走 坡度。每次移动后，isMoverGrounded() 表示是否接触可行走表面， getMoverGroundDot() 返回接触法线与 up 的最大点积，可用于落地、跳跃和斜坡动画状态。

3D 碰撞分层

Shape3D 与 2D Fixture 一样提供 setCategoryBits、setMaskBits 和 setGroupIndex。查询侧通过 world3.setQueryFilter(categoryBits, maskBits) 配置，之后的 ray cast、overlap、shape cast 和 capsule mover 都使用该过滤器；调用 resetQueryFilter() 恢复接受所有低 32 位 category。切换 sensor 时过滤设置会被保留。

连续碰撞与求解器调优

World3D 默认启用连续碰撞。高速动态物体撞击静态场景时应保持 setContinuousCollisionEnabled(true)；对于还需要动态物体之间 CCD 的子弹、弹片等物体， 同时对相应 Body3D 调用 setBullet(true)。

world3.setContinuousCollisionEnabled(true)
world3.setMaximumLinearSpeed(250.0)
world3.setRestitutionThreshold(1.0)

// 接触刚度 Hz、阻尼比、最大穿透修正速度（m/s）
world3.setContactTuning(30.0, 10.0, 3.0)
world3.setContactRecycleDistance(0.01)
world3.setWarmStartingEnabled(true)

较高的接触刚度会更快消除穿透，但也可能带来抖动；降低阻尼会让修正更有弹性。 setMaximumLinearSpeed 是全世界速度安全上限，适合约束异常力或错误脚本产生的极端速度。 接触点复用可以改善静止堆叠的帧间稳定性，设为 0 可关闭。Warm Starting 对稳定堆叠和关节很重要， 通常只应在求解器诊断或确定性对比时关闭。所有调优参数都可通过对应 get* / is* 方法读取。

高级表面材质与传送带

除摩擦、反弹和密度外，Shape3D 还支持滚动阻力、局部切向速度及应用材质 ID：

local belt = floorBody.newBoxShape(12.0, 0.5, 2.0)
belt.setFriction(0.9)
belt.setTangentVelocity(3.0, 0.0, 0.0) // 局部 +X 方向传送带
belt.setMaterialId(1001)                // 脚步声、粒子或游戏材质表索引

local tire = wheelBody.newSphereShape(0.45)
tire.setRollingResistance(0.04)

切向速度会随 Shape 的朝向旋转，并投影到接触平面，因此旋转传送带形状即可改变输送方向。 滚动阻力只对球体和胶囊体产生物理效果。材质 ID 保留完整低 32 位，可作为有符号脚本整数往返； 切换 Sensor 或运行时重建几何时，高级材质参数都会保留。Ray Cast 可通过 getRayHitMaterialId() / getRayResultMaterialId(i) 读取实际命中的表面材质；Shape Cast 对应使用 getShapeCastMaterialId() / getShapeCastResultMaterialId(i)，并与三角形索引一起 支持地面音效、轮胎反馈、弹孔和粒子效果的材质分派。

每个 Shape 还能独立指定摩擦和反弹的混合策略：

ice.setFrictionCombineMode("minimum")
bumper.setRestitutionCombineMode("maximum")

可选值为 default、average、minimum、multiply、maximum。当接触两侧模式不同， 按 maximum > multiply > minimum > average > default 的优先级选择，行为与常见商业引擎的 Physics Material 规则一致。default 保持 Box3D 原生行为：摩擦取几何平均，反弹取最大值。 混合模式编码在内部材质元数据中，修改应用材质 ID 或重建 Shape 都不会丢失。

Triangle Mesh 多材质

静态 Triangle Mesh 可以为每个源三角形选择最多 255 个材质槽：

mesh.setTriangleMeshMaterialIndices([0, 0, 1, 1])
mesh.setTriangleMeshMaterial(
    0, 0.8, 0.0, 0.02, 0.0, 0.0, 0.0, 100, "average", "default")
mesh.setTriangleMeshMaterial(
    1, 0.05, 0.1, 0.0, 0.0, 0.0, 0.0, 200, "minimum", "maximum")

参数依次为槽位、摩擦、反弹、滚动阻力、局部切向速度 XYZ、应用材质 ID、摩擦混合模式和 反弹混合模式。材质槽可运行时更新而无需重建 BVH；更改逐三角形映射时会原子重建碰撞网格。 Ray Cast 和 Shape Cast 返回的是实际命中三角形的材质 ID，而非统一的 Shape 默认值。

运行时接触覆盖

临时穿透角色、队友免碰撞、抓取物体忽略玩家碰撞等场景，可以覆盖指定 Body 对或 Shape 对， 无需改写双方长期使用的 Layer/Mask：

world3.setBodyPairCollisionEnabled(player, carriedObject, false)
world3.setShapePairCollisionEnabled(characterShape, oneSpecificDoorShape, false)

// 放下物体或门重新实体化时恢复
world3.setBodyPairCollisionEnabled(player, carriedObject, true)

isBodyPairCollisionEnabled 和 isShapePairCollisionEnabled 可读取当前覆盖状态。修改会立即刷新 现有接触并同时作用于普通碰撞、CCD 和 Sensor 重叠；Layer/Mask 仍先执行，因此启用覆盖不会绕过 原有碰撞层过滤。规则使用稳定 Body/Shape ID，无论参数顺序如何结果一致，并在对象销毁时自动清理。

径向爆炸与内爆

World3D.explode 按物体朝向爆心的投影面积施加真实几何冲量，而不是简单修改速度：

local affected = world3.explode(
    blastX, blastY, blastZ,
    2.0, 6.0, 35.0, LAYER_DESTRUCTIBLE)

for (local i = 0; i < affected; ++i) {
    local bodyId = world3.getExplosionResultBodyId(i)
    local dvx = world3.getExplosionResultDeltaVelocityX(i)
}

前三个物理参数依次为满强度半径、额外线性衰减距离和每平方米冲量；负冲量产生内爆。 爆炸只影响通过 maskBits 的动态球体、胶囊和凸形状；静态/运动学 Body、Triangle Mesh 与 Height Field 不会获得冲量。结果按稳定 Body ID 排序，并缓存实际造成的线速度和角速度变化， 便于伤害、镜头震动、联网同步和调试。

每个 Shape3D 可用 setExplosionScale(scale) 调整响应：1 为默认，0 完全免疫， 大于 1 可表现轻质碎片或弱点。复合 Body 上各 Shape 的冲量会累积；倍率会在 Sensor 切换、 尺寸调整及网格重建时保留。getExplosionScale() 可用于编辑器属性面板和运行时检查。

世界诊断与性能面板

World3D 暴露无需暂停模拟即可读取的统计数据：

local bodies = world3.getBodyCount()
local contacts = world3.getContactCount()
local memoryBytes = world3.getMemoryByteCount()
local physicsMs = world3.getProfileStepMs()
local solveMs = world3.getProfileSolveMs()

计数器还包括 Shape、Joint、Island、Awake Body/Contact、复用接触点，以及静态/动态宽相树高度。 getProfilePairsMs、getProfileCollideMs、getProfileBulletsMs 和 getProfileSensorsMs 可定位宽相、窄相、CCD 与 Sensor 开销。getBoundsMin* / getBoundsMax* 返回当前世界宽相边界， 适合编辑器取景、流式场景分区和异常物体越界检测。时间单位均为毫秒。

发起者需要排除自身时，调用 setQueryIgnoredBodyId(body.getId()) 会跳过该 Body 的全部复合 Shape；setQueryIgnoredShapeId(shape.getId()) 只跳过一个碰撞器。两项排除可同时生效，并统一 应用于 Ray、AABB/精确 Overlap、Sphere/Capsule/Box Cast、Closest Point 和 Capsule Mover。 传入 -1 可单独关闭一项，clearQueryIgnores() 同时清除两项但不改变 Layer Filter。 最近命中在相同 fraction 时按稳定 Shape ID 决胜，避免 broad-phase 遍历顺序导致结果漂移。

const LAYER_WORLD  = 1;
const LAYER_PLAYER = 2;
const LAYER_TRIGGER = 4;

groundShape.setCategoryBits(LAYER_WORLD);
triggerShape.setCategoryBits(LAYER_TRIGGER);
triggerShape.setSensor(true);

// 角色移动只碰撞世界，不被 trigger 阻挡。
world3.setQueryFilter(LAYER_PLAYER, LAYER_WORLD);
world3.setQueryIgnoredBodyId(playerBody.getId());
world3.moveCapsule(ax, ay, az, bx, by, bz, radius, dx, dy, dz);

可交互布料（2D / 3D）

1. 通过 eve.Cloth() 子模块调用 newCloth(cols, rows, spacing, originX, originY)（2D 像素）或 newCloth3D(cols, rows, spacing, originX, originY, originZ)（3D 米）— 默认钉住顶行。
2. setBounds 限制摆动范围；applyForce 可作风场。
3. grabAt / moveGrab / releaseGrab 做鼠标拖拽；pin / unpin 控制固定点。
4. setSelfCollision(true) 开启自碰撞（3D 含三角面级）；setMaxFoldAngle / setFoldStiffness 控制折角限制（3D 为相邻三角面二面角）。
5. setCollideWorld(world) / setCollideWorld(world3) 让布料与刚体碰撞（按质量比例动量交换）；interactAt 做指针吸引/排斥（与流体一致）。
6. draw(gfx) 绘制约束网与质点（2D）或三角网格（3D，需在 gfx.render3D() 之后调用）。

3D 版把 2D 接口按维度推广：setGravity(gx,gy,gz)、setBounds(x,y,z,w,h,d)、getParticleX/Y/Z、grabAt(x,y,z,r)、applyForce(fx,fy,fz)。

可交互流体

1. newFluid2D(capacity) 后 setBounds 建容器。
2. emit 喷射粒子；interactAt 做吸引/排斥搅拌。
3. 可调 setSmoothingRadius / setRestDensity / setPressureStiffness / setViscosity。
4. draw(gfx) 按密度着色绘制粒子。

3D 绳索现为可独立裁剪的 physics_rope 子模块，详见 physics_rope.md。

常见问题

• 每帧改变 meter：会破坏 2D 单位一致性，应启动时设置一次；3D 世界不受 setMeter 影响。
• 直接把 Body 坐标当左上角：Box2D / Box3D Body 通常表示形状中心。
• 更新 World 多次或完全不更新：每个逻辑帧一次。
• rayCast / queryAABB 结果会被下次同类查询覆盖；需要时立刻读出。
• 布料/流体粒子过多会占 CPU：演示规模建议布料 ≤ 20×15、流体 ≤ 600。
• 布料默认独立于刚体世界；需要碰撞时调用 setCollideWorld（2D 接 World，3D 接 World3D）。流体仍用 bounds / 采样位置自行耦合。
• 2D 自碰撞是粒子级近似：保证非相邻粒子间距 ≥ 2×particleSize；3D 另有三角面级修正（厚度同为 2×particleSize）。particleSize 调小可让布料更薄。
• 3D 布料网格为双面渲染：正/背面各一份顶点，背面法线翻转、winding 反向，两侧光照都正确。
• 3D 物体尺寸建议贴近真实尺度（约 0.1–10 m）；过大过小会降低求解稳定性。

API 快查

下列方法名来自当前 Squirrel 绑定；同一模块创建的辅助对象（例如 World、Body、World3D、Body3D、Cloth、Cloth3D、Fluid2D）的方法也列在这里。

• applyAngularImpulse()、applyForce()、applyForceAt()、applyLinearImpulse()、clear()、clearBounds()、destroy()、destroyBody()
• draw()、drawDebug()、emit()、getAngle()、getAngularVelocity()、getAngularVelocityX()、getAngularVelocityY()、getAngularVelocityZ()、getBody()、getCapacity()、getCols()
• getAirDensity()、getCollideWorld()、getDamping()、getDensity()、getDragCoefficient()、getFoldStiffness()、getFriction()、getGrabIndex()、getGravityX()、getGravityY()、getGravityZ()、getId()、getIterations()、getLiftCoefficient()
• getLinearVelocityX()、getLinearVelocityY()、getLinearVelocityZ()、getMass()、getMeter()、getName()、getNearPressureStiffness()、getParticleCount()、getParticleMass()、getParticleSize()、getParticleVx()
• getMaxFoldAngle()、getParticleVy()、getParticleVx()、getParticleX()、getParticleY()、getParticleZ()、getPressureStiffness()、getQueryBodyId()、getQueryCount()、getRayHitBodyId()、getRayHitFraction()
• getRayHitNormalX()、getRayHitNormalY()、getRayHitNormalZ()、getRayHitX()、getRayHitY()、getRayHitZ()、getRestDensity()、getRestitution()、getRotW()、getRotX()、getRotY()、getRotZ()、getRows()、getSmoothingRadius()
• getOriginX()、getOriginY()、getOriginZ()、getSelfCollision()、getSpacing()、getStiffness()、getType()、getViscosity()、getWindVelocityX()、getWindVelocityY()、getWindVelocityZ()、getX()、getY()、getZ()、grabAt()、hasRayHit()
• interactAt()、isActive()、isAwake()、isBullet()、isFixedRotation()、isGrabbing()、isPinned()、isSensor()
• moveGrab()、newBody()、newBoxShape()、newCapsuleShape()、newCircleFixture()、newCloth()、newCloth3D()、newClothGPU()、newFluid2D()、newRectangleFixture()、newSphereShape()、newWorld()、newWorld3D()、pin()
• pinTopRow()、queryAABB()、rayCast()、releaseGrab()、reset()、setActive()、setAngle()、setAngularVelocity()、setAwake()
• setAerodynamics()、setBounds()、setBullet()、setCollideWorld()、setColor()、setDamping()、setDensity()、setFixedRotation()、setFoldStiffness()、setFriction()、setGravity()、setWindVelocity()
• setIterations()、setLinearVelocity()、setMeter()、setMaxFoldAngle()、setNearPressureStiffness()、setParticleMass()、setParticlePosition()、setParticleSize()、setPosition()、setPressureStiffness()
• setRestDensity()、setRestitution()、setRotation()、setSensor()、setSmoothingRadius()、setStiffness()、setType()、setViscosity()、testPoint()
• setSelfCollision()、unpin()、update()、updateFull()

+### 3D 高级接口补充索引

以下方法补充了 3D 碰撞查询结果、接触事件、关节状态、距离场采样、材质参数和世界诊断的脚本索引。坐标分量方法按 X/Y/Z 成组使用；索引类 getter 的有效范围由对应的 *Count() 返回值决定。

• areHitEventsEnabled()、didMoverHitWall()、getAngularDamping()、getAngularSeparation()、getAwakeBodyCount()、getAwakeContactCount()、getBeginContactShapeAId()、getBeginContactShapeATag()
• getBeginContactShapeBId()、getBeginContactShapeBTag()、getBeginTriggerSensorBodyId()、getBeginTriggerSensorShapeId()、getBeginTriggerSensorShapeTag()、getBeginTriggerVisitorBodyId()、getBeginTriggerVisitorShapeId()、getBeginTriggerVisitorShapeTag()
• getBodyAId()、getBodyBId()、getBoundsMaxX()、getBoundsMaxY()、getBoundsMaxZ()、getBoundsMinX()、getBoundsMinY()、getBoundsMinZ()
• getBoxDepth()、getBoxHeight()、getClosestBodyId()、getClosestNormalX()、getClosestNormalY()、getClosestNormalZ()、getClosestShapeTag()、getClosestY()
• getClosestZ()、getCollideConnected()、getCollisionX()、getCollisionZ()、getConstraintForceX()、getConstraintForceY()、getConstraintForceZ()、getConstraintTorqueX()
• getConstraintTorqueY()、getConstraintTorqueZ()、getContactDampingRatio()、getContactHertz()、getContactPointCount()、getContactPointNormalZ()、getContactPointShapeTag()、getContactPointY()
• getContactPointZ()、getContactPushOutSpeed()、getContactRecycleDistance()、getDepth()、getDistanceLength()、getDynamicTreeHeight()、getEndContactShapeAId()、getEndContactShapeATag()
• getEndContactShapeBId()、getEndContactShapeBTag()、getEndTriggerSensorBodyId()、getEndTriggerSensorShapeId()、getEndTriggerSensorShapeTag()、getEndTriggerVisitorBodyId()、getEndTriggerVisitorShapeId()、getEndTriggerVisitorShapeTag()
• getExplosionResultCount()、getExplosionResultDeltaAngularVelocityX()、getExplosionResultDeltaAngularVelocityY()、getExplosionResultDeltaAngularVelocityZ()、getExplosionResultDeltaVelocityY()、getExplosionResultDeltaVelocityZ()、getForceThreshold()、getFrictionCombineMode()
• getGravityScale()、getHeightFieldCellSizeZ()、getHeightFieldCountZ()、getHeightFieldGlobalMax()、getHitBodyAId()、getHitBodyBId()、getHitEventThreshold()、getHitNormalY()
• getHitNormalZ()、getHitPointY()、getHitPointZ()、getHitShapeAId()、getHitShapeATag()、getHitShapeBId()、getHitShapeBTag()、getInertiaXY()
• getInertiaXZ()、getInertiaYY()、getInertiaYZ()、getInertiaZZ()、getIslandCount()、getJointCount()、getJointStressBodyAId()、getJointStressBodyBId()
• getJointStressKind()、getJointStressTorqueY()、getJointStressTorqueZ()、getLinearDamping()、getLinearSeparation()、getLocalCenterY()、getLocalCenterZ()、getLocalRotW()
• getLocalRotX()、getLocalRotY()、getLocalRotZ()、getLocalX()、getLocalY()、getLocalZ()、getMaterialId()、getMaximumLinearSpeed()
• getMoverGroundSnap()、getMoverNormalY()、getMoverNormalZ()、getMoverSkinWidth()、getMoverStepHeight()、getNormalY()、getNormalZ()、getOutsideDistance()
• getPenetrationDepth()、getQueryCategoryBits()、getQueryIgnoredBodyId()、getQueryIgnoredShapeId()、getQueryMaskBits()、getRayHitShapeTag()、getRayResultNormalY()、getRayResultNormalZ()
• getRayResultY()、getRayResultZ()、getRecycledContactCount()、getRestitutionCombineMode()、getRestitutionThreshold()、getRevoluteAngle()、getRevoluteMotorTorque()、getRollingResistance()
• getShapeCastBodyId()、getShapeCastNormalY()、getShapeCastNormalZ()、getShapeCastResultNormalY()、getShapeCastResultNormalZ()、getShapeCastResultY()、getShapeCastResultZ()、getShapeCastY()
• getShapeCastZ()、getShapeContactX()、getShapeContactZ()、getShapeCount()、getSleepThreshold()、getSphericalConeAngle()、getSphericalTwistAngle()、getStaticTreeHeight()
• getSurfaceX()、getSurfaceZ()、getTangentVelocityX()、getTangentVelocityY()、getTangentVelocityZ()、getTorqueThreshold()、getTriangleMeshMaterialCount()、getTriangleMeshMaterialFriction()
• getTriangleMeshMaterialId()、getTriangleMeshMaterialIndex()、getTriangleMeshMaterialRestitution()、getTriangleMeshMaterialRollingResistance()、getWorldCenterZ()、hasClosestPoint()、hasShapeCastHit()、isAngularXLocked()
• isAngularYLocked()、isAngularZLocked()、isContinuousCollisionEnabled()、isLinearXLocked()、isLinearYLocked()、isLinearZLocked()、isSleepEnabled()、isWarmStartingEnabled()
• sample()、sampleNormal()、setDistanceLength()、setSleepThreshold()

使用要点

• 模块对象和它创建的资源对象应保存在全局或实体状态中，不要在每帧重复创建。
• 带 update(dt) 的系统应在 eve_update 调用；绘制方法应在 eve_render 调用。
• 参数约束、默认值和返回类型以对应模块头文件及 addFunc 绑定为准；本文 API 快查与当前源码同步生成。

源码： src/modules/physics/ 相关测试： test/box2d.cpp、test/box3d.cpp、test/softbody.cpp