From 778805a8d8a3ead8758cd19ee099611454821e1c Mon Sep 17 00:00:00 2001 From: Jonathan Coates Date: Tue, 16 Dec 2025 23:13:21 +0000 Subject: [PATCH] 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. --- doc/reference/block_details.md | 99 +++++++++++++++++++ .../shared/computer/apis/CommandAPI.java | 5 +- .../shared/turtle/apis/TurtleAPI.java | 11 ++- projects/web/src/frontend/index.tsx | 1 + 4 files changed, 109 insertions(+), 7 deletions(-) create mode 100644 doc/reference/block_details.md diff --git a/doc/reference/block_details.md b/doc/reference/block_details.md new file mode 100644 index 000000000..7198a82a3 --- /dev/null +++ b/doc/reference/block_details.md @@ -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. +--- + + + +# 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" diff --git a/projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java b/projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java index 10b937237..9d4d831fd 100644 --- a/projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java +++ b/projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java @@ -247,9 +247,8 @@ public class CommandAPI implements ILuaAPI { /** * Get some basic information about a block. *

- * 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. diff --git a/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java b/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java index 7774ef500..76250fa2f 100644 --- a/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java +++ b/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java @@ -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 

{@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() {
diff --git a/projects/web/src/frontend/index.tsx b/projects/web/src/frontend/index.tsx
index 71172b917..19b4662c4 100644
--- a/projects/web/src/frontend/index.tsx
+++ b/projects/web/src/frontend/index.tsx
@@ -76,6 +76,7 @@ class Window extends Component {
         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;