Physics with entities

Make ordinary Blitz3D entities fall, stack, bounce and push each other. Select Program > Language mode > Extended. You can build a physical scene using entity types, EntityPhysics, Physics and your familiar UpdateWorld loop.

New to collisions and physics? Blitz3D+ Basics: Collisions and Physics is an animated lesson that starts from the beginning.

Start with a falling box

Open the complete falling-box sample. Its physics setup is:

SetCollisionBackend 1
Const SCENERY=1, PROPS=2, BODY_STATIC=0

ground=CreateCube()
ScaleEntity ground,10,.5,10
PositionEntity ground,0,-.5,0
EntityType ground,SCENERY
EntityPhysics ground,BODY_STATIC

crate=CreateCube()
ScaleEntity crate,.5,.5,.5
PositionEntity crate,0,6,0
EntityType crate,PROPS
EntityPhysics crate

Physics PROPS,SCENERY

The sample supplies a camera, light, rendering and a paced update loop. The floor stays fixed, and the crate falls under gravity. No Collisions declaration or native body/shape/world handle is needed.

SetCollisionBackend 1 selects modern collision and physics for this Blitz world.
EntityType labels a category. A label alone does not create a physical body.
EntityPhysics enrolls an entity. The default is a free dynamic body; mode 0 is static scenery and mode 1 is a platform driven by your program.
Physics PROPS,SCENERY lets those categories respond physically. Add Physics PROPS,PROPS for stacking crates.

Choose who moves each object

Role	Setup	Movement
Static scenery	`EntityPhysics entity,0`	Fixed during normal simulation. Transform edits deliberately relocate it.
Kinematic platform	`EntityPhysics entity,1`	Position or rotate it before UpdateWorld. Its contact velocity pushes and carries other bodies.
Dynamic prop	`EntityPhysics entity`	Gravity, forces and contacts determine its motion.
Classic player	Use it as a `Collisions` source.	Your movement and gravity code supplies intent. The collision controller constrains it. Do not also explicitly enroll that source.

One world unit is conventionally one metre. Default gravity is (0,-9.81,0), mass is 1 kg, friction is 0.5 and bounce is 0. Change them with WorldGravity, EntityMass, EntityFriction and EntityBounce. These property commands can be used before enrollment.

Use simple geometry first

Auto shape uses an authored collider when one exists. Otherwise a moving mesh gets a fitted box, a static mesh gets exact triangles and static terrain gets a heightfield. A pivot needs an explicit EntityBox, EntityRadius, EntityCapsule or EntityConvex. Dimensions are local, with entity scale applied once. Prefer an explicit box for simple moving platforms; exact meshes and terrain require static mode.

EntityPhysics entity,mode,shape also accepts a named shape selector: 0 auto, 1 box, 2 sphere/radius, 3 capsule, 4 convex hull, 5 exact mesh, 6 terrain. Declare your own Const names as the samples do. These are different from the method numbers used by Collisions.

Update, push and reset

UpdateWorld 1 advances one nominal tick: 1/60 second. It does not mean one second. The examples use a 60 Hz timer. A variable-step loop converts elapsed seconds to nominal ticks by multiplying by 60. Call UpdateWorld once for the selected scene, then RenderWorld; do not separately step its physics world.

Physics is repeatable: the same program, given the same input and the same UpdateWorld steps, moves and collides everything exactly as before, each time it runs on the same machine and build. That makes replays and repeatable tests possible. A variable-step loop repeats only if its elapsed times repeat, so use a fixed tick for any run that must repeat.

EntityImpulse adds a one-off push. EntityForce adds force over the next positive update and must be reissued for continuous thrust. EntityVelocity replaces linear velocity. Their vectors default to world axes; pass False for local axes. They require an enabled free dynamic body. EntityGravity scales a prop's gravity, and EntityRotationLock locks selected angular axes.

Motion values must fit the simulation's calculations, including squared speed and the effect of mass and inertia. Unrepresentable velocity or impulse results raise an error before that input changes motion. These checks also apply to borrowed PhysicsBodyVelocity, angular velocity, and impulse commands. Force and torque additions reject unrepresentable combined magnitudes while retaining earlier queued input. Motion commands use pending mass, collider, pose and lock settings together. If the command is rejected, those edits remain pending and the previously committed scene stays intact.

