Add reference for block details

I do not like the flow of this page, but did not know how better to structure it. We really need a way to write things which use the same type syntax as parameters. I don't like how this (and events!) are formatted so differently. It'll do for now though.
2026-06-02 19:02:07 +00:00 · 2025-12-16 23:13:21 +00:00
parent f31d8febbf
commit 778805a8d8
4 changed files with 109 additions and 7 deletions
@@ -0,0 +1,99 @@
+---
+module: [kind=reference] block_details
+since: 1.64
+changed: 1.76 Added block state.
+changed: 1.117.0 Added map colour.
+---
+
+<!--
+SPDX-FileCopyrightText: 2025 The CC: Tweaked Developers
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# Block details
+Several functions in CC: Tweaked, such as [`turtle.inspect`] and [`commands.getBlockInfo`] provide a way to get
+information about a block in the world. This page details information about blocks that CC: Tweaked may return.
+
+## Basic information
+Block information will *always* contain:
+ - `name: string`: The namespaced ID for this block, e.g. `minecraft:dirt`. See [this page][block ids] for a full list
+   of vanilla block IDS.
+ - `state: { [string] = any}`: A table containing the block state of the block.
+
+### Example
+A fully hydrated block of farmland:
+
+```lua {data-no-run=1}
+{
+    name = "minecraft:farmland",
+    state = {
+        moisture = 7
+    }
+}
+```
+
+An extended piston, facing upwards:
+
+```lua {data-no-run=1}
+{
+    name = "minecraft:piston",
+    state = {
+        facing = "up",
+        extended = true
+    }
+}
+```
+
+## Block tags
+The [tags][block tags] a block has.
+
+ - `tags: { [string] = boolean }`: The set of tags for this block. This is a mapping of tag name to `true`.
+
+While the representation of tags is a little more complicated then a single list, this makes it very easy to check if a
+block has a certain tag:
+
+```lua
+--- Check if the block in front of the turtle is a log.
+local function is_log()
+    local ok, block = turtle.inspect()
+    return ok and block.tags["minecraft:logs"]
+end
+```
+
+### Example
+A fully hydrated block of farmland:
+
+```lua {data-no-run=1}
+{
+    name = "minecraft:farmland",
+    state = { ... },
+    tags = {
+        ["minecraft:mineable/shovel"] = true,
+    }
+}
+```
+
+## Map colour
+The colour the block will appear on the map, if specified.
+
+ - `mapColour?: number`: The colour of the block, as an RGB hex value.
+ - `mapColor?: number`: The color of the block, as an RGB hex value.
+
+The map colour is just returned as a plain number (e.g. `9923917` for farmland). It can either be displayed in hex with
+[`string.format`], or converted to individual RGB values with [`colors.unpackRGB`].
+
+### Example
+A fully hydrated block of farmland:
+
+```lua {data-no-run=1}
+{
+    name = "minecraft:farmland",
+    state = { ... },
+    mapColour = 9923917,
+    mapColor = 9923917,
+}
+```
+
+[block ids]: https://minecraft.wiki/w/Java_Edition_data_values#Blocks "Java Edition data values on the Minecraft Wiki"
+[block tags]:https://minecraft.wiki/w/Block_tag_%28Java_Edition%29 "Block tags on the Minecraft Wiki"
@@ -247,9 +247,8 @@ public class CommandAPI implements ILuaAPI {
    /**
     * Get some basic information about a block.
     * <p>
-     * The returned table contains the current name, metadata and block state (as
-     * with [`turtle.inspect`]). If there is a block entity for that block, its NBT
-     * will also be returned.
+     * The returned table contains the the same information as listed in [`block_details`]. If there is a block entity
+     * for that block, its NBT will also be returned.
     *
     * @param x         The x position of the block to query.
     * @param y         The y position of the block to query.
@@ -721,13 +721,14 @@ public class TurtleAPI implements ILuaAPI {
    }

    /**
-     * Get information about the block in front of the turtle.
+     * Get [information about the block][`block_details`] in front of the turtle.
     *
     * @return The turtle command result.
     * @cc.treturn boolean Whether there is a block in front of the turtle.
     * @cc.treturn table|string Information about the block in front, or a message explaining that there is no block.
     * @cc.since 1.64
     * @cc.changed 1.76 Added block state to return value.
+     * @cc.see block_details
     * @cc.usage <pre>{@code
     * local has_block, data = turtle.inspect()
     * if has_block then
@@ -747,12 +748,13 @@ public class TurtleAPI implements ILuaAPI {
    }

    /**
-     * Get information about the block above the turtle.
+     * Get [information about the block][`block_details`] above the turtle.
     *
     * @return The turtle command result.
     * @cc.treturn boolean Whether there is a block above the turtle.
-     * @cc.treturn table|string Information about the above below, or a message explaining that there is no block.
+     * @cc.treturn table|string Information about the block above, or a message explaining that there is no block.
     * @cc.since 1.64
+     * @cc.see block_details
     */
    @LuaFunction
    public final MethodResult inspectUp() {
@@ -760,12 +762,13 @@ public class TurtleAPI implements ILuaAPI {
    }

    /**
-     * Get information about the block below the turtle.
+     * Get [information about the block][`block_details`] below the turtle.
     *
     * @return The turtle command result.
     * @cc.treturn boolean Whether there is a block below the turtle.
     * @cc.treturn table|string Information about the block below, or a message explaining that there is no block.
     * @cc.since 1.64
+     * @cc.see block_details
     */
    @LuaFunction
    public final MethodResult inspectDown() {
@@ -76,6 +76,7 @@ class Window extends Component<WindowProps, WindowState> {
        const elements = document.querySelectorAll("pre[data-lua-kind]");
        for (let i = 0; i < elements.length; i++) {
            const element = elements[i] as HTMLElement;
+            if (element.hasAttribute("data-no-run")) continue

            let example = element.innerText;