Readonlyheightimport { Player, system, world } from "@minecraft/server";
// Get all dimensions
const overworld = world.getDimension("overworld");
const nether = world.getDimension("nether");
const end = world.getDimension("the end");
// If user sends a scriptevent command with id test:height_range, it prints the height of each dimension in a world.
system.afterEvents.scriptEventReceive.subscribe((event) => {
if (event.id === "test:height_range") {
// Gets the height range of every dimension
const overworldHeight = overworld.heightRange;
const netherHeight = nether.heightRange;
const endHeight = end.heightRange;
// Sends the message to player who sent the command
if (event.sourceEntity instanceof Player) {
event.sourceEntity.sendMessage(
`Overworld height: ${overworldHeight.min} to ${overworldHeight.max} (Height: ${overworldHeight.max - overworldHeight.min} blocks)`,
);
event.sourceEntity.sendMessage(
`Nether height: ${netherHeight.min} to ${netherHeight.max} (Height: ${netherHeight.max - netherHeight.min} blocks)`,
);
event.sourceEntity.sendMessage(
`End height: ${endHeight.min} to ${endHeight.max} (Height: ${endHeight.max - endHeight.min} blocks)`,
);
}
}
});
ReadonlyidVolume of blocks that will be checked.
Block filter that will be checked against each block in the volume.
OptionalallowUnloadedChunks: booleanIf set to true will suppress the UnloadedChunksError if some or all of the block volume is outside of the loaded chunks. Will only check the block locations that are within the loaded chunks in the volume. Defaults to: false
Returns true if at least one block in the volume satisfies the filter, false otherwise.
The location of the explosion.
Radius, in blocks, of the explosion to create.
OptionalexplosionOptions: ExplosionOptionsAdditional configurable options for the explosion.
Creates an explosion at the specified location.
This function can't be called in read-only mode.
import { DimensionLocation } from "@minecraft/server";
function createExplosion(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
log("Creating an explosion of radius 10.");
targetLocation.dimension.createExplosion(targetLocation, 10);
}
import { DimensionLocation } from "@minecraft/server";
import { Vector3Utils } from "@minecraft/math";
function createNoBlockExplosion(
log: (message: string, status?: number) => void,
targetLocation: DimensionLocation
) {
const explodeNoBlocksLoc = Vector3Utils.floor(Vector3Utils.add(targetLocation, { x: 1, y: 2, z: 1 }));
log("Creating an explosion of radius 15 that does not break blocks.");
targetLocation.dimension.createExplosion(explodeNoBlocksLoc, 15, { breaksBlocks: false });
}
import { DimensionLocation } from "@minecraft/server";
import { Vector3Utils } from "@minecraft/math";
function createExplosions(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
const explosionLoc = Vector3Utils.add(targetLocation, { x: 0.5, y: 0.5, z: 0.5 });
log("Creating an explosion of radius 15 that causes fire.");
targetLocation.dimension.createExplosion(explosionLoc, 15, { causesFire: true });
const belowWaterLoc = Vector3Utils.add(targetLocation, { x: 3, y: 1, z: 3 });
log("Creating an explosion of radius 10 that can go underwater.");
targetLocation.dimension.createExplosion(belowWaterLoc, 10, { allowUnderwater: true });
}
Volume of blocks to be filled.
Type of block to fill the volume with.
Optionaloptions: BlockFillOptionsA set of additional options, such as a block filter which can be used to include / exclude specific blocks in the fill.
Returns a ListBlockVolume which contains all the blocks that were placed.
Fills an area of blocks with a specific block type.
This function can't be called in read-only mode.
import { BlockPermutation, BlockVolume, world } from "@minecraft/server";
// Command: /fill 0 10 0 20 30 40 underwater_tnt replace air
const overworld = world.getDimension("overworld");
const volume = new BlockVolume({ x: 0, y: 10, z: 0 }, { x: 20, y: 30, z: 40 });
const tnt = BlockPermutation.resolve("minecraft:underwater_tnt");
overworld.fillBlocks(volume, tnt, {
blockFilter: { excludeTypes: ["minecraft:air"] },
});
import {
BlockPermutation,
BlockVolume,
Dimension,
Vector3,
world,
} from "@minecraft/server";
function fillBlockType(
dimension: Dimension,
from: Vector3,
to: Vector3,
block: string,
): void {
const volume = new BlockVolume(from, to);
dimension.fillBlocks(volume, block);
}
// Command: /fill 0 10 0 20 30 40 diamond_block
const overworld = world.getDimension("overworld");
fillBlockType(
overworld,
{ x: 0, y: 10, z: 0 },
{ x: 20, y: 30, z: 40 },
"minecraft:diamond_block",
);
BetaStarting location to look for a biome to find.
Identifier of the biome to look for.
Optionaloptions: BiomeSearchOptionsAdditional selection criteria for a biome search.
Returns a location of the biome, or undefined if a biome could not be found.
Finds the location of the closest biome of a particular type. Note that the findClosestBiome operation can take some time to complete, so avoid using many of these calls within a particular tick.
This function can't be called in read-only mode.
// Script by JaylyMC
import { BiomeTypes, system, world } from "@minecraft/server";
import { Vector3Utils } from "@minecraft/math";
/**
* Returns the biome that this location in this dimension resides in
* @param location The location to search for a biome
* @param dimension The dimension to search for a biome
* @returns The biome that this location in this dimension resides in
*/
function getBiome(location, dimension) {
// Retrieve a list of all available biome types in the dimension.
const biomeTypes = BiomeTypes.getAll();
// Define the search options, specifying a bounding search area of 64 blocks in all directions.
const searchOptions = {
boundingSize: { x: 64, y: 64, z: 64 },
};
// Variable to track the closest biome found during the search.
let closestBiome;
// Iterate through all available biome types.
for (const biome of biomeTypes) {
// Attempt to locate the closest instance of the current biome type.
const biomeLocation = dimension.findClosestBiome(
location,
biome,
searchOptions,
);
// If a biome location is found, calculate its distance from the input location.
if (biomeLocation) {
const distance = Vector3Utils.distance(biomeLocation, location);
// Update `closestBiome` if this biome is closer than the previously found one.
if (!closestBiome || distance < closestBiome.distance) {
closestBiome = { biome, distance };
}
}
}
// If no biome was found within the search area, throw an error.
if (!closestBiome) {
throw new Error(`Could not find any biome within given location`);
}
// Return the closest biome type found.
return closestBiome.biome;
}
// Example: Gets the biome that this player resides in to action bar
const player = world.getPlayers()[0];
system.runInterval(() => {
const start = Date.now();
const result = getBiome(player.location, player.dimension);
const end = Date.now();
player.onScreenDisplay.setActionBar(
`Biome: ${result.id} (${end - start}ms)`,
);
});
// Script by JaylyMC
import {
BiomeSearchOptions,
BiomeType,
BiomeTypes,
Dimension,
system,
Vector3,
world,
} from "@minecraft/server";
import { Vector3Utils } from "@minecraft/math";
/**
* Biome result
*/
interface GetBiomeResult {
biome: BiomeType;
distance: number;
}
/**
* Returns the biome that this location in this dimension resides in
* @param location The location to search for a biome
* @param dimension The dimension to search for a biome
* @returns The biome that this location in this dimension resides in
*/
function getBiome(location: Vector3, dimension: Dimension): BiomeType {
// Retrieve a list of all available biome types in the dimension.
const biomeTypes: BiomeType[] = BiomeTypes.getAll();
// Define the search options, specifying a bounding search area of 64 blocks in all directions.
const searchOptions: BiomeSearchOptions = {
boundingSize: { x: 64, y: 64, z: 64 },
};
// Variable to track the closest biome found during the search.
let closestBiome: GetBiomeResult | undefined;
// Iterate through all available biome types.
for (const biome of biomeTypes) {
// Attempt to locate the closest instance of the current biome type.
const biomeLocation = dimension.findClosestBiome(
location,
biome,
searchOptions,
);
// If a biome location is found, calculate its distance from the input location.
if (biomeLocation) {
const distance = Vector3Utils.distance(biomeLocation, location);
// Update `closestBiome` if this biome is closer than the previously found one.
if (!closestBiome || distance < closestBiome.distance) {
closestBiome = { biome, distance };
}
}
}
// If no biome was found within the search area, throw an error.
if (!closestBiome) {
throw new Error(`Could not find any biome within given location`);
}
// Return the closest biome type found.
return closestBiome.biome;
}
// Example: Gets the biome that this player resides in to action bar
const player = world.getPlayers()[0];
system.runInterval(() => {
const start = Date.now();
const result = getBiome(player.location, player.dimension);
const end = Date.now();
player.onScreenDisplay.setActionBar(
`Biome: ${result.id} (${end - start}ms)`,
);
});
// Script by JaylyMC
import { BiomeTypes, system, world } from "@minecraft/server";
import { Vector3Utils } from "@minecraft/math";
/**
* Returns the biomes that this location in this dimension resides in
* @param location The location to search for a biome
* @param dimension The dimension to search for a biome
* @returns All biomes that this location in this dimension resides in,
* with closest distance attribute provided.
*/
function getBiomes(location, dimension) {
// Retrieve a list of all available biome types in the dimension.
const biomeTypes = BiomeTypes.getAll();
// Define the search options, specifying a bounding search area of 64 blocks in all directions.
const searchOptions = {
boundingSize: { x: 64, y: 64, z: 64 },
};
// Initialize an array to store the closest biomes and their respective distances.
const closestBiomes = [];
// Iterate through each biome type and attempt to find the closest instance of each.
for (const biome of biomeTypes) {
// Find the closest location of the current biome within the search bounds.
const biomeLocation = dimension.findClosestBiome(
location,
biome,
searchOptions,
);
// If a location is found, calculate the distance from the given location.
if (biomeLocation) {
const distance = Vector3Utils.distance(biomeLocation, location);
// Store the biome and its calculated distance in the results array.
closestBiomes.push({ biome, distance });
}
}
// Return the array containing all found biomes and their distances.
return closestBiomes;
}
// Example: Gets all biomes that this player resides in to action bar
const player = world.getPlayers()[0];
system.runInterval(() => {
const start = Date.now();
const result = getBiomes(player.location, player.dimension);
const end = Date.now();
for (const { biome, distance } of result) {
player.onScreenDisplay.setActionBar(
`Biome: ${biome.id}, Distance: ${distance}`,
);
}
console.log(`Took ${end - start}ms to find all biomes`);
});
// Script by JaylyMC
import {
BiomeSearchOptions,
BiomeType,
BiomeTypes,
Dimension,
system,
Vector3,
world,
} from "@minecraft/server";
import { Vector3Utils } from "@minecraft/math";
/**
* Biome result
*/
interface GetBiomeResult {
biome: BiomeType;
distance: number;
}
/**
* Returns the biomes that this location in this dimension resides in
* @param location The location to search for a biome
* @param dimension The dimension to search for a biome
* @returns All biomes that this location in this dimension resides in,
* with closest distance attribute provided.
*/
function getBiomes(location: Vector3, dimension: Dimension) {
// Retrieve a list of all available biome types in the dimension.
const biomeTypes: BiomeType[] = BiomeTypes.getAll();
// Define the search options, specifying a bounding search area of 64 blocks in all directions.
const searchOptions: BiomeSearchOptions = {
boundingSize: { x: 64, y: 64, z: 64 },
};
// Initialize an array to store the closest biomes and their respective distances.
const closestBiomes: GetBiomeResult[] = [];
// Iterate through each biome type and attempt to find the closest instance of each.
for (const biome of biomeTypes) {
// Find the closest location of the current biome within the search bounds.
const biomeLocation = dimension.findClosestBiome(
location,
biome,
searchOptions,
);
// If a location is found, calculate the distance from the given location.
if (biomeLocation) {
const distance = Vector3Utils.distance(biomeLocation, location);
// Store the biome and its calculated distance in the results array.
closestBiomes.push({ biome, distance });
}
}
// Return the array containing all found biomes and their distances.
return closestBiomes;
}
// Example: Gets all biomes that this player resides in to action bar
const player = world.getPlayers()[0];
system.runInterval(() => {
const start = Date.now();
const result = getBiomes(player.location, player.dimension);
const end = Date.now();
for (const { biome, distance } of result) {
player.onScreenDisplay.setActionBar(
`Biome: ${biome.id}, Distance: ${distance}`,
);
}
console.log(`Took ${end - start}ms to find all biomes`);
});
import { BiomeTypes, Player } from "@minecraft/server";
const biomeTypes = BiomeTypes.getAll();
/**
* @description
* Finds which biome player is in currently
* @deprecated Check out getBiome.ts or getBiomes.ts examples instead
*/
function getBiome(player: Player): string {
for (const currentBiome of biomeTypes) {
const biome = player.dimension.findClosestBiome(
player.location,
currentBiome,
{ boundingSize: { x: 64, y: 64, z: 64 } },
);
if (biome !== undefined) {
return currentBiome.id;
}
}
throw new Error("Player is not in any biome");
}
RcLocation to retrieve the block above from.
Optionaloptions: BlockRaycastOptionsThe options to decide if a block is a valid result.
RcLocation to retrieve the block below from.
Optionaloptions: BlockRaycastOptionsThe options to decide if a block is a valid result.
Location from where to initiate the ray check.
Vector direction to cast the ray.
Optionaloptions: BlockRaycastOptionsAdditional options for processing this raycast query.
Volume of blocks that will be checked.
Block filter that will be checked against each block in the volume.
OptionalallowUnloadedChunks: booleanIf set to true will suppress the UnloadedChunksError if some or all of the block volume is outside of the loaded chunks. Will only check the block locations that are within the loaded chunks in the volume. Defaults to: false
Returns the ListBlockVolume that contains all the block locations that satisfied the block filter.
import {
BlockPermutation,
BlockVolume,
system,
world,
} from "@minecraft/server";
// Get every non-air block location at chunk (0, 0)
const overworld = world.getDimension("overworld");
const volume = new BlockVolume(
{ x: 0, y: overworld.heightRange.min, z: 0 },
{ x: 15, y: overworld.heightRange.max, z: 15 },
);
const locations = overworld.getBlocks(
volume,
{ excludeTypes: ["minecraft:air"] },
false,
);
/**
* A simple generator that replace non-air blocks to cobblestone at chunk (0, 0),
* yielding after each block placement.
* @returns {Generator<void, void, void>} A generator that yields after each block placement.
*/
function* blockPlacingGenerator() {
for (const location of locations.getBlockLocationIterator()) {
const block = overworld.getBlock(location);
block.setPermutation(BlockPermutation.resolve("minecraft:cobblestone"));
yield;
}
}
system.runJob(blockPlacingGenerator());
Optionaloptions: EntityQueryOptionsAdditional options that can be used to filter the set of entities returned.
An entity array.
Returns a set of entities based on a set of conditions defined via the EntityQueryOptions set of filter criteria.
import { EntityQueryOptions, DimensionLocation } from "@minecraft/server";
function bounceSkeletons(targetLocation: DimensionLocation) {
const mobs = ["creeper", "skeleton", "sheep"];
// create some sample mob data
for (let i = 0; i < 10; i++) {
targetLocation.dimension.spawnEntity(mobs[i % mobs.length], targetLocation);
}
const eqo: EntityQueryOptions = {
type: "skeleton",
};
for (const entity of targetLocation.dimension.getEntities(eqo)) {
entity.applyKnockback(0, 0, 0, 1);
}
}
import { EntityQueryOptions, DimensionLocation } from "@minecraft/server";
function tagsQuery(targetLocation: DimensionLocation) {
const mobs = ["creeper", "skeleton", "sheep"];
// create some sample mob data
for (let i = 0; i < 10; i++) {
const mobTypeId = mobs[i % mobs.length];
const entity = targetLocation.dimension.spawnEntity(mobTypeId, targetLocation);
entity.addTag("mobparty." + mobTypeId);
}
const eqo: EntityQueryOptions = {
tags: ["mobparty.skeleton"],
};
for (const entity of targetLocation.dimension.getEntities(eqo)) {
entity.kill();
}
}
import { EntityItemComponent, EntityComponentTypes, DimensionLocation } from "@minecraft/server";
function testThatEntityIsFeatherItem(
log: (message: string, status?: number) => void,
targetLocation: DimensionLocation
) {
const items = targetLocation.dimension.getEntities({
location: targetLocation,
maxDistance: 20,
});
for (const item of items) {
const itemComp = item.getComponent(EntityComponentTypes.Item) as EntityItemComponent;
if (itemComp) {
if (itemComp.itemStack.typeId.endsWith("feather")) {
log("Success! Found a feather", 1);
}
}
}
}
import { EntityQueryOptions, GameMode, world } from "@minecraft/server";
const options: EntityQueryOptions = {
families: ["mob", "animal"],
excludeTypes: ["cow"],
maxDistance: 50,
excludeGameModes: [GameMode.creative, GameMode.spectator],
};
const filteredEntities = world.getDimension("overworld").getEntities(options);
console.log(
"Filtered Entities:",
filteredEntities.map((entity) => entity.typeId),
);
Optionaloptions: EntityRaycastOptionsAdditional options for processing this raycast query.
Optionaloptions: EntityQueryOptionsAdditional options that can be used to filter the set of players returned.
A player array.
Returns a set of players based on a set of conditions defined via the EntityQueryOptions set of filter criteria.
import { EntityQueryOptions, world } from "@minecraft/server";
const entityQueryOptions: EntityQueryOptions = {
maxDistance: 100,
scoreOptions: [
{ objective: "kills", minScore: 10 },
{ objective: "deaths", maxScore: 5 },
],
};
const filteredPlayers = world
.getDimension("overworld")
.getPlayers(entityQueryOptions);
console.log(
"Filtered Players in Overworld:",
filteredPlayers.map((player) => player.name),
);
BetaReturns a WeatherType that explains the broad category of weather that is currently going on.
The string identifier for the feature.
Location to place the feature.
OptionalshouldThrow: booleanSpecifies if the function call will throw an error if the feature could not be placed. Note: The function call will always throw an error if using an unknown feature name or trying to place in a unloaded chunk. Defaults to: false
Places the given feature into the dimension at the specified location.
This function can't be called in read-only mode.
An error will be thrown if the feature name is invalid. An error will be thrown if the location is in an unloaded chunk.
Error
The string identifier for the feature rule.
Location to place the feature rule.
Places the given feature rule into the dimension at the specified location.
This function can't be called in read-only mode.
An error will be thrown if the feature rule name is invalid. An error will be thrown if the location is in an unloaded chunk.
Identifier of the sound.
Location of the sound.
OptionalsoundOptions: WorldSoundOptionsAdditional options for configuring additional effects for the sound.
Command to run. Note that command strings should not start with slash.
Returns a command result with a count of successful values from the command.
Runs a command synchronously using the context of the broader dimenion.
This function can't be called in read-only mode.
The location within the dimension to set the block.
The block permutation to set.
Set the type of weather to apply.
Optionalduration: numberSets the duration of the weather (in ticks). If no duration is provided, the duration will be set to a random duration between 300 and 900 seconds.
Identifier of the type of entity to spawn. If no namespace is specified, 'minecraft:' is assumed.
The location at which to create the entity.
Optionaloptions: SpawnEntityOptionsNewly created entity at the specified location.
Creates a new entity (e.g., a mob) at the specified location.
This function can't be called in read-only mode.
import { DimensionLocation } from '@minecraft/server';
import { Vector3Utils } from '@minecraft/math';
function spawnAdultHorse(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
log('Create a horse and triggering the ageable_grow_up event, ensuring the horse is created as an adult');
targetLocation.dimension.spawnEntity(
'minecraft:horse<minecraft:ageable_grow_up>',
Vector3Utils.add(targetLocation, { x: 0, y: 1, z: 0 })
);
}
import { DimensionLocation } from "@minecraft/server";
import { MinecraftEntityTypes, MinecraftEffectTypes } from "@minecraft/vanilla-data";
function quickFoxLazyDog(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
const fox = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Fox, {
x: targetLocation.x + 1,
y: targetLocation.y + 2,
z: targetLocation.z + 3,
});
fox.addEffect(MinecraftEffectTypes.Speed, 10, {
amplifier: 2,
});
log("Created a fox.");
const wolf = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Wolf, {
x: targetLocation.x + 4,
y: targetLocation.y + 2,
z: targetLocation.z + 3,
});
wolf.addEffect(MinecraftEffectTypes.Slowness, 10, {
amplifier: 2,
});
wolf.isSneaking = true;
log("Created a sneaking wolf.", 1);
}
import { DimensionLocation } from "@minecraft/server";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";
function triggerEvent(targetLocation: DimensionLocation) {
const creeper = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Creeper, targetLocation);
creeper.triggerEvent("minecraft:start_exploding_forced");
}
Newly created item stack entity at the specified location.
Creates a new item stack as an entity at the specified location.
This function can't be called in read-only mode.
import { ItemStack, DimensionLocation } from "@minecraft/server";
import { MinecraftItemTypes } from "@minecraft/vanilla-data";
function itemStacks(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
const oneItemLoc = { x: targetLocation.x + targetLocation.y + 3, y: 2, z: targetLocation.z + 1 };
const fiveItemsLoc = { x: targetLocation.x + 1, y: targetLocation.y + 2, z: targetLocation.z + 1 };
const diamondPickaxeLoc = { x: targetLocation.x + 2, y: targetLocation.y + 2, z: targetLocation.z + 4 };
const oneEmerald = new ItemStack(MinecraftItemTypes.Emerald, 1);
const onePickaxe = new ItemStack(MinecraftItemTypes.DiamondPickaxe, 1);
const fiveEmeralds = new ItemStack(MinecraftItemTypes.Emerald, 5);
log(`Spawning an emerald at (${oneItemLoc.x}, ${oneItemLoc.y}, ${oneItemLoc.z})`);
targetLocation.dimension.spawnItem(oneEmerald, oneItemLoc);
log(`Spawning five emeralds at (${fiveItemsLoc.x}, ${fiveItemsLoc.y}, ${fiveItemsLoc.z})`);
targetLocation.dimension.spawnItem(fiveEmeralds, fiveItemsLoc);
log(`Spawning a diamond pickaxe at (${diamondPickaxeLoc.x}, ${diamondPickaxeLoc.y}, ${diamondPickaxeLoc.z})`);
targetLocation.dimension.spawnItem(onePickaxe, diamondPickaxeLoc);
}
import { ItemStack, DimensionLocation } from "@minecraft/server";
import { MinecraftItemTypes } from "@minecraft/vanilla-data";
function spawnFeatherItem(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
const featherItem = new ItemStack(MinecraftItemTypes.Feather, 1);
targetLocation.dimension.spawnItem(featherItem, targetLocation);
log(`New feather created at ${targetLocation.x}, ${targetLocation.y}, ${targetLocation.z}!`);
}
Identifier of the particle to create.
The location at which to create the particle emitter.
OptionalmolangVariables: MolangVariableMapA set of optional, customizable variables that can be adjusted for this particle.
Creates a new particle emitter at a specified location in the world.
This function can't be called in read-only mode.
import { MolangVariableMap, DimensionLocation } from "@minecraft/server";
function spawnParticle(targetLocation: DimensionLocation) {
for (let i = 0; i < 100; i++) {
const molang = new MolangVariableMap();
molang.setColorRGB("variable.color", { red: Math.random(), green: Math.random(), blue: Math.random() });
const newLocation = {
x: targetLocation.x + Math.floor(Math.random() * 8) - 4,
y: targetLocation.y + Math.floor(Math.random() * 8) - 4,
z: targetLocation.z + Math.floor(Math.random() * 8) - 4,
};
targetLocation.dimension.spawnParticle("minecraft:colored_flame_particle", newLocation, molang);
}
}
A class that represents a particular dimension (e.g., The End) within a world.