b3dCreatePhysicsBody

Creates physics body for entity (shape: 0=box 1=sphere 2=mesh, mass 0=static >0=dynamic). Takes entityHandle (entity to attach physics to), shape (0=box 1=sphere 2=mesh), mass (0.0=static non-moving, >0=dynamic affected by gravity/forces), width/height/depth (dimensions in world units, ignored for mesh shape). Returns bodyHandle (physics body handle for subsequent operations, 0 on failure). Creates Jolt physics body, attaches to entity, enables collision detection and physical simulation. Powered by Jolt Physics engine.

This function creates rigid body physics. Shape types: 0 (Box: axis-aligned box collision, uses width/height/depth dimensions, good for crates, walls, platforms), 1 (Sphere: spherical collision, uses width as diameter, height/depth ignored, good for balls, projectiles), 2 (Mesh: per-triangle collision using actual mesh geometry, width/height/depth ignored, expensive but precise, good for terrain, complex static geometry). Mass behavior: mass=0.0 creates static body (immovable, infinite mass, not affected by forces/gravity, collision layer NON_MOVING, good for walls, floors, terrain), mass>0 creates dynamic body (movable, affected by forces/gravity, collision layer MOVING, continuous collision detection enabled prevents tunneling, good for players, crates, physics objects). Dimension handling: width/height/depth specify collision volume size in world units (not affected by entity scale initially), if all three are 0.0 auto-calculates from mesh bounding box (only works for ENTITY_MESH, iterates vertices to find min/max XYZ, prints calculated dimensions), entity scale applied to physics dimensions (scaledWidth = width * scaleX ensures physics matches visual size). Use cases: (1) Static collision (mass=0 box/mesh for walls, floors, buildings), (2) Dynamic objects (mass>0 box/sphere for crates, balls, barrels), (3) Character controller (mass>0 box/sphere for player collision), (4) Terrain collision (mass=0 mesh for landscape, complex geometry), (5) Projectiles (mass>0 sphere for bullets, grenades). Common patterns: static floor body = b3dCreatePhysicsBody(floor, 0, 0.0, 100, 1, 100), dynamic crate body = b3dCreatePhysicsBody(crate, 0, 50.0, 2, 2, 2), player capsule body = b3dCreatePhysicsBody(player, 1, 75.0, 1, 2, 1), terrain mesh body = b3dCreatePhysicsBody(terrain, 2, 0.0, 0, 0, 0), auto dimensions body = b3dCreatePhysicsBody(mesh, 0, 10.0, 0, 0, 0). Typical usage: create after loading entity to enable collision, use bodyHandle with b3dSetPhysicsBody* functions to configure properties, combine with b3dGetPhysicsBody* to read simulation results. Body creation: reads entity position (b3dEntityX/Y/Z) as initial physics position, reads entity rotation (b3dEntityPitch/Yaw/Roll converted to quaternion) as initial orientation, applies entity scale to dimensions (physics body matches visual mesh size), creates Jolt BodyCreationSettings with shape/position/rotation/motionType/layer. Dynamic body setup: sets EMotionType::Dynamic (affected by forces), sets EMotionQuality::LinearCast (continuous collision detection prevents fast objects tunneling), sets mOverrideMassProperties = CalculateInertia (inertia tensor calculated from shape/mass), activates body immediately (EActivation::Activate starts simulation). Static body setup: sets EMotionType::Static (immovable infinite mass), sets layer NON_MOVING (collision filter separates static/dynamic), does not activate (static bodies don't need activation). Shape creation details: Box (BoxShape with half-extents width/2 height/2 depth/2, scaled dimensions applied), Sphere (SphereShape with radius = width/2, height/depth ignored, scaled width applied), Mesh (MeshShapeSettings from triangle list built from mesh vertices/indices, each vertex scaled by entity scale, prints triangle count, validates vertices/indices exist, uses actual mesh geometry for precise collision). Mesh shape validation: checks entity type is ENTITY_MESH (returns 0 if not), checks mesh pointer not null (returns 0 if null), checks vertices/indices not empty (returns 0 if empty), converts mesh triangles to Jolt Float3 format (applies entity scale per vertex). Body handle system: g_nextBodyHandle increments for each body (unique handle), g_bodyHandleToBodyID maps handle to Jolt BodyID (lookup for all operations), g_entityToBody maps entityHandle to BodyID (one body per entity), g_bodyToEntity reverse mapping (used in collision callbacks), entity.physicsBodyHandle stores handle (seamless integration). Creation data storage: g_bodyCreationData stores PhysicsBodyData (entityHandle, shapeType, mass, width/height/depth, materialType=0 default), used for rescaling physics body when entity scaled (RescalePhysicsBody recreates body with new dimensions). Position/rotation coordinate system: Jolt uses Y-up coordinates (same as BambooBasic user space), rotation converted from degrees to radians (Euler angles to quaternion), position passed directly (no conversion needed). Validation: returns 0 if g_physicsSystem not initialized (b3dInitPhysics not called), returns 0 if entityHandle not found in g_entities, returns 0 if auto-dimension fails (dimensions=0 but entity not mesh), prints error messages for all failures (helps debugging). Performance: O(1) for box/sphere creation (instant), O(N) for mesh shape where N=triangle count (expensive, use for static geometry only, avoid for dynamic objects), continuous collision for dynamics adds ~10-20% overhead (prevents tunneling). Physics integration: body added to Jolt simulation (bodyInterface.AddBody with Activate), automatically updated by UpdatePhysicsSystem each frame (called in b3dRenderWorld), entity position/rotation synced from physics body after simulation (SyncEntityTransformFromPhysics). Limitations: one physics body per entity (creating second body replaces first in g_entityToBody), mesh shape expensive for large triangle counts (consider simplified collision proxy), static bodies cannot move (use mass>0 then set velocity=0 for movable with kinematic control). Related: b3dSetPhysicsBodyRestitution sets bounciness (0=no bounce 1=perfect bounce), b3dSetPhysicsBodyFriction sets surface friction (0=ice 1=rubber), b3dSetPhysicsBodyPosition teleports body to new position, b3dSetPhysicsBodyRotation sets orientation, b3dSetPhysicsBodyVelocity sets linear velocity (movement speed), b3dSetPhysicsBodyAngularVelocity sets rotational velocity (spin rate).