wave5-physics-world-singleton-queries

PhysicsWorldSingleton Spatial Queries

Intent

Perform runtime spatial queries (raycast, collider cast, distance, overlap) against the Unity Physics collision world using PhysicsWorldSingleton.

Use When

• Line-of-sight checks, ground detection, projectile trajectory, AOE range detection
• Spatial queries against current physics world state (after world build)

Avoid When

• Queries inside FixedStepSimulationSystemGroup before PhysicsBuildWorldGroup — world not yet built
• Per-entity collision response — use trigger/collision event buffers instead

Senior Pattern

[UpdateInGroup(typeof(SimulationSystemGroup))]
[BurstCompile]
public partial struct RaycastSystem : ISystem
{
    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        // Complete physics jobs before reading PhysicsWorldSingleton:
        state.EntityManager.CompleteDependencyBeforeRO<PhysicsWorldSingleton>();

        var physicsWorld = SystemAPI.GetSingleton<PhysicsWorldSingleton>().PhysicsWorld;

        state.Dependency = new RaycastJob
        {
            World = physicsWorld.CollisionWorld,
            Input = new RaycastInput
            {
                Start = float3.zero,       // replace with actual origin
                End = float3.zero + math.forward() * 100f,
                Filter = new CollisionFilter
                {
                    BelongsTo = ~0u,
                    CollidesWith = 1u << 0,  // target layer only
                    GroupIndex = 0
                }
            },
            Hits = new NativeList<RaycastHit>(Allocator.TempJob)
        }.Schedule(state.Dependency);
    }
}

[BurstCompile]
public struct RaycastJob : IJob
{
    [ReadOnly] public CollisionWorld World;
    public RaycastInput Input;
    public NativeList<RaycastHit> Hits;

    public void Execute() { World.CastRay(Input, ref Hits); }
}

Available query types:

// Single closest hit:
world.CollisionWorld.CastRay(input, out RaycastHit hit)

// All hits:
world.CollisionWorld.CastRay(input, ref NativeList<RaycastHit> hits)

// Shape cast:
world.CollisionWorld.CastCollider(input, out ColliderCastHit hit)

// Nearest body to point:
world.CollisionWorld.CalculateDistance(input, out DistanceHit hit)

// Broad-phase AABB overlap:
world.CollisionWorld.OverlapAabb(input, ref NativeList<int> bodyIndices)