add documentation

Assets/Features/VoxelWorld/Contracts/NavMeshWorldContracts.cs

@@ -3,34 +3,88 @@ using UnityEngine;
 
 namespace InfiniteWorld.VoxelWorld.Contracts
 {
+    /// <summary>
+    /// Provides chunk-level nav build inputs without exposing the internal runtime representation of the voxel world.
+    /// </summary>
     public interface IChunkNavSourceReader
     {
+        /// <summary>
+        /// Returns the world-space edge length of one chunk so nav coverage and source collection can reason in chunk units.
+        /// </summary>
         float ChunkWorldSize { get; }
+
+        /// <summary>
+        /// Copies the coordinates of chunks that currently have usable nav geometry into the provided list.
+        /// </summary>
         void GetLoadedChunkCoords(List<Vector2Int> results);
+
+        /// <summary>
+        /// Retrieves the current nav source snapshot for a loaded chunk so sidecar systems can rebuild coverage from stable descriptors.
+        /// </summary>
         bool TryGetChunkNavSourceSnapshot(Vector2Int coord, out ChunkNavSourceSnapshot snapshot);
     }
 
+    /// <summary>
+    /// Exposes the current gameplay-relevant interest points that should influence world streaming or nav coverage planning.
+    /// </summary>
     public interface IWorldInterestReader
     {
+        /// <summary>
+        /// Increments when the logical set of interest points changes and downstream systems should invalidate cached plans.
+        /// </summary>
         int InterestVersion { get; }
+
+        /// <summary>
+        /// Appends the currently active interest points into the provided list.
+        /// </summary>
         void GetInterestPoints(List<WorldInterestPoint> results);
     }
 
+    /// <summary>
+    /// Exposes the currently built nav coverage so gameplay systems can query whether a world-space area is ready for pathing.
+    /// </summary>
     public interface INavCoverageReader
     {
+        /// <summary>
+        /// Returns whether the supplied world position lies inside ready nav coverage, not merely inside generated terrain.
+        /// </summary>
         bool IsPositionCovered(Vector3 worldPosition);
+
+        /// <summary>
+        /// Copies the currently active coverage windows so diagnostics and higher-level systems can inspect the coverage topology.
+        /// </summary>
         void GetCoverageWindows(List<NavCoverageWindowSnapshot> results);
     }
 
+    /// <summary>
+    /// Lets callers inject short-lived route hints that bias nav coverage planning toward an upcoming movement corridor.
+    /// </summary>
     public interface INavCoverageHintRegistry
     {
+        /// <summary>
+        /// Registers or refreshes a temporary linear hint for the given owner so coverage can prewarm along a route before pathing starts.
+        /// </summary>
         void SetLinearHint(int ownerId, Vector3 from, Vector3 to, float priority, float ttlSeconds);
+
+        /// <summary>
+        /// Removes the temporary hint owned by the caller when the route is no longer relevant.
+        /// </summary>
         void ClearHint(int ownerId);
     }
 
+    /// <summary>
+    /// Exposes the current set of transient nav coverage hints as read-only interest points for the nav coverage scheduler.
+    /// </summary>
     public interface INavCoverageHintReader
     {
+        /// <summary>
+        /// Increments whenever the effective hint set changes so dependent planners can invalidate cached coverage windows.
+        /// </summary>
         int HintVersion { get; }
+
+        /// <summary>
+        /// Appends the currently active transient hint points into the provided list.
+        /// </summary>
         void GetHintPoints(List<WorldInterestPoint> results);
     }
 }

Assets/Features/VoxelWorld/Contracts/NavMeshWorldEnums.cs

