World

Namespace Mc.Scripting.Worlds · Kind struct (readonly)

public readonly struct World : IEquatable<World>

A handle to a dimension (overworld, nether, end …). Blittable. Dimensions live as long as the server. The members are split over several files by topic: blocks and block entities (World.Blocks.cs), entities and effects (World.Entities.cs), time, weather, spawn and chunk loading (World.Environment.cs). Everything here must be called on the tick thread.

Constructors

Member	Description
World(int index)	Wraps a dimension slot.

Constructor

public World(int index)

Wraps a dimension slot.

Parameters

Name	Type	Description
index	int	The slot.

Fields

Member	Description
readonly int Index	The dimension slot (overworld 0, nether 1, end 2).

Index

public readonly int Index;

The dimension slot (overworld 0, nether 1, end 2).

Properties

Member	Description
long DayTime { get; set; }	The time of day clock in ticks since the world was created (a day is 24000 ticks: 0 is sunrise, 6000 noon, 12000 sunset, 18000 midnight).
bool DayTimePaused { get; set; }	Whether the day/night clock is stopped (/time pause).
float DayTimeRate { get; set; }	How fast the day/night clock runs (1 = normal, 2 = twice as fast).
IReadOnlyList<Entity> Entities { get; }	Every entity of the dimension (players, mobs, item entities, experience orbs, projectiles, falling blocks …).
long GameTime { get; }	The number of ticks the dimension has been running (does not change with /time set; 20 per second).
long GeneratedChunkCount { get; }	How many chunks this dimension has generated from scratch since the server started (chunks loaded from disk do not count): sample it twice to get a generation rate.
bool HasDayTime { get; }	Whether this dimension has a day/night clock.
int Height { get; }	The build height: the number of block layers (384 in the overworld).
bool IsRaining { get; }	Whether it is raining (also during a thunderstorm).
bool IsThundering { get; }	Whether a thunderstorm is going on.
bool IsValid { get; }	Whether the slot names a dimension of this server.
string Key { get; }	The dimension key, e.g.
int LoadedChunkCount { get; }	How many chunks are loaded in this dimension right now.
int MaxY { get; }	The highest block y of the dimension.
int MinY { get; }	The lowest block y of the dimension (-64 in the overworld).
IReadOnlyList<Player> Players { get; }	The players in the dimension.
int SeaLevel { get; }	The sea level (63 in the overworld).
Location SpawnLocation { get; }	The spawn point of the dimension (where new players appear and where players without a bed respawn) and its facing.
WeatherType Weather { get; }	The weather.
static World End { get; }	The end.
static World Nether { get; }	The nether.
static World Overworld { get; }	The overworld.

DayTime

public long DayTime { get; set; }

The time of day clock in ticks since the world was created (a day is 24000 ticks: 0 is sunrise, 6000 noon, 12000 sunset, 18000 midnight). Setting it moves the sun for every player at once and fires TimeSkipEvent (reason Custom).

Throws

• System.InvalidOperationException: The dimension has no clock (see World.HasDayTime).

DayTimePaused

public bool DayTimePaused { get; set; }

Whether the day/night clock is stopped (/time pause).

DayTimeRate

public float DayTimeRate { get; set; }

How fast the day/night clock runs (1 = normal, 2 = twice as fast).

Entities

public IReadOnlyList<Entity> Entities { get; }

Every entity of the dimension (players, mobs, item entities, experience orbs, projectiles, falling blocks …). A snapshot: entities that spawn or vanish afterwards are not reflected.

GameTime

public long GameTime { get; }

The number of ticks the dimension has been running (does not change with /time set; 20 per second).

GeneratedChunkCount

public long GeneratedChunkCount { get; }

How many chunks this dimension has generated from scratch since the server started (chunks loaded from disk do not count): sample it twice to get a generation rate.

HasDayTime

public bool HasDayTime { get; }

Whether this dimension has a day/night clock. In this server version only the overworld has one; the nether and the end have a fixed time.

