NavMesh Actions

v1.0

NavMesh Query Result

NavMeshQueryResult is a unified result container for all NavMesh query operations in Juicy Actions. All NavMesh query actions which post to the Blackboard store this object making it easy to retrieve and use NavMesh query data from other actions or scripts.

This is a serializable data container for NavMesh query results storing success status, positions, normals, distances, NavMeshHit data, path information, and corner lists. Provides unified storage format for all NavMesh query actions and includes helper methods to populate from sample, raycast, path, or edge operations.

[System.Serializable]
public class NavMeshQueryResult
{
    // Query success/failure
    public bool success;              // True if operation succeeded
    
    // Hit/sample data
    public Vector3 position;          // Hit/sample/edge position
    public Vector3 normal;            // Surface normal at hit point
    public float distance;            // Distance to hit/edge
    public int areaMask;              // NavMesh area mask
    public NavMeshHit hit;            // Full Unity NavMeshHit data
    
    // Path-specific data (only for CalculatePath)
    public NavMeshPath path;          // The calculated path
    public List<Vector3> pathCorners; // Convenient list of path corners
}

Using the NavMeshQueryResult Data

Retrieve Blackboard Data

You can retrieve this data from the Executor or global Blackboard via script:

using MagicPigGames.JuicyActions;
using UnityEngine;

public class MyAIController : MonoBehaviour
{
    [SerializeField] private ActionExecutor executor;
    
    void CheckNavMeshPath()
    {
        // Retrieve the result from blackboard
        var result = executor.Blackboard.Get<NavMeshQueryResult>("NavMesh/PathResult");
        
        if (result == null)
        {
            Debug.LogWarning("No path result found in blackboard");
            return;
        }
        
        if (result.success)
        {
            Debug.Log($"Path found with {result.pathCorners.Count} waypoints");
            
            // Use the path
            foreach (var corner in result.pathCorners)
                Debug.DrawLine(transform.position, corner, Color.green, 2f);
        }
        else
            Debug.Log("No valid path exists");
    }
}

Chain Actions Together

You can also chain Actions together using the Blackboard keys.

1. NavMesh Calculate Path → Stores to "NavMesh/PathResult"

2. Custom Action → Reads from "NavMesh/PathResult" and uses path data

In your custom action:

protected override IEnumerator ExecuteInternal()
{
    var pathResult = Executor.Blackboard.Get<NavMeshQueryResult>("NavMesh/PathResult");
    
    if (pathResult != null && pathResult.success)
    {
        // Navigate along the path
        foreach (var waypoint in pathResult.pathCorners)
            yield return MoveToWaypoint(waypoint);
    }
    else
        LogWarning("No valid path available in blackboard");
}

Practical Example

Example: NavMesh Calculate Path

• Start: useExecutorTargetAsStart = true

• End: endTransform = Player

• Result Key: "AI/PathToPlayer"

• Store To Global: false

public class EnemyAI : MonoBehaviour
{
    [SerializeField] private ActionExecutor executor;
    [SerializeField] private float moveSpeed = 3f;
    
    public void ChasePlayer()
    {
        // ActionExecutor runs "NavMesh Calculate Path" action
        executor.Execute();
        
        // You could also call this from the ActionExecutor via the TriggerUnityEventAction
        // and a "StartCoroutine" method.
        StartCoroutine(FollowPath());
    }
    
    IEnumerator FollowPath()
    {
        yield return new WaitForSeconds(0.1f); // Wait for action to complete
        
        var pathResult = executor.Blackboard.Get<NavMeshQueryResult>("AI/PathToPlayer");
        
        if (pathResult == null || !pathResult.success)
        {
            Debug.Log("No path to player");
            yield break;
        }
        
        // Follow each waypoint
        foreach (var waypoint in pathResult.pathCorners)
        {
            while (Vector3.Distance(transform.position, waypoint) > 0.5f)
            {
                transform.position = Vector3.MoveTowards(
                    transform.position, 
                    waypoint, 
                    moveSpeed * Time.deltaTime
                );
                yield return null;
            }
        }
        
        Debug.Log("Reached player!");
    }
}

