Blitz3D+ Command Reference

PhysicsShapeSphere shape,diameter#[,x#][,y#][,z#]

Parameters

shape - live physics-shape handle

diameter# - sphere diameter in metres

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)

Description

Replaces the shape with a sphere of the supplied diameter and body-local centre.

All lengths are metres. The radius readback is half the diameter. Sphere orientation has no effect; its frame getters return the centre and zero angles.

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: PhysicsShapeCapsule, PhysicsShapeBox, RefreshPhysicsHull, RefreshPhysicsMesh, PhysicsShapeRadius, PhysicsShapeLocalMinX.

Example

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

; Start with a 1 m sphere collider and a ball to show it
diameter#=1
model=CreateSphere(16,root)
ScaleEntity model,0.5,0.5,0.5
EntityColor model,255,120,70
shape=PhysicsBodySphere(body,1)
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 ] resize the sphere; the collider and the ball change together
    change=KeyHit(27)-KeyHit(26)
    If change<>0
        diameter=diameter+change*0.25
        If diameter<0.25 Then diameter=0.25
        PhysicsShapeSphere shape,diameter
        ScaleEntity model,diameter/2,diameter/2,diameter/2
    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   [ / ]: size   Esc: exit"
    Text 0,20,"PhysicsShapeSphere shape,"+diameter
    Text 0,40,"The diameter is in metres"

    Flip

Wend

FreePhysicsWorld world
End

Index