Height

public int Height { get; }

The build height: the number of block layers (384 in the overworld). The highest block y is MinY + Height - 1.

IsRaining

public bool IsRaining { get; }

Whether it is raining (also during a thunderstorm).

IsThundering

public bool IsThundering { get; }

Whether a thunderstorm is going on.

IsValid

public bool IsValid { get; }

Whether the slot names a dimension of this server.

Key

public string Key { get; }

The dimension key, e.g. “minecraft:overworld” (empty if the index is invalid).

LoadedChunkCount

public int LoadedChunkCount { get; }

How many chunks are loaded in this dimension right now.

MaxY

public int MaxY { get; }

The highest block y of the dimension.

MinY

public int MinY { get; }

The lowest block y of the dimension (-64 in the overworld).

Players

public IReadOnlyList<Player> Players { get; }

The players in the dimension.

SeaLevel

public int SeaLevel { get; }

The sea level (63 in the overworld).

SpawnLocation

public Location SpawnLocation { get; }

The spawn point of the dimension (where new players appear and where players without a bed respawn) and its facing. Only the overworld has a world spawn the game keeps and saves; the other dimensions report a placeholder.

Weather

public WeatherType Weather { get; }

The weather. Only the overworld has weather in this server version; the other dimensions always report WeatherType.Clear.

End

public static World End { get; }

The end.

Nether

public static World Nether { get; }

The nether.

Overworld

public static World Overworld { get; }

The overworld.

Methods

Member	Description
void AddDayTime(long ticks)	Moves the day time forward (or back with a negative amount).
bool DestroyBlock(BlockPos pos, bool dropItems = true, Entity breaker = default)	Breaks a block the way the game does (Level.destroyBlock): the break particles and sound, optionally the loot, and the block becomes air (or its fluid).
Entity DropItem(BlockPos block, ItemStack stack)	Drops a stack at the centre of a block (the way a broken block drops its loot).
Entity DropItem(Vec3d position, ItemStack stack, bool randomMotion = true)	Drops an item entity with the full stack (data components included) at a position, like a broken block’s drop: a small random sideways drift and a short pickup delay.
bool Equals(World other)
override bool Equals(object? obj)
Explode	Creates an explosion like a creeper’s: it damages and pushes entities (with exposure and distance falloff), destroys blocks (dropping loot, with decay), optionally lights fires, and the clients get the particles and the sound.
BlockState GetBlock(BlockPos pos)	Reads a block state.
NbtCompound? GetBlockEntityData(BlockPos pos)	The data of the block entity at a position (a chest’s items, a sign’s text, a spawner …) in the form /data get block shows, including the id and the position keys.
override int GetHashCode()
BlockInventory? GetInventory(BlockPos pos)	The inventory of the block entity at a position (BlockInventory.At).
int HighestBlockY(int x, int z, HeightMap kind = HeightMap.MotionBlocking)	The y of the highest block of a column (read from the chunk’s height maps, so it is cheap).
bool IsBlockLoaded(BlockPos pos)	Whether the block position is inside a loaded chunk and within the build height.
bool IsChunkLoaded(int chunkX, int chunkZ)	Whether the chunk is loaded and ready (generated, lit, in memory).
PlaySound	Plays a sound at a position to every player of the dimension who is close enough to hear it (16 blocks, or farther for a volume above 1).
SetBlock	Changes a block, like /setblock: the old block entity goes away, the new block’s placement logic and the neighbour updates run (per flags), the clients are told.
bool SetBlock(BlockPos pos, string state, BlockUpdateFlags flags = BlockUpdateFlags.All)	Changes a block to the state parsed from text ("minecraft:oak_stairs[facing=north]").
bool SetBlockEntityData(BlockPos pos, NbtCompound data, bool merge = true)	Changes the data of a block entity, like /data merge block (or /data modify with the full compound).
bool SetSpawn(BlockPos pos, float yaw = 0f, float pitch = 0f)	Changes the spawn point (like /setworldspawn; the clients are told the new position of the compass and of the respawn, and it is saved with the world).
bool SetWeather(WeatherType weather, int? durationTicks = null)	Sets the weather like /weather.
SpawnEntity	Spawns an entity of a type, like /summon.
SpawnParticle	Shows a particle effect at a position to the players of the dimension within 32 blocks (512 with force).
override string ToString()
bool TryGetBlock(BlockPos pos, out BlockState state)	Reads a block state, saying whether the position was readable.

