aibis-dream/Assets/Scripts/MiniGame/BlockPuzzle/Interface/IBlockPuzzleGrid.cs

using System.Collections.Generic;
using UnityEngine;

namespace AibisDream
{
    /// <summary>
    /// 网格单元格状态
    /// </summary>
    public enum GridCellState
    {
        Empty = 0,      // 空
        Occupied = 1,    // 已占用
        PreviewVaild = 2, // 预览有效
        PreviewInvalid = 3, // 预览无效
        OutOfBounds = 4   // 超出范围
    }

    /// <summary>
    /// 游戏网格系统接口（整个网格）
    /// 负责管理整个游戏网格的状态和操作，包括：
    /// - 网格的整体尺寸和配置
    /// - 所有单元格的状态管理
    /// - 坐标转换（世界坐标 ↔ 网格坐标）
    /// - 网格级别的操作（清空、统计等）
    /// 
    /// 注意：单个单元格（Cell）通过坐标访问，没有独立接口
    /// </summary>
    public interface IBlockPuzzleGrid
    {
        /// <summary>
        /// 网格宽度
        /// </summary>
        int Width { get; }

        /// <summary>
        /// 网格高度
        /// </summary>
        int Height { get; }

        /// <summary>
        /// 网格单元格大小（世界单位）
        /// </summary>
        float CellSize { get; }

        /// <summary>
        /// 网格原点位置（世界坐标）
        /// </summary>
        Vector3 Origin { get; }

        /// <summary>
        /// 网格可视化器
        /// </summary>
        GridVisualizer GridVisualizer { get; }

        /// <summary>
        /// 初始化网格
        /// </summary>
        /// <param name="width">宽度</param>
        /// <param name="height">高度</param>
        /// <param name="cellSize">单元格大小</param>
        void Initialize(int width, int height, float cellSize);

        /// <summary>
        /// 获取指定位置的单元格状态
        /// </summary>
        /// <param name="x">网格X坐标</param>
        /// <param name="y">网格Y坐标</param>
        /// <returns>单元格状态</returns>
        GridCellState GetCellState(int x, int y);

        /// <summary>
        /// 设置指定位置的单元格状态
        /// </summary>
        /// <param name="x">网格X坐标</param>
        /// <param name="y">网格Y坐标</param>
        /// <param name="state">单元格状态</param>
        void SetCellState(int x, int y, GridCellState state);

        /// <summary>
        /// 获取指定位置的预览单元格状态
        /// </summary>
        /// <param name="x">网格X坐标</param>
        /// <param name="y">网格Y坐标</param>
        /// <param name="state">单元格状态</param>
        GridCellState GetPreviewCellState(int x, int y);

        /// <summary>
        /// 设置指定位置的预览单元格状态
        /// </summary>
        /// <param name="x">网格X坐标</param>
        /// <param name="y">网格Y坐标</param>
        /// <param name="state">单元格状态</param>
        void SetPreviewCellState(int x, int y, GridCellState state);

        /// <summary>
        /// 重置预览网格
        /// </summary>
        void ResetPreviewGrid();

        /// <summary>
        /// 检查指定位置是否在网格范围内
        /// </summary>
        /// <param name="x">网格X坐标</param>
        /// <param name="y">网格Y坐标</param>
        /// <returns>是否在范围内</returns>
        bool IsValidPosition(int x, int y);

        /// <summary>
        /// 检查指定位置是否为空
        /// </summary>
        /// <param name="x">网格X坐标</param>
        /// <param name="y">网格Y坐标</param>
        /// <returns>是否为空</returns>
        bool IsCellEmpty(int x, int y);

        /// <summary>
        /// 检查指定位置是否可以放置
        /// </summary>
        /// <param name="gridCells">网格坐标数组</param>
        /// <param name="results">结果集合</param>
        /// <returns>是否可以放置</returns>
        bool CanPlace(Vector2Int[] gridCells);

        /// <summary>
        /// 世界坐标转换为网格坐标
        /// </summary>
        /// <param name="worldPos">世界坐标</param>
        /// <param name="gridX">输出的网格X坐标</param>
        /// <param name="gridY">输出的网格Y坐标</param>
        /// <returns>是否转换成功</returns>
        bool WorldToGrid(Vector3 worldPos, out int gridX, out int gridY);

        /// <summary>
        /// 网格坐标转换为世界坐标
        /// </summary>
        /// <param name="gridX">网格X坐标</param>
        /// <param name="gridY">网格Y坐标</param>
        /// <returns>世界坐标</returns>
        Vector3 GridToWorld(int gridX, int gridY);

        /// <summary>
        /// 清空整个网格
        /// </summary>
        void Clear();

        /// <summary>
        /// 获取已占用的单元格数量
        /// </summary>
        /// <returns>已占用的单元格数量</returns>
        int GetOccupiedCount();

        /// <summary>
        /// 获取总单元格数量
        /// </summary>
        /// <returns>总单元格数量</returns>
        int GetTotalCellCount();

        /// <summary>
        /// 获取网格顶点信息
        /// </summary>
        /// <returns>网格四个顶点位置</returns>
        Vector3[] GridVerticesToWorld(int x, int y);

        /// <summary>
        /// 形状字典, 保存置入网格的形状及其根网格坐标
        /// </summary>
        /// <returns>形状字典</returns>
        Dictionary<BlockShape, GridShapeData> ShapeDict { get; }

        /// <summary>
        /// 获取当前所有的Shapes
        /// </summary>
        /// <returns>所有的Shapes</returns>
        List<BlockShape> GetShapes();
    }
}