Blitz3D+ Command Reference

PhysicsShapeGetRestitution# ( shape[,slot] )

Parameters

shape - live physics-shape handle

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

Description

Returns the selected slot's restitution coefficient; zero is inelastic.

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, PhysicsShapeTangentVelocity, PhysicsMeshTriangleMaterial, PhysicsTerrainCellMaterial, PhysicsQueryMaterialSlot.

Example

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

; Three test objects side by side, each with a different material
Dim things(3)
Dim bodies(3)
Dim shapes(3)
For i=1 To 3
    things(i)=CreateSphere(16)
    ScaleEntity things(i),0.4,0.4,0.4
    bodies(i)=CreatePhysicsBody(world,things(i),PHYSICS_DYNAMIC)
    shapes(i)=PhysicsBodySphere(bodies(i),0.8)
    EntityColor things(i),255,120,70
    PhysicsShapeMaterialRestitution shapes(i),1,(i-1)*0.45
Next
Launch()

While Not KeyDown(1)

    ; R launches them again
    If KeyHit(19) Then Launch()

    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: launch again   Esc: exit"
    For i=1 To 3
        Text (i-1)*210,20,"PhysicsShapeGetRestitution = "+PhysicsShapeGetRestitution(shapes(i))
    Next

    Flip

Wend

FreePhysicsWorld world
End

Function Launch()
    For i=1 To 3
        ResetPhysicsBody bodies(i),i*2-4,4,0,0,0,0
    Next
End Function

Index