Skip to content

BlockEntity

Represents a block entity within the game world, such as a chest or furnace, containing additional data beyond a regular block.

Fields

name: string — Read-Only

The name identifier of the block entity.

nbt: table — Read/Write

A copy of the NBT (Named Binary Tag) data associated with the block entity, including custom data and metadata. Modifications to the table will not affect the actual block entity. To apply changes, either assign the modified table back (blockEntity.nbt = modifiedTable) or use putNbt(). Assigning a table replaces the whole NBT: keys the table omits are removed. To remove single values, use removeNbt(...).

Text components such as CustomName are tables in this Minecraft version, e.g. { text = "Grumpy Pig" }. Minecraft 1.21.4 and earlier used JSON strings ('{"text":"Grumpy Pig"}'). Written here, such a string is taken as literal text, without an error.

pos: Vec3 — Read-Only

A copy of the position of the block entity within the world.

type: BlockEntityType — Read-Only

A reference to the specific type of block entity (e.g., chest, furnace).

world: World — Read-Only

A reference to the world where this block entity is located.

Methods

putNbt(nbtOrPath: table|string, value?: any) → changed: integer?

Merges NBT data into this block entity. There are two forms:

  • putNbt(nbt) merges the table into the block entity's NBT. Keys the table omits are left alone. Entries in Items are matched by Slot; other lists are merged by position.

  • putNbt(path, value) merges value at every tag the NBT path matches, with the same rules, and returns the number of changed tags. See Entity:putNbt for the path syntax.

Example

local o = spell.owner
local h = o:raycastBlock(5)
spell.pos = h.blockPos
if spell.block.type.id ~= "chest" then
    print("no chest found")
    return
end
local blockEntity = spell.blockEntity
blockEntity:putNbt({
  CustomName = { text = "Treasure Chest", color = "gold", bold = true },
  Lock = "SecretKey"
})

Changing one slot of a chest by path: 

spell.blockEntity:putNbt("Items[{Slot:0b}].count", 16)

Parameters

  • nbtOrPath: table|string — The NBT data to merge, or an NBT path.
  • value?: any — The value to merge at the path. Required when nbtOrPath is a path.

Returns

  • changed: integer? — The number of changed tags if a path was given, otherwise nil.

removeNbt(path: string, ...: string) → removed: integer

Removes every tag the given NBT paths match and returns how many were removed. See Entity:removeNbt for the path syntax and how values Minecraft keeps are handled.

Example

local chest = spell.blockEntity
chest:removeNbt("Items[{Slot:0b}]")  -- empties slot 0
chest:removeNbt("Items")             -- empties the chest

Parameters

  • path: string — An NBT path.
  • ...: string — More NBT paths.

Returns

  • removed: integer — The number of removed tags.