TheDeclineOfWarriors/Assets/Features/VoxelWorld/Contracts/NavMeshWorldSnapshots.cs

using UnityEngine;
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)
        {
            Coord = coord;
            Version = version;
            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)
        {
            Shape = shape;
            Transform = transform;
            Size = size;
            Mesh = mesh;
            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)
        {
            Position = position;
            Priority = priority;
            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)
        {
            Id = id;
            Bounds = bounds;
            State = state;
            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; }
    }
}