b3dSetCharacterPosition

Teleports Jolt physics character controller to new position (zeros velocity). Takes characterHandle (character controller handle), x (world X position), y (world Y position), z (world Z position). Returns nothing. Sets physics character position and updates visual entity, clearing all velocities.

This function teleports character. Character controller: Jolt physics character (kinematic capsule for player movement), separate from rigid bodies (specialized for character control), managed by physics system (requires g_physicsSystem initialized), created via b3dCreateCharacter. Teleportation: instantly moves character to new position (no interpolation), does not check for collisions at destination (can teleport into walls), useful for respawns, level transitions, cutscene positioning, checkpoints. Position parameters: x/y/z in world coordinates, y parameter is feet position (ground level), physics system adds capsuleCenterOffset internally (adjusts for capsule center), Jolt uses +Y up (same as BambooBasic). Velocity clearing: zeros all velocity components after teleport, velocity = Vec3::sZero() (main velocity), inputVelocity = Vec3::sZero() (player input velocity), impulseVelocity = Vec3::sZero() (external forces like knockback), pendingImpulse = Vec3::sZero() (queued impulses). Why clear velocity: prevents momentum carryover after teleport, avoids character flying off after respawn, ensures clean state at new position, player expects stationary after teleport. Visual entity sync: updates visual entity position via b3dPositionEntity, entity.entityHandle stores visual mesh entity, visual matches physics position (feet level), maintains visual/physics synchronization. Use cases: (1) Player respawn (death -> checkpoint teleport), (2) Level transitions (door -> new area), (3) Cutscene positioning (move character for cinematic), (4) Checkpoint system (save position, restore on death), (5) Elevator/platform (snap to moving platform). Common patterns: respawn at checkpoint = b3dSetCharacterPosition(player, checkpointX, checkpointY, checkpointZ), level door = b3dSetCharacterPosition(player, doorExitX, doorExitY, doorExitZ), elevator = b3dSetCharacterPosition(player, elevatorX, newFloorY, elevatorZ), fall reset = if characterY < -100 then b3dSetCharacterPosition(player, spawnX, spawnY, spawnZ). Typical usage: call when player triggers checkpoint/door/teleporter, use after loading saved game state, combine with fade-out/fade-in for smooth transition, avoid calling every frame (only for discrete teleports). Character handle: handle returned by b3dCreateCharacter, stored in g_characters map (characterHandle -> CharacterData), function looks up CharacterData by handle, returns silently if handle not found. Error handling: returns early if g_physicsSystem null (physics not initialized), returns early if characterHandle not in g_characters map, no error messages (silent fail), validates handle before accessing character data. Physics system: requires Jolt physics initialized (b3dInitPhysics called), character must be created via b3dCreateCharacter, physics updated each frame (b3dUpdatePhysics), teleport takes effect immediately (no delay). Capsule offset: characterData stores capsuleCenterOffset, physics character positioned at feet + offset (capsule center), y parameter is feet position (user-facing coordinate), internal physics uses feet + offset for capsule center, maintains consistent behavior with other entity functions. Jolt character API: calls character->SetPosition(RVec3(x, physY, z)), physY = y + capsuleCenterOffset (adjust for capsule center), RVec3 is Jolt's high-precision position vector (Real = double or float), SetPosition is instantaneous teleport (not velocity-based movement). Character vs rigid body: character controllers are kinematic (manually controlled), rigid bodies are dynamic (physics simulated), characters don't react to forces the same way, teleportation safe for characters (not for rigid bodies without care). Collision at destination: teleport doesn't check for obstacles, can teleport into walls/geometry, character may be stuck if bad position, use with valid spawn points (tested positions), depenetration occurs over subsequent frames (physics resolves overlap). Feet position: y parameter represents character's feet (ground contact), consistent with b3dPositionEntity for visual entity, capsule extends upward from feet (height = capsule height), simplifies level design (place at ground level). Velocity components: velocity = accumulated movement velocity (walking, falling), inputVelocity = player input (WASD keys), impulseVelocity = external forces (knockback, wind), pendingImpulse = queued single-frame forces, all zeroed to prevent unexpected movement. Related character functions: b3dCreateCharacter creates character controller (returns characterHandle), b3dMoveCharacter sets horizontal velocity (walking input), b3dCharacterJump applies vertical impulse (jumping), b3dGetCharacterState queries ground contact (grounded/jumping/falling), b3dCharacterGroundY gets ground height below character. Example workflow: (1) player dies -> (2) b3dSetCharacterPosition(player, checkpointX, checkpointY, checkpointZ) -> (3) velocity zeroed, character stationary -> (4) player regains control at checkpoint. Performance: O(1) operation (hash map lookup + position set), minimal cost (safe to call when needed), physics teleport is instant (no iterative solving), visual entity update is cheap (single b3dPositionEntity call). Position precision: uses double precision floats (Real type in Jolt), sufficient for large worlds (no floating point precision loss), consistent with BambooBasic's double precision coordinates. Related: b3dCreateCharacter creates character controller (required before teleport), b3dMoveCharacter sets walking velocity (normal movement, not teleport), b3dCharacterJump adds vertical impulse (jumping, not teleport), b3dPositionEntity sets visual entity position (character sync happens internally).