Blitz3D+ Command Reference

PhysicsJointEventTag ( world,index )

Parameters

world - a current physics world handle

index - one-based index in the copied joint overload batch

Description

Reads event index 1 through CountPhysicsJointEvents(world) from the copied overload batch.

Returns the joint's signed application tag as captured after the step. It survives joint/body deletion and later SetPhysicsJointTag calls. Tags need not be unique.

Events persist until the world's next StepPhysics or destruction. Deleting an event's joint does not renumber the remaining events, and reused slots never substitute new identities. Invalid indices raise a runtime error. Events do not automatically break joints and do not store the peak crossing force/torque.

Invalid, stale or wrong-kind handles raise a runtime error.

Requires Extended mode.

See also: PhysicsJointSpring, PhysicsJointFrame, PhysicsJointThresholds, PhysicsJointEventJoint, StepPhysics.

Example

; PhysicsJointEventTag 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)

; A static post, and a door hinged to it on a vertical axis
post=CreateCube()
ScaleEntity post,0.1,1.5,0.1
PositionEntity post,-1.5,1.5,0
EntityColor post,150,150,160
post_body=CreatePhysicsBody(world,post,PHYSICS_STATIC)
post_shape=PhysicsBodyBox(post_body,0.2,3,0.2)
door=CreateCube()
ScaleEntity door,1.2,1.4,0.05
PositionEntity door,-0.2,1.5,0
EntityColor door,255,120,70
door_body=CreatePhysicsBody(world,door,PHYSICS_DYNAMIC)
door_shape=PhysicsBodyBox(door_body,2.4,2.8,0.1)
PhysicsBodyDamping door_body,0,1
hinge=CreatePhysicsHingeJoint(post_body,door_body,-1.4,1.5,0,0,1,0)

; Report overloads above 12 N or 12 N m, for example when the door slams
PhysicsJointThresholds hinge,12,12
SetPhysicsJointTag hinge,7
PhysicsJointLimits hinge,True,-Pi/4,Pi/4

While Not KeyDown(1)

    ; Space pushes the far edge of the door
    If KeyHit(57)
        TFormPoint 1,0,0,door,0
        PhysicsBodyImpulseAt door_body,0,0,2,TFormedX(),TFormedY(),TFormedZ()
    EndIf

    StepPhysics world,1.0/60.0,4

    ; The event copies the joint's tag, so it is easy to recognise
    For e=1 To CountPhysicsJointEvents(world)
        last_tag=PhysicsJointEventTag(world,e)
    Next

    ; Flash the door red for a moment after each overload event
    If CountPhysicsJointEvents(world)>0 Then flash=20
    If flash>0
        flash=flash-1
        EntityColor door,255,40,40
    Else
        EntityColor door,255,120,70
    EndIf

    ; 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: push   Esc: exit"
    Text 0,20,"PhysicsJointEventTag of the last overload: "+last_tag

    Flip

Wend

FreePhysicsWorld world
End

Index