Blitz3D+ Command Reference

PhysicsBallJointTarget joint,pitch#,yaw#,roll#

Parameters

joint - live ball-joint handle from CreatePhysicsBallJoint

pitch# - relative target pitch in physics radians

yaw# - relative target yaw in physics radians

roll# - relative target roll in physics radians

Description

Sets the orientation a ball joint's spring and motor aim for.

Sets the desired orientation of joint frame B relative to frame A using pitch, yaw and roll in physics radians and Blitz's Euler rotation order. It does not change the frames or teleport either body. Enabling the ball spring makes the bodies follow this target; an enabled motor or limits may prevent them from reaching it. Use PhysicsJointFrame to author the body-local reference axes and anchors. This is not a scalar hinge spring target.

Use CreatePhysicsBallJoint for creation and PhysicsJointFrame for body-local attachment frames (positions in unscaled metres, Euler angles in radians). Creation preserves body-local identity axes; differently rotated bodies do not automatically have zero relative frame rotation. The cone axis is frame A's Z axis and twist uses the relative frame decomposition. Exact antiparallel Z axes are a singular swing/twist configuration; author valid reference frames and keep constrained motion within the chosen cone. Entity rotation commands still use degrees.

The joint must belong to the matching joint family. All setters validate every argument before mutation and wake connected bodies. Getters do not wake bodies or change physics state. Settings and native wake operations are recorded for deterministic physics replay. Body/entity/world deletion invalidates owned joint handles. Invalid, stale and wrong-kind handles or unsupported joint types raise runtime errors.

Use PhysicsJointForceX/Y/Z and PhysicsJointTorqueX/Y/Z for combined reaction feedback and PhysicsJointThresholds for overload events. Native overloads are sampled during bias solves; final relaxed force/torque getters need not match the event threshold on that step. Events do not automatically break joints.

Requires Extended mode.

See also: CreatePhysicsBallJoint, PhysicsBallJointConeLimit, PhysicsBallJointTwistLimits, PhysicsBallJointSpring, PhysicsBallJointMotor, PhysicsJointFrame.

Example

; PhysicsBallJointTarget Example
; ------------------------------
; Requires Extended mode.

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

Const PHYSICS_STATIC=0
Const PHYSICS_DYNAMIC=2

camera=CreateCamera()
PositionEntity camera,3,3,-7
RotateEntity camera,5,25,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)

; A static shoulder block, and an arm hanging from it on a ball joint
shoulder=CreateCube()
ScaleEntity shoulder,0.3,0.3,0.3
PositionEntity shoulder,0,4,0
EntityColor shoulder,150,150,160
shoulder_body=CreatePhysicsBody(world,shoulder,PHYSICS_STATIC)
shoulder_shape=PhysicsBodyBox(shoulder_body,0.6,0.6,0.6)
arm=CreateCube()
ScaleEntity arm,0.15,1,0.3
PositionEntity arm,0,3,0
EntityColor arm,255,120,70
arm_body=CreatePhysicsBody(world,arm,PHYSICS_DYNAMIC)
arm_shape=PhysicsBodyBox(arm_body,0.3,2,0.6,10)
joint=CreatePhysicsBallJoint(shoulder_body,arm_body,0,4,0)

; Point both joint frames' Z axes down the arm, so swing is measured
; from hanging straight down and twist is turning about the arm
PhysicsJointFrame joint,1,0,0,0,Pi/2,0,0
PhysicsJointFrame joint,2,0,1,0,Pi/2,0,0

target#=0

; A spring pulls the arm back towards the target orientation
PhysicsBallJointSpring joint,True,1,0.2

While Not KeyDown(1)

    ; Space swings the arm sideways, T twists it about its length
    If KeyHit(57) Then PhysicsBodyImpulseAt arm_body,8,0,4,EntityX(arm),EntityY(arm)-1,EntityZ(arm)
    If KeyHit(20) Then PhysicsBodyAngularImpulse arm_body,0,3,0

    ; [ and ] raise or lower the target pitch the spring pulls towards
    If KeyHit(26) Then target=target-0.25
    If KeyHit(27) Then target=target+0.25
    PhysicsBallJointTarget joint,target,0,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   Space: swing   [ / ]: target pitch   Esc: exit"
    Text 0,20,"PhysicsBallJointTarget joint,"+target+",0,0"
    Text 0,40,"The spring lifts the arm towards the target"

    Flip

Wend

FreePhysicsWorld world
End

Index