Physics Actions

v1.0

Physics Query Result

PysicsQueryResult is a unified result container for all Physics 3D and Physics 2D query operations. The Blackboard Result Positing Actions below all post this data object to the Blackboard. Other scripts and actions can then make use of the data.

// 1. Retrieve from blackboard
var result = executor.Blackboard.Get<PhysicsQueryResult>("PhysicsRaycastResult");

// 2. Check validity
if (result == null || !result.hasHit)
    return;

// 3. Use the data
RaycastHit hit = result.firstHit;
ApplyDamage(hit.collider.gameObject);

// Counts & checks
result.hitCount                 // int - Number of hits
result.hasHit                   // bool - hitCount > 0

// Physics 3D data
result.raycastHits              // List<RaycastHit> - Raycast/cast hits
result.colliders                // List<Collider> - Overlap results
result.firstHit                 // RaycastHit - First hit (convenience)
result.firstCollider            // Collider - First collider (convenience)

// Physics 2D data
result.raycastHits2D            // List<RaycastHit2D> - 2D hits
result.colliders2D              // List<Collider2D> - 2D overlaps
result.firstHit2D               // RaycastHit2D - First 2D hit
result.firstCollider2D          // Collider2D - First 2D collider

result.GetHitGameObject(index)  // Get GameObject at index
result.GetHitPoint(index)       // Get hit point at index
result.GetHitNormal(index)      // Get hit normal at index
result.GetHitDistance(index)    // Get hit distance at index

Blackboard Result Posting Actions

The following physics query Actions implement the IPostBlackboardResults interface, which standardizes how physics query results are saved to the blackboard for later use by other actions. Each action exposes a ResultKey property for the Blackboard storage key, a UseGlobalBlackboard toggle to choose between local (executor) or global blackboard storage, and a computed TargetBlackboard property that resolves to the appropriate blackboard instance.

This consistent interface makes it easy to discover and work with any action that posts results to the blackboard, enabling powerful data-driven workflows where physics queries feed into subsequent action logic.

In this example, our PhysicsSpherecastAction will save its results using the key "Demo Sphere Cast Result".

At runtime, after we execute this Action, the Action Blackboard reports that we have saved the result to the Blackboard.

Physics 2D Circle Cast Action

Sweeps a 2D circle along a direction and saves all collision hits to the blackboard as a PhysicsQueryResult. Supports auto-expanding arrays for detecting large numbers of colliders. Perfect for radial sweep detection, projectile collision prediction, or ground detection for circular characters.

Physics 2D Overlap Box Action

Queries all 2D colliders overlapping a rectangular area at a point in time and posts results to the blackboard. The box dimensions, position, and rotation can be target-relative or fixed. Great for area-of-effect queries, proximity detection, or detecting objects within zones.

Physics 2D Overlap Circle Action

Detects all 2D colliders within a circular area and stores the results to the blackboard. The circle radius and center position can be configured with optional target-relative positioning. Excellent for radial proximity checks, blast radius detection, or sensor-style queries.

Physics 2D Overlap Point Action

Checks if any 2D collider exists at a specific point and optionally stores the first found collider or a boolean result to the blackboard. Lightweight single-point query useful for precise click detection, spawn position validation, or checking if a coordinate is occupied.

Physics Raycast Action

Performs a 3D raycast from an origin point in a direction and saves all hits to the blackboard as a PhysicsQueryResult. Supports target-relative origin and direction with configurable max distance and layer filtering. Essential for 3D line-of-sight, weapon hit detection, or interaction raycasts.

Physics Spherecast Action

Sweeps a 3D sphere along a direction and stores all collision hits to the blackboard. The sphere radius, origin, and direction can be target-relative with optional hit count tracking. Perfect for thick raycasts, large projectile collision prediction, or character controller ground detection.

Physics Boxcast Action

Casts a 3D box (oriented bounding box) along a direction and posts all hits to the blackboard. The box half-extents, center, and orientation support target-relative configuration. Ideal for vehicle collision prediction, rectangular swept volumes, or oriented area queries along a path.

Physics Capsule Cast Action

Performs a 3D capsule cast (swept capsule volume) and saves all hits to the blackboard with optional hit count storage. The capsule endpoints, radius, and direction can be configured with target-relative positioning. Great for character controller sweeps, cylindrical collision prediction, or complex shape queries.

Physics Overlap Box Action

Queries all 3D colliders overlapping an oriented box volume at a point in time and stores results to the blackboard. The box size, position, and rotation can be target-relative or world-space. Perfect for 3D area-of-effect detection, zone queries, or proximity checks in rectangular volumes.

Physics Overlap Sphere Action

Detects all 3D colliders within a spherical volume and posts the results to the blackboard as a PhysicsQueryResult. The sphere center and radius support target-relative positioning with auto-expanding array options. Excellent for explosion radius queries, radial proximity detection, or 3D sensor volumes.

Physics Overlap Capsule Action

Queries all 3D colliders overlapping a capsule volume (cylinder with hemispherical ends) and stores results to the blackboard. The capsule endpoints, radius, and dimensions can be configured with target-relative positioning. Ideal for character-shaped volumes, cylindrical area queries, or pill-shaped proximity detection.

Other Physics Actions

Ignore Collision Action

Controls collision interactions between specific colliders or entire physics layers, with support for both 2D and 3D physics. Can enable or disable collisions between pairs of individual colliders (with support for lists and all-combinations mode) or set layer-to-layer collision rules. Perfect for runtime collision filtering, character-projectile exclusions, or dynamic physics interaction management.

Modify Physics Material Properties Action

Dynamically modifies physics material properties (friction, bounciness, combine modes) on colliders without replacing the material asset itself. Supports both 3D (PhysicMaterial) and 2D (PhysicsMaterial2D) colliders with selective property modification and automatic material creation if missing. Ideal for runtime surface behavior changes, dynamic friction adjustment, or bounce tuning based on game state.

Set Physics Material Action

Assigns a complete physics material asset to one or more colliders, replacing any existing material. Supports both 3D and 2D colliders with options to target specific colliders, the executor's target, or all child colliders. Great for swapping between predefined material presets, applying shared physics behaviors across multiple objects, or setting initial material configurations.