feat: expose block state properties through MCP

MinecraftClient.Tests/BlockStatePropertiesTests.cs

@@ -0,0 +1,43 @@
+using MinecraftClient.Mapping.BlockPalettes;
+
+namespace MinecraftClient.Tests;
+
+public sealed class BlockStatePropertiesTests
+{
+    private readonly Palette262 _palette = new();
+
+    [Theory]
+    [InlineData(32162, "north", "true", "inactive")]
+    [InlineData(32168, "north", "false", "unlocking")]
+    [InlineData(32193, "east", "false", "ejecting")]
+    public void VaultStatesExposeAllProperties(
+        int stateId,
+        string facing,
+        string ominous,
+        string vaultState)
+    {
+        IReadOnlyDictionary<string, string> properties = _palette.GetStateProperties(stateId);
+
+        Assert.Equal(facing, properties["facing"]);
+        Assert.Equal(ominous, properties["ominous"]);
+        Assert.Equal(vaultState, properties["vault_state"]);
+    }
+
+    [Fact]
+    public void PropertiesUseServerReportedStateStride()
+    {
+        IReadOnlyDictionary<string, string> properties = _palette.GetStateProperties(3989);
+
+        Assert.Equal("left", properties["type"]);
+        Assert.Equal("north", properties["facing"]);
+        Assert.Equal("true", properties["waterlogged"]);
+    }
+
+    [Fact]
+    public void StateWithoutPropertiesReturnsEmptyMap()
+    {
+        IReadOnlyDictionary<string, string> properties = _palette.GetStateProperties(1);
+
+        Assert.Empty(properties);
+    }
+}

MinecraftClient/Mapping/Block.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.Runtime.CompilerServices;
 using MinecraftClient.Mapping.BlockPalettes;
 using MinecraftClient.Protocol.Message;
@@ -78,6 +79,19 @@ namespace MinecraftClient.Mapping
             }
         }
 
+        /// <summary>
+        /// Exact raw block state ID. For Minecraft 1.12 and older this contains the packed block ID and metadata.
+        /// </summary>
+        public int StateId => blockIdAndMeta;
+
+        /// <summary>
+        /// Get the properties associated with this block's exact state ID.
+        /// </summary>
+        public IReadOnlyDictionary<string, string> GetStateProperties()
+        {
+            return Palette.GetStateProperties(StateId);
+        }
+
         /// <summary>
         /// Material of the block
         /// </summary>

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;
+        }
+    }
+}

MinecraftClient/Mcp/MccMcpCapabilities.cs

@@ -1090,6 +1090,8 @@ public sealed class MccMcpCapabilities : IMccMcpCapabilities
                             typeLabel,
                             blockId = block.BlockId,
                             blockMeta = block.BlockMeta,
+                            stateId = block.StateId,
+                            properties = block.GetStateProperties(),
                             distance = Math.Sqrt(dx * dx + dy * dy + dz * dz)
                         });
                     }
@@ -1139,7 +1141,7 @@ public sealed class MccMcpCapabilities : IMccMcpCapabilities
             int cy = (int)Math.Floor(playerLocation.Y) - 1;
             int cz = (int)Math.Floor(playerLocation.Z);
 
-            List<(int x, int y, int z, string material, string typeLabel, int blockId, byte blockMeta, double distance)> found = new();
+            List<(int x, int y, int z, string material, string typeLabel, int blockId, byte blockMeta, int stateId, IReadOnlyDictionary<string, string> properties, double distance)> found = new();
             World world = client.GetWorld();
 
             for (int y = cy - radius; y <= cy + radius && found.Count < limit; y++)
@@ -1167,6 +1169,8 @@ public sealed class MccMcpCapabilities : IMccMcpCapabilities
                             block.GetTypeString(),
                             block.BlockId,
                             block.BlockMeta,
+                            block.StateId,
+                            block.GetStateProperties(),
                             Math.Sqrt(dx * dx + dy * dy + dz * dz)));
                     }
                 }
@@ -1190,6 +1194,8 @@ public sealed class MccMcpCapabilities : IMccMcpCapabilities
                         entry.typeLabel,
                         entry.blockId,
                         entry.blockMeta,
+                        entry.stateId,
+                        entry.properties,
                         entry.distance
                     })
                     .ToArray()
@@ -1853,7 +1859,9 @@ public sealed class MccMcpCapabilities : IMccMcpCapabilities
                 z,
                 material = block.Type.ToString(),
                 blockId = block.BlockId,
-                blockMeta = block.BlockMeta
+                blockMeta = block.BlockMeta,
+                stateId = block.StateId,
+                properties = block.GetStateProperties()
             });
         });
     }
@@ -3121,7 +3129,9 @@ public sealed class MccMcpCapabilities : IMccMcpCapabilities
             material = block.Type.ToString(),
             typeLabel = block.GetTypeString(),
             blockId = block.BlockId,
-            blockMeta = block.BlockMeta
+            blockMeta = block.BlockMeta,
+            stateId = block.StateId,
+            properties = block.GetStateProperties()
         };
     }
 

MinecraftClient/Scripting/MccGameCommon.cs

@@ -26,6 +26,8 @@ public sealed class MccBlockStateSnapshot
     public required string TypeLabel { get; init; }
     public required int BlockId { get; init; }
     public required int BlockMeta { get; init; }
+    public required int StateId { get; init; }
+    public required IReadOnlyDictionary<string, string> Properties { get; init; }
 }
 
 /// <summary>
