SCRIPTING API / Physics / Physics

Physics

Questions about the physics world of the running scene: rays, shape casts and overlaps against colliders, filtered by gameplay layers and collision layers. Queries see the state of the last fixed step.

Kindclass

NamespaceKroys.EngineScripting

Members17

SourcePhysics.cs

EXAMPLE

In a script

Build masks with LayerMask (gameplay layers) and CollisionLayerMask. Triggers are ignored unless a query asks for them. On the dedicated server the same queries run against the server's scene.

Gameplay.cs

public sealed class LaserPointer : EntityScript
{
    public float Range = 50.0f;

    protected override void OnFixedUpdate(float fixedDeltaTime)
    {
        if (!Input.IsActionHeld("Fire")) return;
        Transform transform = Transform;
        Vector3 origin = transform.WorldPosition + transform.WorldForward * 0.5f;

        // Only the gameplay layers that matter; triggers are ignored.
        uint mask = Physics.LayerMask(GameplayLayer.Default, GameplayLayer.Enemy);
        if (Physics.Raycast(origin, transform.WorldForward, Range, mask, out RaycastHit hit))
            Debug.Log($"hit {hit.Entity.Name} at {hit.Distance:0.0} m, normal {hit.Normal}");

        // Everything within 3 m of the hit point, for an area effect.
        foreach (Entity nearby in Physics.OverlapSphere(origin + transform.WorldForward * hit.Distance, 3.0f, mask))
            Debug.Log($"near: {nearby.Name}");
    }
}

REFERENCE

Members

Methods

#public static bool Raycast(Vector3 origin, Vector3 direction, float distance, out RaycastHit hit)

Casts a ray through the active physics world.

methodstatic

#public static bool Raycast(Vector3 origin, Vector3 direction, float distance, uint gameplayLayerMask, out RaycastHit hit)

Casts a ray through the active physics world using a gameplay layer mask.

methodstatic

#public static bool Raycast(Vector3 origin, Vector3 direction, float distance, out RaycastHit hit, float debugDrawDurationSeconds)

Casts a ray through the active physics world and draws it for the requested duration when query tracing is enabled in the editor.

methodstatic

#public static bool Raycast(Vector3 origin, Vector3 direction, float distance, out RaycastHit hit, bool debugDraw)

Casts a ray through the active physics world and optionally draws it when query tracing is enabled in the editor.

methodstatic

#public static bool Raycast(Vector3 origin, Vector3 direction, float distance, out RaycastHit hit, bool debugDraw, float debugDrawDurationSeconds)

Casts a ray through the active physics world and optionally draws it for the requested duration when query tracing is enabled in the editor.

methodstatic

#public static bool Raycast(Vector3 origin, Vector3 direction, float distance, out RaycastHit hit, uint gameplayLayerMask, bool includeTriggers, bool debugDraw = false, float debugDrawDurationSeconds = 0.0f)

Casts a ray through the active physics world with gameplay layer and trigger filters.

methodstatic

#public static RaycastHit[] RaycastAll( Vector3 origin, Vector3 direction, float distance, uint gameplayLayerMask = uint.MaxValue, bool collectAllHits = true, bool includeTriggers = false, bool debugDraw = false, float debugDrawDurationSeconds = 0.0f)

Casts a ray and returns distance-sorted collider hits. When collectAllHits is false, only the nearest hit on each gameplay layer is returned.

methodstatic

#public static int RaycastBatch(RaycastCommand[] commands, RaycastHit[] hits)

Runs many raycasts through one native call. This reduces scripting interop overhead for stress tests.

methodstatic

#public static int RaycastBatch(RaycastBatchBuffer buffer, int count = -1)

Runs many raycasts using a reusable buffer to avoid per-frame managed allocations.

methodstatic

#public static bool SphereCast(Vector3 origin, float radius, Vector3 direction, float distance, out RaycastHit hit, uint gameplayLayerMask = uint.MaxValue, uint collisionLayerMask = uint.MaxValue, bool includeTriggers = false, bool debugDraw = false)

Sweeps a sphere through the active physics world and returns the first hit. A hit at distance 0 means the sphere already overlapped the body at origin.

methodstatic

#public static bool CapsuleCast(Vector3 origin, Quaternion rotation, float radius, float halfHeight, Vector3 direction, float distance, out RaycastHit hit, uint gameplayLayerMask = uint.MaxValue, uint collisionLayerMask = uint.MaxValue, bool includeTriggers = false, bool debugDraw = false)

Sweeps a capsule (segment along its local Y axis, halfHeight each side of the center) and returns the first hit.

methodstatic

