b3dSetPhysicsBodyPosition

Teleports physics body to new position (activates dynamic bodies to recalculate collisions). Takes bodyHandle (physics body from b3dCreatePhysicsBody), x/y/z (new position in world coordinates). Returns nothing. Sets Jolt body position instantly (no interpolation), activates dynamic bodies to recalculate collisions after teleport. Use for respawning, cutscene placement, or manual positioning.

This function teleports physics body. Position update: sets body center of mass position to (x,y,z) instantly (no physics simulation between old and new position), does not affect velocity (body retains momentum after teleport), does not trigger collision callbacks during teleport (body simply appears at new position). Dynamic body activation: if body has mass>0 (dynamic body) activates body with EActivation::Activate (forces Jolt to recalculate collisions, wake sleeping body, update broad-phase collision structure), prevents stale collision state after teleport (ensures collisions detected at new position). Static body behavior: if body has mass=0 (static body) uses EActivation::DontActivate (static bodies don't need activation, assumes static geometry rarely moves). Use cases: (1) Respawn system (teleport player to checkpoint after death), (2) Portals (teleport object to portal exit position), (3) Cutscenes (position physics objects for scripted events), (4) Level reset (return objects to starting positions), (5) Editor placement (manually position objects in scene). Common patterns: respawn player b3dSetPhysicsBodyPosition(playerBody, checkpointX, checkpointY, checkpointZ), portal exit b3dSetPhysicsBodyPosition(objBody, portalX, portalY, portalZ), reset object b3dSetPhysicsBodyPosition(crateBody, startX, startY, startZ). Typical usage: call after player death to respawn, combine with b3dSetPhysicsBodyVelocity(body, 0, 0, 0) to reset momentum, use with b3dSetPhysicsBodyRotation to set both position and orientation. Coordinate system: x/y/z in BambooBasic Y-up world coordinates (same as entity positions, no conversion needed), passed directly to Jolt RVec3 (Jolt also uses Y-up). Velocity preservation: body velocity unchanged after teleport (momentum retained, may cause unexpected movement), reset velocity separately if desired (b3dSetPhysicsBodyVelocity(body, 0, 0, 0) for stationary teleport). Collision detection: activation ensures body detects collisions at new position (broad-phase updated, narrow-phase triggered on next frame), prevents body floating through geometry at teleport destination, may trigger collision callbacks if teleported inside other object. Entity sync: entity visual position not automatically updated (call b3dPositionEntity to sync visual and physics), physics system syncs entity TO physics each frame (not physics to entity for teleport), manually sync if visual should match teleport. Performance: O(1) operation (simple position set), activation triggers broad-phase update (cheap), avoid teleporting many bodies per frame (activation overhead accumulates). Alternatives: for smooth movement use b3dSetPhysicsBodyVelocity instead (physics simulates motion), for kinematic control use position + velocity = 0 each frame (prevents drift). Validation: silently returns if g_physicsSystem not initialized, silently returns if bodyHandle not found in g_bodyHandleToBodyID, reads g_bodyCreationData to determine if dynamic (checks mass>0). Activation importance: without activation teleported body may have stale collision state (collisions not detected until natural wake event), activation forces immediate collision update (prevents tunneling or floating after teleport). Sleeping bodies: dynamic bodies sleep when stationary to save CPU (auto-sleep after stable), activation wakes body (re-enables collision and physics update), prevents teleported body remaining asleep at old position. Related: b3dSetPhysicsBodyRotation sets orientation (combine with position for full transform), b3dSetPhysicsBodyVelocity sets velocity (reset to 0,0,0 for stationary teleport), b3dCreatePhysicsBody creates physics body (call this after creation), b3dPositionEntity positions visual entity (sync with physics position).