AddDayTime

public void AddDayTime(long ticks)

Moves the day time forward (or back with a negative amount).

Parameters

Name	Type	Description
ticks	long	The amount.

Throws

• System.InvalidOperationException: The dimension has no clock.

DestroyBlock

public bool DestroyBlock(BlockPos pos, bool dropItems = true, Entity breaker = default)

Breaks a block the way the game does (Level.destroyBlock): the break particles and sound, optionally the loot, and the block becomes air (or its fluid). A block entity’s contents drop too.

Parameters

Name	Type	Description
pos	BlockPos	The position.
dropItems	bool = true	Whether the block drops its loot.
breaker	Entity = default	The entity that breaks it (for the loot context), or none.

Returns bool: True when a block was destroyed.

DropItem

public Entity DropItem(BlockPos block, ItemStack stack)

Drops a stack at the centre of a block (the way a broken block drops its loot).

Parameters

Name	Type	Description
block	BlockPos	The block position.
stack	ItemStack	The stack.

Returns Entity: The item entity, or Entity.Null.

DropItem

public Entity DropItem(Vec3d position, ItemStack stack, bool randomMotion = true)

Drops an item entity with the full stack (data components included) at a position, like a broken block’s drop: a small random sideways drift and a short pickup delay. EntitySpawnEvent fires with reason Plugin and can cancel it.

Parameters

Name	Type	Description
position	Vec3d	Where the item appears.
stack	ItemStack	The stack (1 up to the stack size).
randomMotion	bool = true	Whether the item drifts like a block drop (false: it falls straight down).

Returns Entity: The item entity, or Entity.Null when the chunk is not loaded, the stack is not valid or a handler cancelled the spawn.

Equals

public bool Equals(World other)

Parameters

Name	Type	Description
other	World

Returns bool

Equals

public override bool Equals(object? obj)

Parameters

Name	Type	Description
obj	object?

Returns bool

Explode

public bool Explode(Vec3d position, float power, bool setFire = false, bool breakBlocks = true, Entity source = default)

Creates an explosion like a creeper’s: it damages and pushes entities (with exposure and distance falloff), destroys blocks (dropping loot, with decay), optionally lights fires, and the clients get the particles and the sound.

Parameters

Name	Type	Description
position	Vec3d	The centre.
power	float	The radius-like strength (TNT is 4, a creeper 3, a charged creeper 6; the work grows with its cube, so values above 32 are refused).
setFire	bool = false	Whether fires start in the explosion’s wake.
breakBlocks	bool = true	Whether blocks are destroyed (false: only the entities are affected).
source	Entity = default	The entity that causes it (excluded from the damage, used as the damage source), or none.

Returns bool: True when the explosion happened; false for a power outside 0-32 (exclusive of 0), an unloaded centre or an unknown world.

GetBlock

public BlockState GetBlock(BlockPos pos)

Reads a block state. A position in an unloaded chunk or outside the build height reads as air (check World.IsBlockLoaded to tell); the chunk is not loaded by the read.

Parameters

Name	Type	Description
pos	BlockPos	The position.

Returns BlockState: The block state.

GetBlockEntityData

public NbtCompound? GetBlockEntityData(BlockPos pos)

The data of the block entity at a position (a chest’s items, a sign’s text, a spawner …) in the form /data get block shows, including the id and the position keys.

Parameters

Name	Type	Description
pos	BlockPos	The position.

