ReadonlydimensionThis property can't be read in early-execution mode.
ReadonlyisThis property can't be read in early-execution mode.
import { BlockPermutation, system, world } from "@minecraft/server";
world.afterEvents.entitySpawn.subscribe(({ entity }) => {
if (entity.typeId !== "minecraft:egg") return;
const intervalId = system.runInterval(() => {
if (!entity.isValid) {
system.clearRun(intervalId);
return;
}
const block = entity.dimension.getBlock(entity.location)?.below();
if (!block) return;
if (block.isAir) {
block.setPermutation(BlockPermutation.resolve("minecraft:white_wool"));
} else {
system.clearRun(intervalId);
}
});
});
ReadonlyisReturns true if this block is a liquid block - (e.g., a water block and a lava block are liquid, while an air block and a stone block are not. Water logged blocks are not liquid blocks).
This property can't be read in early-execution mode.
import { Player, system } from "@minecraft/server";
// Run `/scriptevent example:debug` in chat to check whether you are standing in a liquid block.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:debug" || !(sourceEntity instanceof Player)) return;
const block = sourceEntity.dimension.getBlock(sourceEntity.location);
if (!block) return;
sourceEntity.sendMessage(block.isLiquid ? `Liquid block: ${block.typeId}` : `Not liquid: ${block.typeId}`);
});
Readonly BetaisReturns true if this block is solid and impassible - (e.g., a cobblestone block and a diamond block are solid, while a ladder block and a fence block are not).
This property can't be read in early-execution mode.
import { world } from "@minecraft/server";
// Subscribe to the event that triggers when a player places a block
world.afterEvents.playerPlaceBlock.subscribe((eventData) => {
// Destructure the block object from the event data
const { block } = eventData;
// Check if the placed block is solid
if (block.isSolid) {
// Get the coordinates of the block's location
let { x, y, z } = block.location;
// Create a string of the coordinates in the format "x, y, z"
let coordinates = [x, y, z].join(", ");
// Send a message to the world indicating the location of the placed solid block
world.sendMessage("You placed a solid block at location: " + coordinates);
}
});
ReadonlyisReturns true if this reference to a block is still valid (for example, if the block is unloaded, references to that block will no longer be valid.)
This property can't be read in early-execution mode.
ReadonlyisThis property can't be read in early-execution mode.
ReadonlylocalizationThis property can't be read in early-execution mode.
ReadonlylocationThis property can't be read in early-execution mode.
import { Player, system } from "@minecraft/server";
// Run `/scriptevent example:blockexplode` in chat to create an explosion at the block under you.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:blockexplode" || !(sourceEntity instanceof Player)) return;
const block = sourceEntity.dimension.getBlock(sourceEntity.location)?.below();
if (!block) return;
block.dimension.createExplosion(block.location, 4);
});
ReadonlypermutationThis property can't be read in early-execution mode.
import { Player, system } from "@minecraft/server";
// Run `/scriptevent example:blockstates` in chat to inspect the block states under your feet.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:blockstates" || !(sourceEntity instanceof Player)) return;
const block = sourceEntity.dimension.getBlock(sourceEntity.location)?.below();
if (!block) return;
const blockStates = block.permutation.getAllStates();
sourceEntity.sendMessage(`${block.typeId}: ${JSON.stringify(blockStates)}`);
});
ReadonlytypeThis property can't be read in early-execution mode.
ReadonlytypeIdentifier of the type of block for this block. Warning: Vanilla block names can be changed in future releases, try using 'Block.matches' instead for block comparison.
This property can't be read in early-execution mode.
ReadonlyxThis property can't be read in early-execution mode.
ReadonlyyThis property can't be read in early-execution mode.
ReadonlyzThis property can't be read in early-execution mode.
Optionalsteps: number
Number of steps above to step before returning. Defaults to: 1
Returns the Block above this block (positive in the Y direction).
This function can't be called in early-execution mode.
Optionalsteps: number
Number of steps below to step before returning. Defaults to: 1
Returns the Block below this block (negative in the Y direction).
This function can't be called in early-execution mode.
Returns the Vector3 of the center of this block on the X and Z axis.
This function can't be called in early-execution mode.
The type of liquid this function should be called for.
Whether this block is removed when touched by liquid.
This function can't be called in early-execution mode.
The type of liquid this function should be called for.
Whether this block can have a liquid placed over it.
This function can't be called in early-execution mode.
Beta
Block type or block permutation to check placement for.
OptionalfaceToPlaceOn: Direction
Optional specific face of this block to check placement against.
Returns true if the block type or permutation can be
placed on this block, else false.
Checks to see whether it is valid to place the specified block type or block permutation, on a specified face on this block.
This function can't be called in early-execution mode.
Returns the Vector3 of the center of this block on the X, Y, and Z axis.
This function can't be called in early-execution mode.
Optionalsteps: number
Number of steps to the east to step before returning. Defaults to: 1
Returns the Block to the east of this block (positive in the X direction).
This function can't be called in early-execution mode.
The identifier of the component (e.g., 'minecraft:inventory'). If no namespace prefix is specified, 'minecraft:' is assumed. Available component IDs are those in the BlockComponentTypes enum and custom component IDs registered with the BlockComponentRegistry.
Returns the component if it exists on the block, otherwise undefined.
Gets a component (that represents additional capabilities) for a block - for example, an inventory component of a chest block.
This function can't be called in early-execution mode.
import { BlockPermutation, ItemStack, Player, system } from "@minecraft/server";
// Run `/scriptevent example:addchestitem` in chat to place a chest with cobblestone at your feet.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:addchestitem" || !(sourceEntity instanceof Player)) return;
const block = sourceEntity.dimension.getBlock(sourceEntity.location);
if (!block) return;
block.setPermutation(BlockPermutation.resolve("minecraft:chest"));
const inventory = block.getComponent("minecraft:inventory");
if (!inventory?.container) return;
inventory.container.addItem(new ItemStack("minecraft:cobblestone", 64));
});
import { BlockPermutation, Player, SignSide, system } from "@minecraft/server";
// Run `/scriptevent example:edithangingsign` in chat to place and edit a hanging sign.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:edithangingsign" || !(sourceEntity instanceof Player)) return;
const block = sourceEntity.dimension.getBlock(sourceEntity.location);
if (!block) return;
block.setPermutation(BlockPermutation.resolve("minecraft:birch_hanging_sign"));
const sign = block.getComponent("minecraft:sign");
if (!sign) return;
sign.setText("back", SignSide.Back);
sign.setText("front", SignSide.Front);
});
import { BlockPermutation, Player, system } from "@minecraft/server";
// Run `/scriptevent example:editsign` in chat to place and clear a standing sign.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:editsign" || !(sourceEntity instanceof Player)) return;
const block = sourceEntity.dimension.getBlock(sourceEntity.location);
if (!block) return;
block.setPermutation(BlockPermutation.resolve("minecraft:darkoak_standing_sign"));
const sign = block.getComponent("minecraft:sign");
if (!sign) return;
sign.setText("Welcome");
});
import { BlockPermutation, Player, system, world } from "@minecraft/server";
// Run `/scriptevent example:pistonattachedblocks` in chat to inspect blocks attached to a piston.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:pistonattachedblocks" || !(sourceEntity instanceof Player)) return;
const dimension = sourceEntity.dimension;
const origin = sourceEntity.location;
const pistonBlock = dimension.getBlock({ x: origin.x, y: origin.y, z: origin.z });
if (!pistonBlock) return;
pistonBlock.setPermutation(BlockPermutation.resolve("minecraft:piston"));
for (let offset = 1; offset <= 3; offset++) {
const pushBlock = dimension.getBlock({ x: origin.x, y: origin.y, z: origin.z + offset });
pushBlock?.setPermutation(BlockPermutation.resolve("minecraft:dirt"));
}
const piston = pistonBlock.getComponent("minecraft:piston");
if (!piston) return;
const attachedBlocks = piston.getAttachedBlocks();
sourceEntity.sendMessage(`Attached blocks: ${attachedBlocks.length}`);
});
world.afterEvents.pistonActivate.subscribe(({ piston, isExpanding }) => {
const attachedBlocks = piston.getAttachedBlocks();
console.log(`Piston ${isExpanding ? "extending" : "retracting"} (${attachedBlocks.length} blocks).`);
});
This function can't be called in early-execution mode.
Optionalamount: number
Number of instances of this block to place in the item stack. Defaults to: 1 Bounds: [1, 255]
OptionalwithData: boolean
Whether additional data facets of the item stack are included. Defaults to: false
An itemStack with the specified amount of items and data. Returns undefined if block type is incompatible.
Creates a prototype item stack based on this block that can be used with Container/ContainerSlot APIs.
This function can't be called in early-execution mode.
The brightness level on the block.
This function can't be called in restricted-execution mode.
This function can't be called in early-execution mode.
Beta
This function can't be called in early-execution mode.
Returns array of all loaded block parts if this block has the 'minecraft:multi_block' trait. If it does not have the trait returns undefined
This function can't be called in early-execution mode.
Returns undefined if redstone power is not applicable to this block.
This function can't be called in early-execution mode.
import { Player, system } from "@minecraft/server";
// Run `/scriptevent example:ispowered` in chat to check redstone power on the block under you.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:ispowered" || !(sourceEntity instanceof Player)) return;
const block = sourceEntity.dimension.getBlock(sourceEntity.location)?.below();
if (!block) return;
const power = block.getRedstonePower() ?? 0;
sourceEntity.sendMessage(power > 0 ? `Block is powered (level ${power}).` : "Block is not powered.");
});
The brightness level on the block.
This function can't be called in restricted-execution mode.
This function can't be called in early-execution mode.
The list of tags that the block has.
This function can't be called in early-execution mode.
The identifier of the component (e.g., 'minecraft:inventory') to retrieve. If no namespace prefix is specified, 'minecraft:' is assumed.
This function can't be called in early-execution mode.
Beta
This function can't be called in early-execution mode.
Tag to check for.
Returns true if the permutation of this block has the tag,
else false.
import { DimensionLocation } from '@minecraft/server';
function checkBlockTags(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
// Fetch the block
const block = targetLocation.dimension.getBlock(targetLocation);
// check that the block is loaded
if (block) {
log(`Block is dirt: ${block.hasTag('dirt')}`);
log(`Block is wood: ${block.hasTag('wood')}`);
log(`Block is stone: ${block.hasTag('stone')}`);
}
}
This function can't be called in early-execution mode.
The type of liquid this function should be called for.
Whether this block stops liquid from flowing.
This function can't be called in early-execution mode.
Whether liquid can flow into the block from the provided direction, or flow out from the provided direction when liquid is placed into it with a bucket
Returns whether liquid can flow into the block from the provided direction, or flow out from the provided direction when liquid is placed into it with a bucket.
This function can't be called in early-execution mode.
The type of liquid this function should be called for.
Whether this block is removed and spawns its item when touched by liquid.
This function can't be called in early-execution mode.
Block type identifier to match this API against.
Optionalstates: Record<string, string | number | boolean>
Optional set of block states to test this block against.
Returns true if the block matches the specified criteria.
This function can't be called in early-execution mode.
import { Player, system } from "@minecraft/server";
// Run `/scriptevent example:checkstandingsign` in chat while standing on a north-facing standing sign.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:checkstandingsign" || !(sourceEntity instanceof Player)) return;
const block = sourceEntity.dimension.getBlock(sourceEntity.location);
if (!block) return;
const matches = block.matches("minecraft:standing_sign", { ground_sign_direction: 8 });
sourceEntity.sendMessage(
matches ? "This block is a north-facing standing sign." : `Found ${block.typeId} instead.`,
);
});
Optionalsteps: number
Number of steps to the north to step before returning. Defaults to: 1
Returns the Block to the north of this block (negative in the Z direction).
This function can't be called in early-execution mode.
import { Player, system } from "@minecraft/server";
// Run `/scriptevent example:blockatnorth` in chat to inspect the block 1 block north of you.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:blockatnorth" || !(sourceEntity instanceof Player)) return;
const block = sourceEntity.dimension.getBlock(sourceEntity.location);
const blockAtNorth = block?.north();
if (!blockAtNorth) return;
sourceEntity.sendMessage(`Block to the north: ${blockAtNorth.typeId}`);
});
The offset vector. For example, an offset of 0, 1, 0 will return the block above the current block.
Block at the specified offset, or undefined if that block could not be retrieved (for example, the block and its relative chunk is not loaded yet.)
This function can't be called in early-execution mode.
Beta
Name of the scheduled event to remove.
This function can't be called in restricted-execution mode.
This function can't be called in early-execution mode.
Beta
Name of the event to schedule. Up to 31 characters.
Number of ticks to wait before the event is raised. Must be at least 1. Minimum value: 1
Schedules a named tick event for this block. The event will
be delivered to block custom components registered with the
onNamedTick callback after the specified delay.
This function can't be called in restricted-execution mode.
This function can't be called in early-execution mode.
Permutation that contains a set of property states for the Block.
This function can't be called in restricted-execution mode.
This function can't be called in early-execution mode.
import { BlockPermutation, Player, system } from "@minecraft/server";
// Run `/scriptevent example:bedrocktoair` in chat while standing on bedrock to replace it with air.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:bedrocktoair" || !(sourceEntity instanceof Player)) return;
const block = sourceEntity.dimension.getBlock(sourceEntity.location)?.below();
if (!block) return;
if (block.typeId === "minecraft:bedrock") {
block.setPermutation(BlockPermutation.resolve("minecraft:air"));
sourceEntity.sendMessage("Replaced bedrock with air.");
} else {
sourceEntity.sendMessage(`Expected bedrock below you, found ${block.typeId}.`);
}
});
Identifier of the type of block to apply - for example, minecraft:powered_repeater.
This function can't be called in restricted-execution mode.
This function can't be called in early-execution mode.
import { BlockTypes, world } from "@minecraft/server";
world.afterEvents.playerPlaceBlock.subscribe(({ player, block }) => {
const blockTypes = BlockTypes.getAll();
const randomBlockType = blockTypes[Math.floor(Math.random() * blockTypes.length)];
if (!randomBlockType) return;
block.setType(randomBlockType);
player.sendMessage(`Changed placed block to ${randomBlockType.id}.`);
});
true if the block should have water within it.
Sets whether this block has a water logged state - for example, whether stairs are submerged within water.
This function can't be called in restricted-execution mode.
This function can't be called in early-execution mode.
Optionalsteps: number
Number of steps to the south to step before returning. Defaults to: 1
Returns the Block to the south of this block (positive in the Z direction).
This function can't be called in early-execution mode.
import { Player, system } from "@minecraft/server";
// Run `/scriptevent example:blockatsouth` in chat to inspect the block 1 block south of you.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:blockatsouth" || !(sourceEntity instanceof Player)) return;
const block = sourceEntity.dimension.getBlock(sourceEntity.location);
const nearbyBlock = block?.south();
if (!nearbyBlock) return;
sourceEntity.sendMessage(`Block to the south: ${nearbyBlock.typeId}`);
});
Beta
Permutation that contains a set of property states for the Block.
Returns true if the block permutation data was
successfully set, else false.
Tries to set the block in the dimension to the state of the permutation by first checking if the placement is valid.
This function can't be called in restricted-execution mode.
This function can't be called in early-execution mode.
Optionalsteps: number
Number of steps to the west to step before returning. Defaults to: 1
Returns the Block to the west of this block (negative in the X direction).
This function can't be called in early-execution mode.
import { Player, system } from "@minecraft/server";
// Run `/scriptevent example:blockatwest` in chat to inspect the block 10 blocks west of you.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:blockatwest" || !(sourceEntity instanceof Player)) return;
const block = sourceEntity.dimension.getBlock(sourceEntity.location);
const blockAtWest = block?.west(10);
if (!blockAtWest) return;
sourceEntity.sendMessage(`Block 10 blocks west: ${blockAtWest.typeId}`);
});
Represents a block in a dimension. A block represents a unique X, Y, and Z within a dimension and get/sets the state of the block at that location. This type was significantly updated in version 1.17.10.21.
Example: createWall.ts
Source