@@ -1,18 +1,38 @@
 namespace InfiniteWorld.VoxelWorld.Contracts
 {
+    /// <summary>
+    /// Identifies why a point contributes to nav coverage so planners and diagnostics can treat different sources appropriately.
+    /// </summary>
     public enum WorldInterestKind
     {
+        /// <summary>Coverage seeded by the current player-controlled actor.</summary>
         PlayerActor = 0,
+
+        /// <summary>Coverage seeded by an active NPC that still requires authoritative pathing.</summary>
         ActiveNpc = 1,
+
+        /// <summary>Coverage seeded by a spawn location that should be warm before actors start moving.</summary>
         SpawnAnchor = 2,
+
+        /// <summary>Coverage seeded by a short-lived route hint that biases planning ahead of movement.</summary>
         TransientNavHint = 3,
+
+        /// <summary>Fallback category for future interest sources that do not fit a more specific kind.</summary>
         Other = 4
     }
 
+    /// <summary>
+    /// Describes where a coverage window currently sits in the nav build lifecycle.
+    /// </summary>
     public enum NavCoverageState
     {
+        /// <summary>The window exists conceptually but still needs a fresh build.</summary>
         Pending = 0,
+
+        /// <summary>The window is currently rebuilding its runtime NavMesh data.</summary>
         Building = 1,
+
+        /// <summary>The window has ready NavMesh data that can answer pathing queries.</summary>
         Ready = 2
     }
 }

Assets/Features/VoxelWorld/Contracts/NavMeshWorldMessages.cs

@@ -2,6 +2,9 @@ using UnityEngine;
 
 namespace InfiniteWorld.VoxelWorld.Contracts
 {
+    /// <summary>
+    /// Signals that a chunk now has valid nav geometry and dependent coverage windows should invalidate cached builds.
+    /// </summary>
     public readonly struct ChunkNavGeometryReadyMessage
     {
         public ChunkNavGeometryReadyMessage(Vector2Int coord, int version)
@@ -10,10 +13,20 @@ namespace InfiniteWorld.VoxelWorld.Contracts
             Version = version;
         }
 
+        /// <summary>
+        /// Chunk coordinate whose nav geometry became available.
+        /// </summary>
         public Vector2Int Coord { get; }
+
+        /// <summary>
+        /// Version of the chunk runtime state associated with this notification.
+        /// </summary>
         public int Version { get; }
     }
 
+    /// <summary>
+    /// Signals that a chunk's nav geometry is being removed so dependent coverage windows can drop stale build data.
+    /// </summary>
     public readonly struct ChunkNavGeometryRemovedMessage
     {
         public ChunkNavGeometryRemovedMessage(Vector2Int coord, int version)
@@ -22,10 +35,20 @@ namespace InfiniteWorld.VoxelWorld.Contracts
             Version = version;
         }
 
+        /// <summary>
+        /// Chunk coordinate whose nav geometry is no longer available.
+        /// </summary>
         public Vector2Int Coord { get; }
+
+        /// <summary>
+        /// Last known version of the chunk state before removal.
+        /// </summary>
         public int Version { get; }
     }
 
+    /// <summary>
+    /// Invalidates consumers that cache the current world interest set.
+    /// </summary>
     public readonly struct WorldInterestChangedMessage
     {
         public WorldInterestChangedMessage(int version)
@@ -33,9 +56,15 @@ namespace InfiniteWorld.VoxelWorld.Contracts
             Version = version;
         }
 
+        /// <summary>
+        /// Monotonic version of the world interest state after the change.
+        /// </summary>
         public int Version { get; }
     }
 
+    /// <summary>
+    /// Invalidates consumers that cache transient nav coverage hints.
+    /// </summary>
     public readonly struct NavCoverageHintChangedMessage
     {
         public NavCoverageHintChangedMessage(int version)
@@ -43,6 +72,9 @@ namespace InfiniteWorld.VoxelWorld.Contracts
             Version = version;
         }
 
+        /// <summary>
+        /// Monotonic version of the active nav hint state after the change.
+        /// </summary>
         public int Version { get; }
     }
 }

Assets/Features/VoxelWorld/Contracts/NavMeshWorldSnapshots.cs

@@ -3,6 +3,9 @@ using UnityEngine.AI;
 
 namespace InfiniteWorld.VoxelWorld.Contracts
 {
+    /// <summary>
+    /// Captures the nav-relevant state of one chunk at a specific version so sidecar systems can rebuild from immutable inputs.
+    /// </summary>
     public readonly struct ChunkNavSourceSnapshot
     {
         public ChunkNavSourceSnapshot(Vector2Int coord, int version, ChunkNavBuildSourceDescriptor[] sources)
@@ -12,11 +15,25 @@ namespace InfiniteWorld.VoxelWorld.Contracts
             Sources = sources;
         }
 
+        /// <summary>
+        /// Chunk coordinate this snapshot was produced for.
+        /// </summary>
         public Vector2Int Coord { get; }
+
+        /// <summary>
+        /// Version of the chunk runtime state used to generate this snapshot.
+        /// </summary>
         public int Version { get; }
+
+        /// <summary>
+        /// Stable nav build descriptors derived from the chunk's current geometry.
+        /// </summary>
         public ChunkNavBuildSourceDescriptor[] Sources { get; }
     }
 
