Blitz3D+ Command Reference

PhysicsBallJointSpringDamping# ( joint )

Parameters

joint - live ball-joint handle from CreatePhysicsBallJoint

Description

Returns the configured dimensionless spring damping ratio, including while disabled.

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, PhysicsBallJointTarget, PhysicsBallJointMotor.

Example

; PhysicsBallJointSpringDamping 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

damping#=0.2

; 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 ] change the damping; 1 settles without overshooting
    If KeyHit(26) And damping>0 Then damping=damping-0.1
    If KeyHit(27) Then damping=damping+0.1
    PhysicsBallJointSpring joint,True,1,damping
    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   [ / ]: damping   Esc: exit"
    Text 0,20,"PhysicsBallJointSpringDamping(joint) = "+PhysicsBallJointSpringDamping(joint)
    Text 0,40,"(frequency "+PhysicsBallJointSpringHertz(joint)+" Hz)"

    Flip

Wend

FreePhysicsWorld world
End

Index