#public static bool BoxCast(Vector3 origin, Quaternion rotation, Vector3 halfExtents, Vector3 direction, float distance, out RaycastHit hit, uint gameplayLayerMask = uint.MaxValue, uint collisionLayerMask = uint.MaxValue, bool includeTriggers = false, bool debugDraw = false)

Sweeps an oriented box and returns the first hit.

methodstatic

#public static Entity[] OverlapSphere(Vector3 center, float radius, uint gameplayLayerMask = uint.MaxValue, uint collisionLayerMask = uint.MaxValue, bool includeTriggers = false, bool debugDraw = false)

Entities whose colliders overlap a sphere.

methodstatic

#public static Entity[] OverlapCapsule(Vector3 center, Quaternion rotation, float radius, float halfHeight, uint gameplayLayerMask = uint.MaxValue, uint collisionLayerMask = uint.MaxValue, bool includeTriggers = false, bool debugDraw = false)

Entities whose colliders overlap a capsule (segment along its local Y axis).

methodstatic

#public static Entity[] OverlapBox(Vector3 center, Quaternion rotation, Vector3 halfExtents, uint gameplayLayerMask = uint.MaxValue, uint collisionLayerMask = uint.MaxValue, bool includeTriggers = false, bool debugDraw = false)

Entities whose colliders overlap an oriented box.

methodstatic

#public static uint CollisionLayerMask(params int[] layers)

Builds a mask for one or more collision layers (0..31, as set on colliders and in the project collision matrix).

methodstatic

#public static uint LayerMask(params GameplayLayer[] layers)

Builds a mask for one or more gameplay layers.

methodstatic

Signatures

public static bool Raycast(Vector3 origin, Vector3 direction, float distance, out RaycastHit hit)
public static bool Raycast(Vector3 origin, Vector3 direction, float distance, uint gameplayLayerMask, out RaycastHit hit)
public static bool Raycast(Vector3 origin, Vector3 direction, float distance, out RaycastHit hit, float debugDrawDurationSeconds)
public static bool Raycast(Vector3 origin, Vector3 direction, float distance, out RaycastHit hit, bool debugDraw)
public static bool Raycast(Vector3 origin, Vector3 direction, float distance, out RaycastHit hit, bool debugDraw, float debugDrawDurationSeconds)
public static bool Raycast(Vector3 origin, Vector3 direction, float distance, out RaycastHit hit, uint gameplayLayerMask, bool includeTriggers, bool debugDraw = false, float debugDrawDurationSeconds = 0.0f)
public static RaycastHit[] RaycastAll( Vector3 origin, Vector3 direction, float distance, uint gameplayLayerMask = uint.MaxValue, bool collectAllHits = true, bool includeTriggers = false, bool debugDraw = false, float debugDrawDurationSeconds = 0.0f)
public static int RaycastBatch(RaycastCommand[] commands, RaycastHit[] hits)
public static int RaycastBatch(RaycastBatchBuffer buffer, int count = -1)
public static bool SphereCast(Vector3 origin, float radius, Vector3 direction, float distance, out RaycastHit hit, uint gameplayLayerMask = uint.MaxValue, uint collisionLayerMask = uint.MaxValue, bool includeTriggers = false, bool debugDraw = false)
public static bool CapsuleCast(Vector3 origin, Quaternion rotation, float radius, float halfHeight, Vector3 direction, float distance, out RaycastHit hit, uint gameplayLayerMask = uint.MaxValue, uint collisionLayerMask = uint.MaxValue, bool includeTriggers = false, bool debugDraw = false)
public static bool BoxCast(Vector3 origin, Quaternion rotation, Vector3 halfExtents, Vector3 direction, float distance, out RaycastHit hit, uint gameplayLayerMask = uint.MaxValue, uint collisionLayerMask = uint.MaxValue, bool includeTriggers = false, bool debugDraw = false)
public static Entity[] OverlapSphere(Vector3 center, float radius, uint gameplayLayerMask = uint.MaxValue, uint collisionLayerMask = uint.MaxValue, bool includeTriggers = false, bool debugDraw = false)
public static Entity[] OverlapCapsule(Vector3 center, Quaternion rotation, float radius, float halfHeight, uint gameplayLayerMask = uint.MaxValue, uint collisionLayerMask = uint.MaxValue, bool includeTriggers = false, bool debugDraw = false)
public static Entity[] OverlapBox(Vector3 center, Quaternion rotation, Vector3 halfExtents, uint gameplayLayerMask = uint.MaxValue, uint collisionLayerMask = uint.MaxValue, bool includeTriggers = false, bool debugDraw = false)
public static uint CollisionLayerMask(params int[] layers)
public static uint LayerMask(params GameplayLayer[] layers)

KroysEngine 0.1.0 documentation, built from the engine repository by Tools/BuildDocsSite.py.