@@ -143,7 +145,9 @@ public static class MccGameCommon
             Material = block.Type.ToString(),
             TypeLabel = block.GetTypeString(),
             BlockId = block.BlockId,
-            BlockMeta = block.BlockMeta
+            BlockMeta = block.BlockMeta,
+            StateId = block.StateId,
+            Properties = block.GetStateProperties()
         };
     }
 

tools/gen_block_palette.py

@@ -14,6 +14,7 @@ Example:
 """
 
 import json
+import math
 import re
 import sys
 from pathlib import Path
@@ -40,6 +41,54 @@ def load_known_materials() -> set[str]:
     return known
 
 
+def get_state_property_definitions(
+    block_key: str,
+    states: list[dict],
+    properties: dict[str, list[str]],
+) -> list[tuple[str, list[str], int]]:
+    """Build and verify the compact stride schema against every reported state."""
+    if not properties:
+        return []
+
+    ordered_states = sorted(states, key=lambda state: state["id"])
+    first_state_id = ordered_states[0]["id"]
+    expected_ids = list(range(first_state_id, first_state_id + len(ordered_states)))
+    actual_ids = [state["id"] for state in ordered_states]
+    if actual_ids != expected_ids:
+        raise ValueError(f"{block_key} has non-contiguous state IDs")
+
+    expected_count = math.prod(len(values) for values in properties.values())
+    if expected_count != len(ordered_states):
+        raise ValueError(
+            f"{block_key} has {len(ordered_states)} states but its properties describe {expected_count} combinations"
+        )
+
+    definitions = []
+    for name, values in properties.items():
+        stride = next(
+            (
+                candidate
+                for candidate in range(1, len(ordered_states) + 1)
+                if all(
+                    state.get("properties", {}).get(name)
+                    == values[(offset // candidate) % len(values)]
+                    for offset, state in enumerate(ordered_states)
+                )
+            ),
+            None,
+        )
+        if stride is None:
+            raise ValueError(f"{block_key} property {name} has no regular state stride")
+        definitions.append((name, values, stride))
+
+    return definitions
+
+
+def csharp_string(value: str) -> str:
+    """Encode a Python string as a compatible C# string literal."""
+    return json.dumps(value, ensure_ascii=False)
+
+
 def main():
     if len(sys.argv) != 3:
         print(__doc__)
@@ -55,14 +104,15 @@ def main():
     with open(blocks_json) as f:
         data = json.load(f)
 
-    # Build (min_state, max_state, cs_name) for each block, sorted by min_state
+    # Build block ranges and compact state-property definitions, sorted by min state.
     block_ranges = []
     for block_key, block_info in data.items():
         cs_name = mc_name_to_csharp(block_key)
         states = block_info.get("states", [])
         state_ids = [s["id"] for s in states]
         if state_ids:
-            block_ranges.append((min(state_ids), max(state_ids), cs_name))
+            properties = get_state_property_definitions(block_key, states, block_info.get("properties", {}))
+            block_ranges.append((min(state_ids), max(state_ids), cs_name, properties))
 
     block_ranges.sort(key=lambda x: x[0])
     print(f"Loaded {len(block_ranges)} blocks from {blocks_json}")
@@ -71,7 +121,7 @@ def main():
     print(f"State ID range: 0 - {max_state}")
 
     known_materials = load_known_materials()
-    missing = [cs for _, _, cs in block_ranges if known_materials and cs not in known_materials]
+    missing = [cs for _, _, cs, _ in block_ranges if known_materials and cs not in known_materials]
     if missing:
         print(f"\nWARNING: {len(missing)} blocks not found in Material.cs enum:")
         for cs_name in missing:
@@ -95,24 +145,54 @@ def main():
         "        {",
     ]
 
-    for min_s, max_s, cs_name in block_ranges:
+    for min_s, max_s, cs_name, _ in block_ranges:
         lines.append(f"            for (int i = {min_s}; i <= {max_s}; i++)")
         lines.append(f"                materials[i] = Material.{cs_name};")
 
     lines += [
         "        }",
         "",
+        "        private static readonly BlockStateDefinition[] stateDefinitions =",
+        "        [",
+    ]
+
+    property_definition_count = 0
+    for min_s, max_s, _, properties in block_ranges:
+        if not properties:
+            continue
+
+        property_definition_count += 1
+        lines.append(f"            new({min_s}, {max_s - min_s + 1},")
+        lines.append("            [")
+        property_items = properties
+        for index, (name, values, stride) in enumerate(property_items):
+            encoded_values = ", ".join(csharp_string(value) for value in values)
+            suffix = "," if index < len(property_items) - 1 else ""
+            lines.append(f"                new({csharp_string(name)}, [{encoded_values}], {stride}){suffix}")
+        lines.append("            ]),")
+
+    lines += [
+        "        ];",
+        "",
         "        protected override Dictionary<int, Material> GetDict()",
         "        {",
         "            return materials;",
         "        }",
+        "",
+        "        protected override BlockStateDefinition[] GetStateDefinitions()",
+        "        {",
+        "            return stateDefinitions;",
+        "        }",
         "    }",
         "}",
         "",
     ]
 
     output_path.write_text("\n".join(lines))
-    print(f"Generated {output_path} with {len(block_ranges)} blocks ({max_state + 1} total states)")
+    print(
+        f"Generated {output_path} with {len(block_ranges)} blocks, "
+        f"{max_state + 1} total states, and {property_definition_count} property definitions"
+    )
 
 
 if __name__ == "__main__":