Returns NbtCompound?: A copy of the data, or null when there is no block entity (or its chunk is not loaded).

GetHashCode

public override int GetHashCode()

Returns int

GetInventory

public BlockInventory? GetInventory(BlockPos pos)

The inventory of the block entity at a position (BlockInventory.At).

Parameters

Name	Type	Description
pos	BlockPos	The block position.

Returns BlockInventory?: The inventory, or null when the block has none.

HighestBlockY

public int HighestBlockY(int x, int z, HeightMap kind = HeightMap.MotionBlocking)

The y of the highest block of a column (read from the chunk’s height maps, so it is cheap).

Parameters

Name	Type	Description
x	int	Block x.
z	int	Block z.
kind	HeightMap = HeightMap.MotionBlocking	Which surface.

Returns int: The y of the highest matching block, or World.MinY - 1 when the column has none or its chunk is not loaded.

IsBlockLoaded

public bool IsBlockLoaded(BlockPos pos)

Whether the block position is inside a loaded chunk and within the build height.

Parameters

Name	Type	Description
pos	BlockPos	The position.

Returns bool: True when World.GetBlock returns real data for it.

IsChunkLoaded

public bool IsChunkLoaded(int chunkX, int chunkZ)

Whether the chunk is loaded and ready (generated, lit, in memory). Blocks of other chunks read as air and cannot be changed.

Parameters

Name	Type	Description
chunkX	int	The chunk x (block x >> 4).
chunkZ	int	The chunk z.

Returns bool: True when loaded.

PlaySound

public int PlaySound(string sound, Vec3d position, SoundCategory category = SoundCategory.Master, float volume = 1f, float pitch = 1f)

Plays a sound at a position to every player of the dimension who is close enough to hear it (16 blocks, or farther for a volume above 1).

Parameters

Name	Type	Description
sound	string	The sound id, "minecraft:entity.generic.explode", or a sound of a resource pack.
position	Vec3d	Where it comes from.
category	SoundCategory = SoundCategory.Master	The volume slider category.
volume	float = 1f	The volume (1 = normal; above 1 carries farther).
pitch	float = 1f	The pitch (1 = normal, 0.5 - 2).

Returns int: How many players received it.

SetBlock

public bool SetBlock(BlockPos pos, BlockState state, BlockUpdateFlags flags = BlockUpdateFlags.All)

Changes a block, like /setblock: the old block entity goes away, the new block’s placement logic and the neighbour updates run (per flags), the clients are told. No player event fires (this is not a player placing the block); the engine’s own block events (a fire spreading, a piston moving) are the ones the block triggers itself.

Parameters

Name	Type	Description
pos	BlockPos	The position.
state	BlockState	The new state.
flags	BlockUpdateFlags = BlockUpdateFlags.All	What to propagate.

Returns bool: True when the block changed; false when the state was already there, the position is outside the build height or its chunk is not loaded (changes to chunks that are not fully loaded are dropped, load them first with a ChunkTickets ticket).

SetBlock

public bool SetBlock(BlockPos pos, string state, BlockUpdateFlags flags = BlockUpdateFlags.All)

Changes a block to the state parsed from text ("minecraft:oak_stairs[facing=north]").

Parameters

Name	Type	Description
pos	BlockPos	The position.
state	string	The block state text.
flags	BlockUpdateFlags = BlockUpdateFlags.All	What to propagate.

Returns bool: See World.SetBlock.

Throws

• System.FormatException: The text names no block state.

SetBlockEntityData

public bool SetBlockEntityData(BlockPos pos, NbtCompound data, bool merge = true)

Changes the data of a block entity, like /data merge block (or /data modify with the full compound). The clients receive the new data.

Parameters

Name	Type	Description
pos	BlockPos	The position.
data	NbtCompound	The data.
merge	bool = true	True merges the compound into the existing data (nested compounds merge, other tags are replaced); false replaces all data except what the engine keeps (the type and the position).

