Blitz3D+ Command Reference

PhysicsShapeTangentVelocity shape,x#,y#,z#[,slot]

Parameters

shape - live physics-shape handle

x# - local surface velocity component in m/s
y# - local surface velocity component in m/s
z# - local surface velocity component in m/s

slot (optional) - 1-based material table entry; 1 (default)

Description

Sets the material's local target surface velocity in metres per second.

Native contact generation rotates this vector with the body and projects it onto the contact tangent plane. Entity/mesh scale does not multiply it; colliders are cooked into body-local space. A rotated conveyor therefore follows its body's local axes.

Handles must be live and of the correct kind. Material slots are 1-based; slot 1 is the base material and the first table entry, not an independent fallback. Mesh and terrain tables belong to each shape. Material edits retain density, body mass, filtering, event flags, shape tags and the public shape handle.

Friction, restitution and rolling resistance must be finite and non-negative. Values above one are permitted. Friction products and the squared tangent-velocity length must be representable. Invalid ranges or allocations fail before replacing the material/geometry. Readbacks do not wake bodies. Edits invalidate cached contact material sampling and wake affected enabled bodies; disabled bodies stay disabled. Replacing the native shape for table resizing/painting invalidates its current contacts.

Ray and contact-query material numbers are copied snapshots; later painting, table edits or shape destruction do not alter them. A current-contact query samples each point's assigned material when queried, which can differ from cached coefficients of the last solve after an edit. Native mesh/terrain contact response can average several touched triangle materials. Material IDs in hit events are copied at the hit.

Material table entries, painting, refresh and resulting wake operations record/replay through Blitz3D+. Table edits use an added native recording opcode, so such recordings require the patched Blitz3D+ player; older opcodes are unchanged. Terrain preferences under holes are wrapper metadata; later recorded refresh captures the resulting collision geometry. Physics replay does not restore render meshes or this editable authoring metadata.

Requires Extended mode.

See also: PhysicsShapeMaterial, PhysicsShapeMaterials, PhysicsMeshTriangleMaterial, PhysicsTerrainCellMaterial, PhysicsQueryMaterialSlot.

Example

; PhysicsShapeTangentVelocity 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 conveyor belt: its surface moves, but the belt itself stays put
belt=CreateCube()
ScaleEntity belt,4,0.2,0.8
PositionEntity belt,0,0.2,0
EntityColor belt,60,60,70
belt_body=CreatePhysicsBody(world,belt,PHYSICS_STATIC)
belt_shape=PhysicsBodyBox(belt_body,8,0.4,1.6)
speed#=2
PhysicsShapeTangentVelocity belt_shape,speed,0,0

; Three crates dropped onto the belt
Dim crate_bodies(2)
For i=0 To 2
    crate=CreateCube()
    ScaleEntity crate,0.3,0.3,0.3
    EntityColor crate,255,120,70
    crate_bodies(i)=CreatePhysicsBody(world,crate,PHYSICS_DYNAMIC)
    crate_shape=PhysicsBodyBox(crate_bodies(i),0.6,0.6,0.6)
    ResetPhysicsBody crate_bodies(i),i*1.5-3,1+i,0,0,0,0
Next

While Not KeyDown(1)

    ; R drops the crates on the belt again
    If KeyHit(19)
        For i=0 To 2
            ResetPhysicsBody crate_bodies(i),i*1.5-3,1+i,0,0,0,0
        Next
    EndIf

    ; [ and ] change the belt's surface speed along X
    If KeyHit(26) Then speed=speed-1
    If KeyHit(27) Then speed=speed+1
    PhysicsShapeTangentVelocity belt_shape,speed,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   [ / ]: belt speed   R: drop again   Esc: exit"
    Text 0,20,"PhysicsShapeTangentVelocity belt_shape,"+speed+",0,0"
    Text 0,40,"Crates touching the belt are carried along; a negative speed runs it backwards"

    Flip

Wend

FreePhysicsWorld world
End

Index