Blitz3D+ Command Reference

ResetPhysicsBody body,x#,y#,z#,pitch#,yaw#,roll#[,clear_velocity]

Parameters

body - live physics body handle

x# - world position component in metres
y# - world position component in metres
z# - world position component in metres

pitch# - world rotation component in radians

yaw# - world rotation component in radians

roll# - world rotation component in radians

clear_velocity (optional) - True clears velocities (default); False preserves them

Description

Teleports a body and its entity to a new position and rotation.

Teleports the body and its entity to a world-space position in metres and a world rotation in physics radians, using the same Euler order as RotateEntity. The default clear_velocity=True clears linear/angular velocity, including paused motion. False preserves it. Joints, attachment frames and spring targets retain their identities/settings. Wakes enabled bodies and resets entity interpolation/collision history. Resets work while disabled and on kinematic bodies.

For a borrowed managed body, the requested pose and pending scene changes are prepared together. Invalid parent transforms, invalid collider bounds or failed preparation leave the committed pose, motion and collision history unchanged. Pending geometry changes can replace shape handles while retaining the body handle. A clearing reset also discards queued force, torque and wind; a preserving reset retains them, including while hidden. A Collisions-controlled mover requires clear_velocity=True.

For a standalone body, existing shape handles are retained and already accumulated forces are not cleared. Apply any new forces after resetting.

Stale/wrong-kind handles and invalid numeric inputs cause runtime errors. Object ownership is unchanged by these controls.

Requires Extended mode.

See also: PhysicsBodyActive, PhysicsBodyMode, StepPhysics.

Example

; ResetPhysicsBody Example
; ------------------------
; Requires Extended mode.

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

Const PHYSICS_STATIC=0
Const PHYSICS_DYNAMIC=2

camera=CreateCamera()
PositionEntity camera,0,3,-7
RotateEntity camera,20,0,0

light=CreateLight()
RotateEntity light,45,-30,0
AmbientLight 60,60,60

; An independent Box3D world with standard gravity
world=CreatePhysicsWorld()

; Blue static floor
ground=CreateCube()
ScaleEntity ground,6,0.5,6
PositionEntity ground,0,-0.5,0
EntityColor ground,80,160,255
ground_body=CreatePhysicsBody(world,ground,PHYSICS_STATIC)
ground_shape=PhysicsBodyBox(ground_body,12,1,12)

; An orange plank to push around
plank=CreateCube()
ScaleEntity plank,1.5,0.25,0.5
EntityColor plank,255,120,70
plank_body=CreatePhysicsBody(world,plank,PHYSICS_DYNAMIC)
plank_shape=PhysicsBodyBox(plank_body,3,0.5,1)
ResetPhysicsBody plank_body,0,1,0,0,0,0

While Not KeyDown(1)

    ; R puts the plank back in the middle
    If KeyHit(19) Then ResetPhysicsBody plank_body,0,1,0,0,0,0

    ; Space teleports the plank above the floor at a random angle
    If KeyHit(57) Then ResetPhysicsBody plank_body,Rnd(-3,3),3,Rnd(-3,3),Rnd(-Pi,Pi),Rnd(-Pi,Pi),0
    StepPhysics world,1.0/60.0,4

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    Text 0,0,"Arrow keys: move camera   R: reset   Space: teleport   Esc: exit"
    Text 0,20,"ResetPhysicsBody moves the body and its entity, and clears velocity"
    Text 0,40,"Angles are in radians: pitch, yaw, roll"

    Flip

Wend

FreePhysicsWorld world
End

Index