Returns bool: True when the block entity took the data; false when there is no block entity, it cannot be edited this way or the data is invalid for it.

SetSpawn

public bool SetSpawn(BlockPos pos, float yaw = 0f, float pitch = 0f)

Changes the spawn point (like /setworldspawn; the clients are told the new position of the compass and of the respawn, and it is saved with the world).

Parameters

Name	Type	Description
pos	BlockPos	The block.
yaw	float = 0f	The facing of a player who spawns there.
pitch	float = 0f	The pitch of a player who spawns there.

Returns bool: False in the nether and the end: only the overworld has a world spawn.

SetWeather

public bool SetWeather(WeatherType weather, int? durationTicks = null)

Sets the weather like /weather. The change reaches the players immediately and fires WeatherChangeEvent.

Parameters

Name	Type	Description
weather	WeatherType	The new weather.
durationTicks	int? = null	How long it lasts before the natural cycle takes over, or null for the vanilla random duration.

Returns bool: False in dimensions without weather.

SpawnEntity

public Entity SpawnEntity(string type, Vec3d position, NbtCompound? nbt = null, float yaw = 0f, float pitch = 0f)

Spawns an entity of a type, like /summon. Mobs the engine simulates (zombies, cows, creepers …) get their normal spawn logic: with no NBT their random attributes and equipment are rolled; with NBT the data is applied as given ({Health:5f,CustomName:'"Bob"'}). Item entities (minecraft:item with Item:{id:"minecraft:diamond",count:3}) and experience orbs (minecraft:experience_orb with Value) are supported too. The spawn fires EntitySpawnEvent (reason Plugin) where the entity kind has that event, and a handler may cancel it.

Parameters

Name	Type	Description
type	string	The entity type key, "minecraft:zombie" (the namespace may be left out).
position	Vec3d	Where to spawn it.
nbt	NbtCompound? = null	Entity data, or null.
yaw	float = 0f	The initial yaw in degrees (an NBT Rotation overrides it).
pitch	float = 0f	The initial pitch in degrees.

Returns Entity: The entity (a handle: check Entity.IsAlive before keeping it), or Entity.Null when the type is unknown or cannot be spawned here (a type the engine does not simulate yet, the chunk is not loaded, a monster in peaceful, a handler cancelled it).

SpawnParticle

public int SpawnParticle(string particle, Vec3d position, int count = 1, Vec3d offset = default, float speed = 0f, bool force = false)

Shows a particle effect at a position to the players of the dimension within 32 blocks (512 with force).

Parameters

Name	Type	Description
particle	string	The particle as the /particle command writes it: "flame", "dust 1 0 0 1", "block minecraft:stone".
position	Vec3d	The centre.
count	int = 1	How many (0: a single particle whose motion is the offset and the speed).
offset	Vec3d = default	The random spread on each axis.
speed	float = 0f	The particle speed.
force	bool = false	Show it even when the client’s particle setting is minimal.

Returns int: How many players received it; 0 when the particle text is invalid.

ToString

public override string ToString()

Returns string

TryGetBlock

public bool TryGetBlock(BlockPos pos, out BlockState state)

Reads a block state, saying whether the position was readable.

Parameters

Name	Type	Description
pos	BlockPos	The position.
state	out BlockState	The state, air when the position is not readable.

Returns bool: False for an unloaded chunk or a position outside the build height.

Operators

Member	Description
static bool operator !=(World a, World b)	Inequality.
static bool operator ==(World a, World b)	Equality.

operator !=

public static bool operator !=(World a, World b)

Inequality.

Parameters

Name	Type	Description
a	World
b	World

Returns bool

operator ==

public static bool operator ==(World a, World b)

Equality.

Parameters

Name	Type	Description
a	World
b	World

Returns bool

See also

BlockInventory · BlockPos · BlockState · BlockUpdateFlags · Entity · HeightMap · ItemStack · Location · NbtCompound · Player · SoundCategory · Vec3d · WeatherType