Physics troubleshooting: diagnose in order
Check collisions, signals, jitter, tunneling and physics time without random setting changes.
Reduce the reproduction first
Keep one problematic object, one floor and the active script. Compare with the complete 2D and 3D levels. Record backend, tick frequency, dimensions, speed, mass, filters and action order. Pause/step inspection and visible shapes are more useful than raising every setting at random.
Missing collision or signal
| Symptom | Check in this order |
|---|---|
| Passes through a wall even slowly | Body type; direct CollisionShape parent; Shape and dimensions; Disabled; Layer/Mask; current world |
| Visible mesh, no contact | The visual model does not automatically create a shape; hide artwork and inspect geometry |
| Area has no entry event | Monitoring, active shape, area Mask against target Layer, BodyEntered versus AreaEntered, other area Monitorable, physics tick |
| RigidBody has no contact event | ContactMonitor and MaxContactsReported > 0; actual contact rather than visual proximity |
| Ray misses | World From/To versus local TargetPosition, Mask, CollideWithAreas, RID exclusions, origin inside a shape |
| Old result after a change | The query reads prior physics state; allow a tick, or use ForceRaycastUpdate for RayCast when appropriate |
| Every instance changes geometry | Shared Shape resource; clone before resizing |
| Error disabling an area in a signal | Set a handled flag first, then SetDeferred/QueueFree; do not mutate locked structure immediately |
These cases are exercised by the published examples. Other cases below are diagnostic directions, not universal fixes or tests of every device.
A fast object crosses a wall
Compare travel per tick, speed / ticksPerSecond, with wall thickness and object dimensions. Discrete detection can place the object on the opposite side. First rule out direct Transform teleporting, filters and thin/zero-sized geometry. Then evaluate supported CCD modes, thicker geometry, permitted speed or tick frequency. CCD has costs and limitations; one flag does not guarantee every projectile hit. A gameplay bullet often needs a separate segment/shape query from its previous to next position and an explicit hit policy.
Jittering stacks, thin objects or cylinders
Remove initial penetration, extreme mass/scale ratios, overly thin shapes, competing Position/Rotation scripts and a moving parent of a dynamic body. Check PhysicsMaterial, sleep and the selected backend's solver settings. More iterations/ticks require CPU measurement and do not repair unsuitable geometry. Compare a capsule for a cylindrical character; choose an object's shape through intended behavior and testing, not appearance alone.
Scale, seams and vehicles
Set dimensions on Shape with unit scale in the physics branch. Check every ancestor transform. Compound tiles/triangles can expose internal edges that catch moving bodies; try continuous simplified geometry, suitable merging and rounded character shapes. Changing every margin without analysis can introduce gaps or penetration.
VehicleBody is a ready-made model with limits, not a guarantee of stable realistic vehicles at any speed. Check centre of mass, suspension, radii, units, chassis geometry and tick size first. An unusual vehicle can require custom force control. This test suite does not exercise VehicleBody, tall stacks, thin cylinders or CCD.
Simulation slows down
Measure physics, scripts and rendering separately. Contact between large groups, complex concave/convex collections or many signals can sharply raise work. Check active body/contact counts, geometry rebuilding and callback allocations. Sleep/deactivate objects under an explicit policy when they have no useful action, without breaking player collisions.
If a frame cannot complete the required physics steps, physics/common/max_physics_steps_per_frame can limit catch-up work. Raising the limit does not make a step cheaper. Reduce cost and measure worst cases first; time scale, FPS or interpolation changes can hide symptoms without removing work. Do not assume bit-identical complex simulation across platforms without a separate determinism strategy.
Far from the origin
Large coordinates reduce available transform/contact/render precision. First move a minimal reproduction near zero. Regional worlds, origin shifting and builds with different precision need agreement across systems and separate validation. A one-crate scene does not prove large-world behavior. See large coordinates.