Box3D 实战指南:用户数据、坐标系与调试绘制全解析(Loose Ends)
Box3D 实战指南:用户数据、坐标系与调试绘制全解析(Loose Ends)
Box3D 是一个面向游戏开发的 3D 刚体物理引擎,本文基于官方文档 docs/loose_ends.md,系统讲解三块"散落在主手册之外"的关键实践:如何在物理对象上挂接游戏实体指针(User Data)、Box3D 采用的坐标系与单位约定,以及如何通过 b3DebugDraw 完整绘制物理世界。读完本文,你将能够把 Box3D 的 body / shape / joint 无缝接回自己的游戏对象体系,写出正确的坐标与单位换算代码,并搭建一套可过滤、可复用的调试渲染管线,同时掌握该引擎在 v0.1 阶段已知的 9 条工程限制。
一、User Data:物理实体与游戏对象的双向映射
Box3D 的世界(world)、刚体(body)、形状(shape)和关节(joint)都允许挂载一个 void* 形式的用户数据指针。当你在接触事件、查询或回调中拿到一个 b3BodyId / b3ShapeId / b3JointId 时,通过 user data 可以立刻回溯到对应的游戏对象,而无需自己维护一套 id 哈希表。
1.1 典型用法:在 body 上存游戏实体指针
最常见的模式是在创建刚体时,把游戏实体指针直接写入 b3BodyDef.userData,同时把刚体 id 存回游戏实体,形成"实体 → 刚体 → 实体"的循环引用:
GameEntity* entity = GameCreateEntity();
b3BodyDef bodyDef = b3DefaultBodyDef();
bodyDef.userData = entity;
entity->bodyId = b3CreateBody(myWorldId, &bodyDef);
b3BodyDef 结构体在 include/box3d/types.h 中定义,其中 userData 字段的官方注释为 "Use this to store application specific body data",位于 name 字段之后。这之后,从任何物理事件中拿到的 body id 都能直接转换为游戏实体:
- 从接触事件(contact event)中拿到刚体 id,对对应实体施加伤害;
- 当刚体进入某个区域(sensor 或查询)时,触发一段脚本事件;
- 当关节被销毁时,清理与之绑定的游戏状态。
1.2 四类对象一致的 Set / Get 接口
Box3D 为世界、刚体、形状、关节提供了完全对称的 setter / getter,全部声明于 include/box3d/box3d.h:
// Body
b3Body_SetUserData(bodyId, ptr);
void* ptr = b3Body_GetUserData(bodyId);
// Shape
b3Shape_SetUserData(shapeId, ptr);
void* ptr = b3Shape_GetUserData(shapeId);
// Joint
b3Joint_SetUserData(jointId, ptr);
void* ptr = b3Joint_GetUserData(jointId);
// World
b3World_SetUserData(worldId, ptr);
void* ptr = b3World_GetUserData(worldId);
从源码实现看,这些接口都是"按 id 取对象、直接读写字段"的轻量操作:b3Body_SetUserData 在 src/body.c 中通过 b3GetBodyFullId 取出 b3Body 后执行 body->userData = userData;b3Shape_SetUserData 在 src/shape.c、b3Joint_SetUserData 在 src/joint.c 中逻辑完全一致。这意味着 setter/getter 几乎没有性能开销,可以在游戏逻辑中频繁调用。
1.3 类型一致性是硬性要求
保持类型一致。如果某个 body 存的是 GameEntity*,那么所有 body 都应存 GameEntity*(或显式约定使用判别字段)。混合存放不同指针类型、不做判别就强制转换,会导致难以排查的崩溃。建议为每种物理对象定义统一的数据结构,例如:
typedef struct GameBodyData {
uint32_t type; // 判别字段,例如 kPlayer / kProp / kDebris
GameEntity* entity; // 真正的游戏对象
} GameBodyData;
二、坐标系、单位与自由度约定
2.1 右手坐标系,Y 轴向上
Box3D 采用右手坐标系,默认 Y 轴向上,因此默认重力向量指向 Y 轴负方向:
b3Vec3 gravity = { 0.0f, -9.8f, 0.0f };
值得注意的是,引擎内部没有硬编码重力方向——重力只是设置在 world 上的一个 b3Vec3,你完全可以根据应用需求调整它(例如横版游戏把重力改为 X 方向,或设置零重力太空场景)。
2.2 MKS 单位制与尺度范围
Box3D 使用 MKS 单位:米(meters)、千克(kilograms)、秒(seconds)、弧度(radians)。求解器针对 约 0.1 到 10 米 的物体范围做了调优:
- 超出该范围的极小或极大物体,数值稳定性会下降(详见下文"限制"章节);
- 如果你的美术资产使用不同的单位尺度(例如以厘米或英尺为单位),应在资源管线与 Box3D 的边界处应用唯一的换算系数,而不是把换算散落在仿真代码各处。
2.3 刚体的 6 个自由度
Box3D 刚体拥有 6 个自由度(3 个平移 + 3 个旋转),对应数据结构如下:
| 物理量 | 类型 | 说明 |
|---|---|---|
| 位置 position | b3Vec3 |
刚体原点世界坐标 |
| 姿态 orientation | b3Quat |
四元数,避免欧拉角万向锁 |
| 角速度 angularVelocity | b3Vec3 |
弧度/秒 |
| 力矩 torque | b3Vec3 |
施加的力矩向量 |
| 转动惯量张量 | b3Matrix3 |
3×3 惯性张量矩阵 |
需要限制某个轴的运动时,可以使用 b3BodyDef 中的 b3MotionLocks motionLocks 字段(见 include/box3d/types.h),例如把角色限制为只能绕 Y 轴旋转。
三、调试绘制(Debug Drawing)
调试绘制是理解物理世界内部状态(碰撞形状、关节约束、接触力、island 划分等)的最直接手段。Box3D 提供了统一的 b3DebugDraw 回调结构,让你把物理世界渲染到任意图形后端。
3.1 b3DebugDraw 结构体与回调槽位
b3DebugDraw 结构体定义在 include/box3d/types.h,每个回调都接收 b3HexColor 颜色和 context 用户上下文(在大型世界模式下,回调收到的是双精度平移后的世界坐标,你需要在自己的回调里平移到相机坐标系)。
| 回调字段 | 签名要点 | 绘制内容 |
|---|---|---|
DrawShapeFcn |
(void* userShape, b3WorldTransform, b3HexColor, void* context) |
绘制一个形状;userShape 来自 createDebugShape 回调返回的不透明句柄 |
DrawSegmentFcn |
(b3Pos p1, b3Pos p2, b3HexColor, void*) |
线段 |
DrawTransformFcn |
(b3WorldTransform, void*) |
坐标系(长度比例自定) |
DrawPointFcn |
(b3Pos, float size, b3HexColor, void*) |
点 |
DrawSphereFcn |
(b3Pos, float radius, b3HexColor, float alpha, void*) |
球体 |
DrawCapsuleFcn |
(b3Pos p1, b3Pos p2, float radius, b3HexColor, float alpha, void*) |
胶囊体 |
DrawBoundsFcn |
(b3AABB, b3HexColor, void*) |
AABB 线框盒 |
DrawBoxFcn |
(b3Vec3 extents, b3WorldTransform, b3HexColor, void*) |
有朝向的盒体 |
DrawStringFcn |
(b3Pos, const char* s, b3HexColor, void*) |
世界空间文字标签 |
3.2 类别开关(Category Flags)
结构体上的布尔标志控制"画什么":
| Flag | 显示内容 |
|---|---|
drawShapes |
形状几何体 |
drawJoints |
关节坐标系与约束 |
drawJointExtras |
关节附加信息(限位、马达) |
drawBounds |
形状 AABB |
drawMass |
动态刚体的质心标记与质量数值 |
drawSleep |
动态/运动学刚体的睡眠信息 |
drawBodyNames |
刚体名称字符串 |
drawContacts |
接触点与锚点 |
drawContactNormals |
接触法线方向 |
drawContactForces |
法向冲量大小 |
drawAnchorA |
接触锚点 A |
drawGraphColors |
约束图着色(contact/joint 的并行分组颜色) |
drawContactFeatures |
原始接触特征索引 |
drawIslands |
岛屿包围盒 |
3.3 调用方式:b3World_Draw 与 maskBits
在每次步进世界之后调用绘制函数:
b3DebugDraw draw = b3DefaultDebugDraw();
draw.DrawShapeFcn = MyDrawShape;
draw.DrawSegmentFcn = MyDrawSegment;
// ... 填充其余回调 ...
draw.drawShapes = true;
draw.drawingBounds = myViewAABB;
b3World_Draw(worldId, &draw, UINT64_MAX);
关键点解析:
b3DefaultDebugDraw()(实现于 src/types.c)会预先填充所有回调为空实现,避免你遗漏某个回调时触发空指针异常;同时把drawingBounds默认设置为以原点为中心、边长 200 米(按长度单位换算100.0f * b3GetLengthUnitsPerMeter())的 AABB,并把jointScale、forceScale初始化为 1.0。maskBits与碰撞过滤联动:b3World_Draw内部(src/physics_world.c)会对世界宽相树中的每个形状测试(maskBits & shape->categoryBits) != 0,只有命中的形状才会被访问。传入UINT64_MAX绘制全部内容;传入你自己类别位的子集,则可以按图层裁剪绘制(例如俯视视角下跳过 debris 碎片层)。- 视锥裁剪:绘制前必须设置有效的
drawingBounds(b3World_Draw中有B3_ASSERT( b3IsValidAABB( draw->drawingBounds ) )),绘制会以该 AABB 对宽相树发起查询(b3DynamicTree_Query),只绘制视野内的形状。
3.4 两回调模型:createDebugShape / destroyDebugShape
形状绘制路径采用 b3WorldDef 上设置的两个回调,避免每帧重复上传 GPU 几何:
createDebugShape(include/box3d/types.h):形状第一次被绘制时调用一次,返回值是不透明句柄,用于上传 GPU 几何体;destroyDebugShape:形状被修改或销毁时调用,用于释放对应 GPU 资源。
在 b3WorldDef 中设置(include/box3d/types.h):
b3WorldDef worldDef = b3DefaultWorldDef();
worldDef.createDebugShape = MyCreateDebugShape; // 首次绘制时上传几何
worldDef.destroyDebugShape = MyDestroyDebugShape; // 修改/销毁时释放资源
worldDef.userDebugShapeContext = myContext; // 传给回调的用户上下文
从实现看(src/physics_world.c),b3World_Draw 在遍历形状时,若 shape->userShape == NULL 且设置了 createDebugShape,就会调用它生成几何句柄存入 shape;后续帧 DrawShapeFcn 直接拿到该句柄,实现多遍渲染(multi-pass rendering)而无需重复上传。之后 DrawShapeFcn 收到的 userShape 正是 createDebugShape 的返回值,配合 drawingBounds 的剔除测试,可做到高效的分层渲染。
samples 应用(尤其是 samples/gfx/debug_adapter.h 中的 MakeDebugDraw / GetGuiDraw / ApplyGuiFlags)提供了完整的 b3DebugDraw 参考实现,你可以直接对照它学习如何把上述回调接到实际的渲染器上。
四、已知限制:v0.1 引擎的工程取舍
Box3D 使用多种近似手段换取实时物理性能,作为 v0.1 引擎仍在成熟过程中,官方文档明确提示"比 Box2D 更粗糙"(rougher edges than Box2D)。当前已知限制如下:
- 极端质量比:连接刚体之间质量比极端时,会导致关节拉伸和接触重叠。
- 软约束(Soft constraints):提升了鲁棒性,但允许关节和接触出现少量柔性形变。
- 连续碰撞(CCD)覆盖范围:处理快速动态刚体对静态几何(以及子弹对动态刚体)的碰撞,但不支持通用的动态 vs 动态连续碰撞。
- CCD 不跨关节传播:快速运动的铰链链(articulated chains)可能瞬时拉伸。
- 半隐式欧拉积分:一阶精度,抛体轨迹是近似的。提高
b3World_Step的subStepCount可提升精度,代价是等比例的性能开销。 - 迭代 Gauss-Seidel 求解器:为实时性能而设计,碰撞并非完美刚性,接触并非逐像素精确;增加子步数可收紧结果。
- 网格与高度场形状仅限静态:不参与动态 vs 动态接触。
- 复合形状(compound)仅限静态刚体:且创建后不可变。
- 角色移动器(character mover)API 为实验性:接口可能在未来版本发生变化。
理解这些限制,有助于你在游戏设计中规避典型陷阱:例如避免把大量质量悬殊的物体铰接在一起、对高速子弹使用专门的连续碰撞配置、以及把美术单位在进入 Box3D 前统一换算为 MKS。
延伸阅读
- docs/hello.md:Box3D 最小可用程序示例;
- docs/overview.md:引擎整体架构概览;
- include/box3d/types.h:
b3DebugDraw、b3WorldDef、b3BodyDef等核心结构体的完整字段定义; - samples/gfx/debug_adapter.h:可直接参考的调试绘制实现;
- src/physics_world.c:
b3World_Draw的真实实现,展示了宽相树查询与 maskBits 过滤逻辑。