feat: expose block state properties through MCP

MinecraftClient/Mapping/BlockPalettes/BlockPalette.cs

@@ -1,4 +1,5 @@
-using System.Collections.Generic;
+using System;
+using System.Collections.Generic;
 
 namespace MinecraftClient.Mapping.BlockPalettes
 {
@@ -23,6 +24,46 @@ namespace MinecraftClient.Mapping.BlockPalettes
             return Material.Air;
         }
 
+        /// <summary>
+        /// Get block-state properties for a modern block state ID.
+        /// </summary>
+        /// <param name="stateId">Raw block state ID.</param>
+        /// <returns>Block-state property names and values, or an empty map when unavailable.</returns>
+        public IReadOnlyDictionary<string, string> GetStateProperties(int stateId)
+        {
+            BlockStateDefinition[] definitions = GetStateDefinitions();
+            int low = 0;
+            int high = definitions.Length - 1;
+
+            while (low <= high)
+            {
+                int middle = low + ((high - low) / 2);
+                BlockStateDefinition definition = definitions[middle];
+                if (stateId < definition.FirstStateId)
+                {
+                    high = middle - 1;
+                }
+                else if (stateId > definition.LastStateId)
+                {
+                    low = middle + 1;
+                }
+                else
+                {
+                    return definition.GetProperties(stateId);
+                }
+            }
+
+            return BlockStateDefinition.EmptyProperties;
+        }
+
+        /// <summary>
+        /// Get compact block-state definitions sorted by their first state ID.
+        /// </summary>
+        protected virtual BlockStateDefinition[] GetStateDefinitions()
+        {
+            return Array.Empty<BlockStateDefinition>();
+        }
+
         /// <summary>
         /// Returns TRUE if block ID uses old metadata encoding with ID and Meta inside one ushort
         /// Only Palette112 should override this.

MinecraftClient/Mapping/BlockPalettes/BlockStateDefinition.cs

@@ -0,0 +1,71 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+
+namespace MinecraftClient.Mapping.BlockPalettes
+{
+    /// <summary>
+    /// Compact description of the property combinations in a contiguous block-state range.
+    /// </summary>
+    public sealed class BlockStateDefinition
+    {
+        private static readonly IReadOnlyDictionary<string, string> s_emptyProperties =
+            new ReadOnlyDictionary<string, string>(new Dictionary<string, string>());
+
+        private readonly BlockStatePropertyDefinition[] _properties;
+        public int FirstStateId { get; }
+        public int LastStateId { get; }
+        public static IReadOnlyDictionary<string, string> EmptyProperties => s_emptyProperties;
+
+        public BlockStateDefinition(int firstStateId, int stateCount, BlockStatePropertyDefinition[] properties)
+        {
+            ArgumentOutOfRangeException.ThrowIfNegative(firstStateId);
+            ArgumentOutOfRangeException.ThrowIfNegativeOrZero(stateCount);
+            ArgumentNullException.ThrowIfNull(properties);
+
+            FirstStateId = firstStateId;
+            LastStateId = checked(firstStateId + stateCount - 1);
+            _properties = properties;
+        }
+
+        public IReadOnlyDictionary<string, string> GetProperties(int stateId)
+        {
+            if (stateId < FirstStateId || stateId > LastStateId)
+                return EmptyProperties;
+
+            int offset = stateId - FirstStateId;
+            Dictionary<string, string> result = new(_properties.Length, StringComparer.Ordinal);
+            for (int i = 0; i < _properties.Length; i++)
+            {
+                BlockStatePropertyDefinition property = _properties[i];
+                int valueIndex = (offset / property.Stride) % property.Values.Length;
+                result[property.Name] = property.Values[valueIndex];
+            }
+
+            return result;
+        }
+    }
+
+    /// <summary>
+    /// Property name and its values in Minecraft's block-state iteration order.
+    /// </summary>
+    public sealed class BlockStatePropertyDefinition
+    {
+        public string Name { get; }
+        public string[] Values { get; }
+        public int Stride { get; }
+
+        public BlockStatePropertyDefinition(string name, string[] values, int stride)
+        {
+            ArgumentException.ThrowIfNullOrEmpty(name);
+            ArgumentNullException.ThrowIfNull(values);
+            if (values.Length == 0)
+                throw new ArgumentException("A block-state property must define at least one value.", nameof(values));
+            ArgumentOutOfRangeException.ThrowIfNegativeOrZero(stride);
+
+            Name = name;
+            Values = values;
+            Stride = stride;
+        }
+    }
+}