Before a positive update starts, queued forces, torque, wind and scaled gravity are checked using pending mass, inertia, damping, motion and the chosen substep. An unrepresentable result rejects the update before committing edits or consuming inputs. Repair the settings or clear queued loads with ResetEntity before retrying. Later slices check the motion produced so far; an error after simulation has advanced does not undo that elapsed simulation.

A large spin can also overflow the rotational correction used for bodies whose inertia differs between axes. Such a spin may fit the velocity setter but still cause a gyroscopic integration error on the next positive update. Reduce the angular velocity or reset the entity before retrying; the initial rejection preserves the committed scene and leaves authored edits pending.

Changing a spinning body's collider can move its mass centre and change its centre velocity. These calculations must remain representable even for hidden bodies, UpdateWorld 0, and synchronization through borrowed-handle commands. Mass and rotation-lock edits are checked at the same boundary. An invalid change rejects the whole synchronization, including unrelated pending edits. Restore safe collider or role settings before retrying, then reduce the spin before applying the intended change again.

For respawning, position the entity and call ResetEntity to clear velocity, queued forces and interpolation history. A position edit without reset preserves a dynamic body's motion. HideEntity also suspends physics; showing it restores its retained motion unless a reset cleared it. Hiding a visual child separately allows its enabled physical parent to remain active.

Add props to a classic game

Collisions PLAYER,SCENERY,3,2
Physics PLAYER,PROPS
Physics PROPS,SCENERY
Physics PROPS,PROPS

Keep the player's existing movement policy and explicitly enroll the props. Modern collisions and entity physics share one solve, so the player can push or ride a crate while the crate retains momentum. Use distinct type pairs: the same unordered pair cannot have both a Collisions rule and a Physics rule. ClearCollisions only removes classic rules; Physics A,B,False removes a physical pair.

Backend 0 retains its original collision behavior. Independently created low-level Physics worlds remain separate and manually stepped.

An enrolled prop can also be a classic collision destination. Match the method to its selected shape: 1 for radius/ellipsoid or capsule, 2 for exact mesh/terrain, 3 for box, and 4 for convex hull. Both rule families then use the same dimensions, including scaling and fitted hulls, while retaining their own material or sensor response. A mesh-derived hull needs no extra EntityConvex declaration.

Read the results

Use EntityCollided for touching, or CountCollisions and CollisionEntity/NX/NY/NZ for individual contacts. Physical results include resting and sleeping contacts. A normal pointing upward can identify support; it is not a complete character controller. EntityHit returns the strongest qualifying impact, including an impact in an earlier solver slice. Resting support does not count as repeated hits.

Reuse advanced features when needed

EntityPhysicsBody(entity) returns its real managed body and GetWorldPhysics() returns the shared world. They reconcile pending configuration without stepping. Use these borrowed handles with existing joint and query commands. Keep entity lifetime and UpdateWorld in charge: do not free managed bodies/shapes/worlds or call StepPhysics on them. Managed recording/replay and structural collider edits through the low-level API are rejected.

Queries read the committed scene. After later entity edits, call GetWorldPhysics() again or UpdateWorld to synchronize before querying. Saved query results keep their geometry and tags across updates and collider rebuilding; an obsolete shape identity reads as zero. A body target survives rebuilding, while a target set to an old shape must be changed or cleared. Compatibility shapes can also appear as hits on the same body, subject to the normal sensor and target filters.

Complete examples

For optional collider diagnostics, obtain world=GetWorldPhysics(), then call PhysicsDebugDraw world,camera,4096 after RenderWorld and before Flip. The overlay shows each body's role and identity; solid edges use role colours and short orange segments show classic compatibility geometry. Label counts C/K mean canonical/compatibility colliders. See PhysicsDebugDraw for colours, clipping and limits. This is a development aid; games do not need debug commands to configure physics.

Falling crates: stacking, mass, friction, an impulse, pause and reset.
Balls and ramps: compare three restitution values.
Player, crate and platform: authored movement, dynamic support, jumping and a kinematic platform.
Projectile impacts: launch velocity, impact reporting and physical response.
Borrowed joint: a pendulum using the existing distance-joint command.

Entity-physics commands | Advanced Physics reference | Guides

Blitz3D+ Guides