Blitz3D+ Command Reference

RefreshPhysicsHull shape,mesh[,x#][,y#][,z#][,pitch#][,yaw#][,roll#]

Parameters

shape - live physics-shape handle

mesh - live source mesh entity

x# (optional) - frame X offset in body-local metres; 0 (default)
y# (optional) - frame Y offset in body-local metres; 0 (default)
z# (optional) - frame Z offset in body-local metres; 0 (default)

pitch# (optional) - frame pitch in radians; 0 (default)
yaw# (optional) - frame yaw in radians; 0 (default)
roll# (optional) - frame roll in radians; 0 (default)

Description

Rebuilds a convex hull collider from a mesh's current vertices.

Cooks a new convex hull from every surface vertex of the supplied mesh entity, then replaces the collider. It uses source-local vertices multiplied by the source entity's world scale. Source world position and rotation are ignored. The optional body-local frame is applied after scale; its angles are radians. Requires at least four vertices spanning a volume. Native cooking approximates the hull with at most 64 vertices. This command can convert another shape kind to a hull.

The shape handle, body/world ownership, public enumeration order, application tag, density, filter, sensor/event settings and material table remain intact. Sphere, capsule and box setters and RefreshPhysicsHull require a one-slot material table; explicitly remap existing faces and shrink larger tables before converting to a convex shape. Triangle meshes and terrain remain restricted to static bodies.

Primitive diameters and box dimensions must be positive; all positions, dimensions and frame angles must be finite. Replacement data is validated and cooked before native mutation. Invalid inputs raise a runtime error and retain the previous collider. Supported source limits are 1,048,576 vertices and 1,048,576 triangles. Coordinates/bounds must fit the pinned Box3D coordinate range; mass and inertia must remain finite and representable. Native allocation failure follows the library's allocation policy; these limits are not a guarantee that every maximum-size mesh will fit memory.

Successful edits recalculate body mass from all shapes, replacing custom mass data. Moving the centre of mass preserves point velocity, including saved velocity on disabled bodies. Enabled bodies are woken; disabled bodies remain disabled. Geometry changes invalidate contacts and wake affected touching bodies. Replacing an identical shared hull can retain its native proxy/contact cache. Queries run afterward see the current collider; existing owned queries retain their historical numbers and still resolve this live public shape handle.

Visual geometry changes never refresh physics automatically. Refresh is an explicit authoring operation, not a dynamic deformable-mesh solver. Native mesh geometry is borrowed: the wrapper releases previous cooked storage only after native references are gone. Hull geometry is copied into the native world database. All replacement effects record/replay. Hull/mesh replacement uses added opcodes and requires the patched Blitz3D+ player; older opcodes retain their values. Wrapper frame/dimension metadata and editable visual assets are not restored by physics replay.

Requires Extended mode.

See also: PhysicsShapeSphere, PhysicsShapeCapsule, PhysicsShapeBox, RefreshPhysicsMesh, PhysicsShapeRadius, PhysicsShapeLocalMinX.

Example

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

; An empty pivot carries the body; a child mesh shows its collider
root=CreatePivot()
body=CreatePhysicsBody(world,root,PHYSICS_DYNAMIC)

; A cube mesh whose top face can be pinched into a point
taper#=1
model=CreateCube(root)
ScaleEntity model,0.5,0.5,0.5
EntityColor model,255,120,70
shape=PhysicsBodyHull(body,model)
ResetPhysicsBody body,0,2,0,0,0,0

While Not KeyDown(1)

    ; Space tosses the body, R drops it again
    If KeyHit(57)
        PhysicsBodyImpulse body,0,5,0
        PhysicsBodyAngularImpulse body,0.5,0,0.5
    EndIf
    If KeyHit(19) Then ResetPhysicsBody body,0,2,0,0,0,0

    ; [ and ] pinch or widen the top of the mesh, then rebuild its hull collider
    change=KeyHit(27)-KeyHit(26)
    If change<>0
        taper=taper+change*0.25
        If taper<0 Then taper=0
        If taper>1 Then taper=1
        surface=GetSurface(model,1)
        For v=0 To CountVertices(surface)-1
            If VertexY(surface,v)>0 Then VertexCoords surface,v,Sgn(VertexX(surface,v))*taper,1,Sgn(VertexZ(surface,v))*taper
        Next
        UpdateNormals model
        RefreshPhysicsHull shape,model
    EndIf
    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: toss   R: reset   [ / ]: pinch the top"
    Text 0,20,"Esc: exit"
    Text 0,40,"RefreshPhysicsHull shape,model   (top width "+taper*100+"%)"
    Text 0,60,"The hull collider is rebuilt from the edited mesh"

    Flip

Wend

FreePhysicsWorld world
End

Index