Skip to content

debug-visualizer-requirements.md

Latest commit

 

History

History
71 lines (52 loc) · 4.82 KB

debug-visualizer-requirements.md

File metadata and controls

71 lines (52 loc) · 4.82 KB
Raw

AgentDebugVisualizer Requirements in Unity

Objective

The AgentDebugVisualizer in Unity is intended to provide developers and designers with clear, real-time insights into the behavior of agents and the state of the simulation. Its primary purpose is to aid in debugging, understanding complex agent interactions, and validating the C++ core's outputs within the Unity editor environment.

Key Information to Visualize

The AgentDebugVisualizer should be capable of presenting the following categories of information:

1. Agent-Specific Data

  • Position & Rotation: Visual representation of each agent's current location and orientation.
  • Agent ID: A unique identifier displayed near the agent.
  • Current FSM State: The active state of an agent's Finite State Machine (e.g., IDLE, WANDERING, PURSUING_GOAL).
  • Current Goal: The agent's immediate or long-term objective (e.g., GATHER_WOOD, REACH_TARGET).
  • Active Action/Plan: The current action an agent is executing or the sequence of actions in its GOAP plan.
  • Perception Cone/Radius: Visualization of an agent's sensory range or field of view.
  • Health/Resources: Basic stats for agents.

2. World State Data

  • World Objects:
    • Positions and types of WorldObject instances (e.g., trees, rocks, food sources).
    • Interactive status (e.g., highlight if interactable).
  • World Events:
    • Location and type of WorldEvent instances (e.g., sound events, danger zones).
    • Severity/Radius of influence.
  • Navigation Mesh/Paths (Future):
    • Overlay of the navigable areas.
    • Visualization of agent-specific computed paths.
  • Dynamic Obstacles: Displaying runtime-generated or movable obstacles.

3. Simulation Debug Data

  • Level of Detail (LOD) Status: Visual indication of which LOD tier an agent or a group of agents is currently in.
  • Multithreading Activity (Future): Simple indicators of worker thread load, job queue status, or thread contention hotspots.
  • Performance Metrics: Basic display of key performance indicators from the C++ profiling hooks (e.g., frame time, GOAP planning duration).
  • Agent Spawning/Despawning: Visual cues for agent lifecycle events.

Presentation Methods within Unity Editor

The AgentDebugVisualizer will utilize a combination of Unity's built-in debugging features and custom UI elements for effective presentation:

  1. Unity Gizmos (Editor-Only):

    • Agent Representation: Draw wire spheres, cubes, or custom icons at agent positions. Use different colors to indicate FSM state or LOD.
    • Direction/Orientation: Draw lines or arrows to represent agent forward direction/rotation.
    • Goals/Targets: Draw lines from agents to their current goal targets.
    • World Objects/Events: Draw icons or wire shapes at the locations of world objects and events.
    • Paths: Visualize agent paths as lines or sequences of points.
    • Perception: Draw wire spheres or cones representing perception ranges.

  2. On-Screen UI / Handles GUI (Runtime & Editor):

    • Agent Selection Details: When an agent GameObject is selected, display its detailed properties (FSM state, goal, action, debug values) in a custom Inspector window or as an overlay.
    • Global Simulation Stats: Display overall simulation performance metrics, active agent count, etc., as an overlay.
    • Toggles: UI elements to enable/disable specific visualizations (e.g., "Show Agent Paths," "Show Perception Cones").

  3. Colored Overlays & Shaders:

    • Use temporary materials or post-processing effects to highlight areas (e.g., "danger zones," "resource hotspots") or color-code agents based on their type or state.

  4. Custom Editor Windows (Advanced):

    • For highly complex data, such as visualizing the GOAP plan graph or detailed FSM transitions, a dedicated custom editor window might be considered to provide a more interactive and comprehensive view.

Integration Considerations

  • Performance: The visualizer itself must be performant, especially for large agent counts, to avoid impacting the simulation's performance during debugging. Many visualizations should be editor-only.
  • Configurability: Provide options to toggle different visualization elements on/off to reduce visual clutter.
  • Extensibility: Design the visualizer to be easily extensible for adding new debug information as the simulation core evolves.
  • C# to C++ Data Transfer: The necessary debug data will be marshaled from the C++ core to C# via the UnityAdapter (e.g., GetAgentDebugData(agentId) or a consolidated GetAllAgentDebugData()).

This initial sketch lays the groundwork for developing a robust and informative AgentDebugVisualizer crucial for iterating on agent behaviors and optimizing simulation performance.