PhysicsExplosion world,x#,y#,z#,radius#,impulse_per_area#[,falloff#][,mask_bits]
Parameters
|
world - live physics-world handle x# - explosion centre X in world metres y# - explosion centre Y in world metres z# - explosion centre Z in world metres radius# - non-negative full-strength radius in metres, measured to the nearest point on each shape impulse_per_area# - signed impulse per projected square metre, in N s/m2; negative values pull inward falloff# (optional) - non-negative additional distance over which strength decreases linearly to zero; 0 (default) mask_bits (optional) - 32-bit category mask; 0 selects none; -1 selects all exposed category bits (default) |
Description
|
Applies an explosion's radial impulse to nearby dynamic bodies. Applies one immediate radial impulse to each matching enabled dynamic sphere, capsule or convex hull. The native helper uses the projected shape area facing the explosion and the distance from the centre to the nearest shape surface. Shapes within radius receive full strength; a positive falloff reduces strength linearly beyond radius to zero at radius + falloff. It does not create a persistent force or an expanding shock wave. Positive impulse_per_area pushes away; negative values produce an implosion. The impulse acts at the nearest shape point, so offset geometry can produce torque. When the centre is inside a shape, the native helper uses that shape’s centroid to determine direction. At the exact centroid it falls back to body-local +X, rotated into world space. mask_bits matches each shape’s category bits. Collision masks and collision groups do not affect this selection. Sensor geometry on dynamic bodies participates; multiple shapes on one body contribute separately. Static, kinematic and disabled bodies are omitted. Matching bodies within the affected surface-distance range are awakened, including zero-strength edge cases. A zero mask selects and wakes nothing. There is no line-of-sight/occlusion test: walls do not shield bodies. Use category masks to select eligible geometry. This command does not move visual meshes until the next StepPhysics synchronises their entities. Native motion/speed restrictions are enforced by the subsequent solver step. All arguments must be finite. Radius and falloff are non-negative, and their combined extent, world query bounds and impulse magnitude must be representable. Invalid input raises a runtime error before the native operation. The world handle must be live and cannot be stepping. Standalone-world explosions are included in physics recording/replay. For a managed world borrowed with GetWorldPhysics, the command includes pending entity transforms, collider changes, mass, rotation locks and inherited visibility/enabling. It prepares every affected body's blast before committing scene edits. If geometry, impulse arithmetic or resulting motion cannot be represented, or preparation runs out of memory, the command reports an error while retaining committed bodies, colliders, motion, sleep state, contact results and queued inputs. Authored entity edits remain pending for repair and retry. Only each free dynamic body's canonical collider contributes in a managed world. Compatibility copies and Collisions-controlled movers receive no direct blast. Managed canonical colliders use category bit 1; mask_bits is not an EntityType number. Each accepted impulse applies immediately once, without advancing time or consuming queued force/wind. Use UpdateWorld to advance this scene and publish its simulated entity transforms. Matching zero-strength blasts still wake bodies; a zero mask causes no direct blast wake, although reconciled edits can wake bodies independently. Requires Extended mode. See also: PhysicsShapeWind, GetWorldPhysics, PhysicsShapeFilter, PhysicsBodyForceAt, PhysicsBodyImpulseAt, StepPhysics. |
Example
; PhysicsExplosion Example ; ------------------------ ; Requires Extended mode. Graphics3D 640,480,0,2 SetBuffer BackBuffer() Const PHYSICS_STATIC=0 Const PHYSICS_DYNAMIC=2 Const CRATE_COUNT=12 SeedRnd MilliSecs() camera=CreateCamera() PositionEntity camera,0,6,-12 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 pile of crates, dropped from random heights Dim crates(CRATE_COUNT) Dim crate_bodies(CRATE_COUNT) For i=1 To CRATE_COUNT crates(i)=CreateCube() ScaleEntity crates(i),0.5,0.5,0.5 crate_bodies(i)=CreatePhysicsBody(world,crates(i),PHYSICS_DYNAMIC) crate_shape=PhysicsBodyBox(crate_bodies(i),1,1,1) Next DropPile() While Not KeyDown(1) ; R drops the pile again If KeyHit(19) Then DropPile() ; Space sets off an explosion under the middle of the pile If KeyHit(57) Then PhysicsExplosion world,0,0,0,4,6 StepPhysics world,1.0/60.0,4 ; Orange crates are awake, grey crates are asleep For i=1 To CRATE_COUNT If PhysicsBodyIsAwake(crate_bodies(i)) EntityColor crates(i),255,120,70 Else EntityColor crates(i),150,150,150 EndIf Next ; 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: drop again Space: explode Esc: exit" Text 0,20,"PhysicsExplosion world,0,0,0,4,6" Text 0,40,"Radius 4 m; 6 N s of impulse for each square metre facing the blast" Flip Wend FreePhysicsWorld world End Function DropPile() For i=1 To CRATE_COUNT ResetPhysicsBody crate_bodies(i),Rnd(-1.5,1.5),2+i*0.8,Rnd(-1.5,1.5),0,Rnd(Pi),0 Next End Function
Index