Example: NavMesh Raycast

• Start: useExecutorTargetAsStart = true (enemy)

• End: useExecutorTargetAsEnd = true (player)

• Result Key: "AI/LineOfSight"

• Also Store Hit: true

• Hit Key: "AI/HasObstacle"

public class VisionSystem : MonoBehaviour
{
    [SerializeField] private ActionExecutor executor;
    
    public bool HasClearLineOfSight()
    {
        executor.Execute(); // Runs NavMesh Raycast, maybe with additional JUICE
        
        // If raycast hit something, there's an obstacle
        bool hasObstacle = executor.Blackboard.Get<bool>("AI/HasObstacle");
        
        if (!hasObstacle)
            return true; // Clear line of sight
        
        // Check what was hit
        var result = executor.Blackboard.Get<NavMeshQueryResult>("AI/LineOfSight");
        
        Debug.Log($"NavMesh obstacle at {result.position}");
        Debug.Log($"Distance to obstacle: {result.distance}");
        
        return false;
    }
}

Blackboard Posting Actions

These Actions will post results to the executor or global Blackboard.

NavMesh Calculate Path Action

Calculates a NavMesh path between two positions (Vector3, Transform, or executor target) and stores the result with path corners, success status, and optional corner count to the Blackboard. Supports configurable area masks for multi-layer NavMesh setups. Essential for AI pathfinding validation, path visualization, pre-calculated routes, or movement cost estimation before committing to navigation.

NavMesh Sample Position Action

Samples the closest valid NavMesh position within a maximum distance from a source point, storing the result to the blackboard with configurable area masks. Critical for snapping arbitrary positions to walkable surfaces, spawn point validation, object placement on NavMesh, or recovering agents from off-mesh positions.

NavMesh Raycast Action

Performs a NavMesh raycast between two positions to detect obstructions or line-of-sight on the navigation mesh, storing hit results and boolean success to the Blackboard. Perfect for AI line-of-sight checks on walkable surfaces, navigation-aware cover detection, or validating direct paths before agent movement.

NavMesh Find Closest Edge Action

Finds the nearest NavMesh edge from a source position and stores hit data including edge position, normal, and distance to the blackboard. Useful for boundary detection, wall avoidance systems, edge-aware AI behavior, or identifying navigation mesh limits for procedural content placement.

NavMeshAgent Actions

Set NavMeshAgent Avoidance Priority Action

Sets the avoidance priority (0-99, lower values have higher priority) for NavMeshAgents to control which agents yield during collision avoidance. Supports target selection modes (random/sequential) with fallback to executor target and optional child inclusion. Use this to establish agent hierarchy for crowded navigation scenarios.

Set NavMeshAgent Destination Action

Commands NavMeshAgents to navigate to a destination (Vector3, Transform, or executor target) with optional auto-resume if the agent was previously stopped. Supports flexible target selection with random/sequential modes and batch application to multiple agents. The primary action for AI movement and pathfinding-driven gameplay.

Set NavMeshAgent Speed Action

Animates NavMeshAgent movement speed (and optionally acceleration and angular speed) over time with curve-based interpolation and automatic base value restoration. Extends ActionOverTimeWithBaseValues with per-agent Blackboard state management and proper cleanup on cancel/restart. Perfect for dynamic AI behavior, temporary speed boosts, slow-motion effects, or state-based locomotion changes.

Stop NavMeshAgent Action

Immediately stops or resumes NavMeshAgent movement with optional path reset to clear current navigation data. Supports target selection modes for controlling single, random, sequential, or all agents in a list. Essential for pausing AI, implementing idle states, or canceling ongoing navigation commands.

Warp NavMeshAgent Action

Instantly teleports NavMeshAgents to a target position (Vector3, Transform, or executor target) without pathfinding or animation. Supports flexible target selection modes and batch warping of multiple agents. Use this for cutscenes, spawn systems, level transitions, or repositioning agents without navigation.