+    /// <summary>
+    /// Describes one build source in a format that can be consumed without direct references to world internals or scene scans.
+    /// </summary>
     public readonly struct ChunkNavBuildSourceDescriptor
     {
         public ChunkNavBuildSourceDescriptor(NavMeshBuildSourceShape shape, Matrix4x4 transform, Vector3 size, Mesh mesh, int area)
@@ -28,23 +45,51 @@ namespace InfiniteWorld.VoxelWorld.Contracts
             Area = area;
         }
 
+        /// <summary>
+        /// Unity NavMesh source shape represented by this descriptor.
+        /// </summary>
         public NavMeshBuildSourceShape Shape { get; }
+
+        /// <summary>
+        /// World transform used when the descriptor is converted into a runtime build source.
+        /// </summary>
         public Matrix4x4 Transform { get; }
+
+        /// <summary>
+        /// Source size for primitive shapes such as box-based ground coverage.
+        /// </summary>
         public Vector3 Size { get; }
+
+        /// <summary>
+        /// Source mesh for mesh-based obstacles or walkable surfaces when applicable.
+        /// </summary>
         public Mesh Mesh { get; }
+
+        /// <summary>
+        /// Nav area assigned to the resulting build source.
+        /// </summary>
         public int Area { get; }
 
+        /// <summary>
+        /// Creates a compact descriptor for box-based chunk geometry such as ground slabs.
+        /// </summary>
         public static ChunkNavBuildSourceDescriptor CreateBox(Matrix4x4 transform, Vector3 size, int area = 0)
         {
             return new ChunkNavBuildSourceDescriptor(NavMeshBuildSourceShape.Box, transform, size, null, area);
         }
 
+        /// <summary>
+        /// Creates a compact descriptor for mesh-based chunk geometry such as carved terrain or obstacles.
+        /// </summary>
         public static ChunkNavBuildSourceDescriptor CreateMesh(Matrix4x4 transform, Mesh mesh, int area = 0)
         {
             return new ChunkNavBuildSourceDescriptor(NavMeshBuildSourceShape.Mesh, transform, Vector3.zero, mesh, area);
         }
     }
 
+    /// <summary>
+    /// Represents one gameplay-driven point that should influence nav coverage planning and clustering.
+    /// </summary>
     public readonly struct WorldInterestPoint
     {
         public WorldInterestPoint(Vector3 position, float priority, WorldInterestKind kind)
@@ -54,11 +99,25 @@ namespace InfiniteWorld.VoxelWorld.Contracts
             Kind = kind;
         }
 
+        /// <summary>
+        /// World position the planner should consider when shaping coverage.
+        /// </summary>
         public Vector3 Position { get; }
+
+        /// <summary>
+        /// Relative weight used to prioritize coverage near more important interest points.
+        /// </summary>
         public float Priority { get; }
+
+        /// <summary>
+        /// Category of interest so diagnostics can distinguish players, spawn anchors, hints and future AI sources.
+        /// </summary>
         public WorldInterestKind Kind { get; }
     }
 
+    /// <summary>
+    /// Lightweight read-model snapshot describing one currently managed nav coverage window.
+    /// </summary>
     public readonly struct NavCoverageWindowSnapshot
     {
         public NavCoverageWindowSnapshot(int id, Bounds bounds, NavCoverageState state, int interestCount)
@@ -69,9 +128,24 @@ namespace InfiniteWorld.VoxelWorld.Contracts
             InterestCount = interestCount;
         }
 
+        /// <summary>
+        /// Stable runtime identifier of the coverage window.
+        /// </summary>
         public int Id { get; }
+
+        /// <summary>
+        /// World-space bounds the window currently covers for pathing readiness.
+        /// </summary>
         public Bounds Bounds { get; }
+
+        /// <summary>
+        /// Current lifecycle state of the window in the build scheduler.
+        /// </summary>
         public NavCoverageState State { get; }
+
+        /// <summary>
+        /// Number of interest points currently collapsed into this window.
+        /// </summary>
         public int InterestCount { get; }
     }
 }