cWorld


Index:
Articles
Classes
Hooks

Quick navigation:
BannerPattern
BossBarColor
BossBarDivisionType
cArrowEntity
cBeaconEntity
cBedEntity
cBlockArea
cBlockEntity
cBlockEntityWithItems
cBlockInfo
cBoat
cBoundingBox
cBrewingstandEntity
cChatColor
cChestEntity
cChunkDesc
cClientHandle
cColor
cCommandBlockEntity
cCompositeChat
cCraftingGrid
cCraftingRecipe
cCryptoHash
cCuboid
cDispenserEntity
cDropperEntity
cDropSpenserEntity
cEnchantments
cEnderCrystal
cEntity
cEntityEffect
cExpBottleEntity
cExpOrb
cFallingBlock
cFile
cFireChargeEntity
cFireworkEntity
cFloater
cFlowerPotEntity
cFurnaceEntity
cGhastFireballEntity
cHangingEntity
cHopperEntity
cIniFile
cInventory
cItem
cItemFrame
cItemGrid
cItems
cJson
cJukeboxEntity
cLeashKnot
cLineBlockTracer
cLuaWindow
cMap
cMapManager
cMobHeadEntity
cMobSpawnerEntity
cMojangAPI
cMonster
cNetwork
cNoteEntity
cObjective
cPainting
cPawn
cPickup
cPlayer
cPlugin
cPluginLua
cPluginManager
cProjectileEntity
cRankManager
cRoot
cScoreboard
cServer
cServerHandle
cSignEntity
cSplashPotionEntity
cStringCompression
cTCPLink
cTeam
cThrownEggEntity
cThrownEnderPearlEntity
cThrownSnowballEntity
cTNTEntity
cUDPEndpoint
cUrlClient
cUrlParser
CustomStatistic
cUUID
cWebAdmin
cWindow
cWitherSkullEntity
cWorld
EffectID
HTTPFormData
HTTPRequest
HTTPTemplateRequest
ItemCategory
lxp
SmokeDirection
sqlite3
StatisticsManager
TakeDamageInfo
tolua
Vector3d
Vector3f
Vector3i
Globals

Contents


cWorld class

cWorld is the game world. It is the hub of all the information managed by individual classes, providing convenient access to them. Cuberite supports multiple worlds in any combination of world types. You can have two overworlds, three nethers etc. To enumerate all world the server provides, use the cRoot:ForEachWorld() function.

The world data is held in individual chunks. Each chunk consists of 16 (x) * 16 (z) * 256 (y) blocks, each block is specified by its block type (8-bit) and block metadata (4-bit). Additionally, each block has two light values calculated - skylight (how much daylight it receives) and blocklight (how much light from light-emissive blocks it receives), both 4-bit.

Each world runs several separate threads used for various housekeeping purposes, the most important of those is the Tick thread. This thread updates the game logic 20 times per second, and it is the thread where all the gameplay actions are evaluated. Liquid physics, entity interactions, player movement etc., all are applied in this thread.

Additional threads include the generation thread (generates new chunks as needed, storage thread (saves and loads chunk from the disk), lighting thread (updates block light values) and the chunksender thread (compresses chunks to send to the clients).

The world provides access to all its players, entities and block entities. Because of multithreading issues, individual objects cannot be retrieved for indefinite handling, but rather must be modified in callbacks, within which they are guaranteed to stay valid.

Physics for individual blocks are handled by the simulators. These will fire in each tick for all blocks that have been scheduled for simulator update ("simulator wakeup"). The simulators include liquid physics, falling blocks, fire spreading and extinguishing and redstone.

Game time is also handled by the world. It provides the time-of-day and the total world age.


Functions

NameParametersReturn valueNotes
AreCommandBlocksEnabled
boolean
Returns whether command blocks are enabled on the (entire) server
BroadcastBlockAction
BlockXnumber
BlockYnumber
BlockZnumber
ActionByte1number
ActionByte2number
BlockTypenumber
ExcludeClientcClientHandle
Broadcasts the BlockAction packet to all clients who have the appropriate chunk loaded (except ExcludeClient). The contents of the packet are specified by the parameters for the call, the blocktype needn't match the actual block that is present in the world data at the specified location. (DEPRECATED)
BroadcastChat
Messagestring
ExcludeClientcClientHandle
ChatPrefixeMessageType
Sends the Message to all players in this world, except the optional ExcludeClient. No formatting is done by the server.
BroadcastChatDeath
Messagestring
ExcludeClientcClientHandle
Prepends Gray [DEATH] / colours entire text (depending on ShouldUseChatPrefixes()) and broadcasts message. For when a player dies.
BroadcastChatFailure
Messagestring
ExcludeClientcClientHandle
Prepends Rose [INFO] / colours entire text (depending on ShouldUseChatPrefixes()) and broadcasts message. For a command that failed to run because of insufficient permissions, etc.
BroadcastChatFatal
Messagestring
ExcludeClientcClientHandle
Prepends Red [FATAL] / colours entire text (depending on ShouldUseChatPrefixes()) and broadcasts message. For a plugin that crashed, or similar.
BroadcastChatInfo
Messagestring
ExcludeClientcClientHandle
Prepends Yellow [INFO] / colours entire text (depending on ShouldUseChatPrefixes()) and broadcasts message. For informational messages, such as command usage.
BroadcastChatSuccess
Messagestring
ExcludeClientcClientHandle
Prepends Green [INFO] / colours entire text (depending on ShouldUseChatPrefixes()) and broadcasts message. For success messages.
BroadcastChatWarning
Messagestring
ExcludeClientcClientHandle
Prepends Rose [WARN] / colours entire text (depending on ShouldUseChatPrefixes()) and broadcasts message. For concerning events, such as plugin reload etc.
BroadcastEntityAnimation
TargetEntitycEntity
Animationnumber
ExcludeClientcClientHandle
Sends an animation of an entity to all clienthandles (except ExcludeClient if given)
BroadcastParticleEffect
ParticleNamestring
SourcePosVector3f
OffsetVector3f
ParticleDatanumber
ParticleAmountnumber
ExcludeClientcClientHandle
Spawns the specified particles to all players in the world exept the optional ExeptClient. A list of available particles by thinkofdeath can be found Here
BroadcastPlayerListHeaderFooter
HeadercCompositeChat
FootercCompositeChat
(undocumented)
BroadcastSoundEffect
SoundNamestring
Xnumber
Ynumber
Znumber
Volumenumber
Pitchnumber
ExcludeClientcClientHandle
Sends the specified sound effect to all players in this world, except the optional ExceptClient (DEPRECATED, use vector-parametered version instead)
BroadcastSoundParticleEffect
EffectIDnumber
SourcePosVector3i
EffectDatastring
ExcludeClientcClientHandle
Sends the specified effect to all players in this world, except the optional ExceptClient
CastThunderbolt
Xnumber
Ynumber
Znumber
Creates a thunderbolt at the specified coords (DEPRECATED, use vector-parametered version instead)
ChangeWeather Forces the weather to change in the next game tick. Weather is changed according to the normal rules: wSunny <-> wRain <-> wStorm
ChunkStay
ChunkCoordTabletable
OnChunkAvailablefunction
OnAllChunksAvailablefunction
Queues the specified chunks to be loaded or generated and calls the specified callbacks once they are loaded. ChunkCoordTable is an arra-table of chunk coords, each coord being a table of 2 numbers: { {Chunk1x, Chunk1z}, {Chunk2x, Chunk2z}, ...}. When any of those chunks are made available (including being available at the start of this call), the OnChunkAvailable() callback is called. When all the chunks are available, the OnAllChunksAvailable() callback is called. The function signatures are:
function OnChunkAvailable(ChunkX, ChunkZ)
function OnAllChunksAvailable()
All return values from the callbacks are ignored.
CreateProjectile
Xnumber
Ynumber
Znumber
ProjectileKindeKind
CreatorcEntity
Originating ItemcItem
SpeedVector3d
Creates a new projectile of the specified kind at the specified coords. The projectile's creator is set to Creator (may be nil). The item that created the projectile entity, commonly the player's currently equipped item, is used at present for fireworks to correctly set their entity metadata. It is not used for any other projectile. Optional speed indicates the initial speed for the projectile.
DigBlock
BlockPosVector3i
DiggercEntity
boolean
Replaces the specified block with air, without dropping the usual pickups for the block. Wakes up the simulators for the block and its neighbors. The optional Digger parameter specifies the entity who dug the block, usually a player. Returns true on success, or false if the chunk is not loaded or invalid coords. See also DropBlockAsPickups() for the version that drops pickups.
DigBlock
Xnumber
Ynumber
Znumber
DiggercEntity
boolean
Replaces the specified block with air, without dropping the usual pickups for the block. Wakes up the simulators for the block and its neighbors. The optional Digger parameter specifies the entity who dug the block, usually a player. Returns true on success, or false if the chunk is not loaded or invalid coords. See also DropBlockAsPickups() for the version that drops pickups.
DoExplosionAt
Forcenumber
Xnumber
Ynumber
Znumber
CanCauseFireboolean
SourceeExplosionSource
SourceDataany
Creates an explosion of the specified relative force in the specified position. If CanCauseFire is set, the explosion will set blocks on fire, too. The Source parameter specifies the source of the explosion, one of the esXXX constants. The SourceData parameter is specific to each source type, usually it provides more info about the source.
DoWithBeaconAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a beacon at the specified coords, calls the CallbackFunction with the cBeaconEntity parameter representing the beacon. The CallbackFunction has the following signature:
function Callback(BeaconEntity)
The function returns false if there is no beacon, or if there is, it returns the bool value that the callback has returned.
DoWithBedAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a bed at the specified coords, calls the CallbackFunction with the cBedEntity parameter representing the bed. The CallbackFunction has the following signature:
function Callback(cBedEntity)
The function returns false if there is no bed, or if there is, it returns the bool value that the callback has returned.
DoWithBlockEntityAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a block entity at the specified coords, calls the CallbackFunction with the cBlockEntity parameter representing the block entity. The CallbackFunction has the following signature:
function Callback(BlockEntity)
The function returns false if there is no block entity, or if there is, it returns the bool value that the callback has returned.
DoWithBrewingstandAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a brewingstand at the specified coords, calls the CallbackFunction with the cBrewingstandEntity parameter representing the brewingstand. The CallbackFunction has the following signature:
function Callback(cBrewingstandEntity)
The function returns false if there is no brewingstand, or if there is, it returns the bool value that the callback has returned.
DoWithChestAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a chest at the specified coords, calls the CallbackFunction with the cChestEntity parameter representing the chest. The CallbackFunction has the following signature:
function Callback(ChestEntity)
The function returns false if there is no chest, or if there is, it returns the bool value that the callback has returned.
DoWithCommandBlockAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a command block at the specified coords, calls the CallbackFunction with the cCommandBlockEntity parameter representing the command block. The CallbackFunction has the following signature:
function Callback(CommandBlockEntity)
The function returns false if there is no command block, or if there is, it returns the bool value that the callback has returned.
DoWithDispenserAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a dispenser at the specified coords, calls the CallbackFunction with the cDispenserEntity parameter representing the dispenser. The CallbackFunction has the following signature:
function Callback(DispenserEntity)
The function returns false if there is no dispenser, or if there is, it returns the bool value that the callback has returned.
DoWithDropSpenserAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a dropper or a dispenser at the specified coords, calls the CallbackFunction with the cDropSpenserEntity parameter representing the dropper or dispenser. The CallbackFunction has the following signature:
function Callback(DropSpenserEntity)
Note that this can be used to access both dispensers and droppers in a similar way. The function returns false if there is neither dispenser nor dropper, or if there is, it returns the bool value that the callback has returned.
DoWithDropperAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a dropper at the specified coords, calls the CallbackFunction with the cDropperEntity parameter representing the dropper. The CallbackFunction has the following signature:
function Callback(DropperEntity)
The function returns false if there is no dropper, or if there is, it returns the bool value that the callback has returned.
DoWithEntityByID
EntityIDnumber
CallbackFunctionfunction
boolean
If an entity with the specified ID exists, calls the callback with the cEntity parameter representing the entity. The CallbackFunction has the following signature:
function Callback(Entity)
The function returns false if the entity was not found, and it returns the same bool value that the callback has returned if the entity was found.
DoWithFlowerPotAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a flower pot at the specified coords, calls the CallbackFunction with the cFlowerPotEntity parameter representing the flower pot. The CallbackFunction has the following signature:
function Callback(FlowerPotEntity)
The function returns false if there is no flower pot, or if there is, it returns the bool value that the callback has returned.
DoWithFurnaceAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a furnace at the specified coords, calls the CallbackFunction with the cFurnaceEntity parameter representing the furnace. The CallbackFunction has the following signature:
function Callback(FurnaceEntity)
The function returns false if there is no furnace, or if there is, it returns the bool value that the callback has returned.
DoWithHopperAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a hopper at the specified coords, calls the CallbackFunction with the cHopperEntity parameter representing the hopper. The CallbackFunction has the following signature:
function Callback(cHopperEntity)
The function returns false if there is no hopper, or if there is, it returns the bool value that the callback has returned.
DoWithMobHeadAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a mob head at the specified coords, calls the CallbackFunction with the cMobHeadEntity parameter representing the furnace. The CallbackFunction has the following signature:
function Callback(MobHeadEntity)
The function returns false if there is no mob head, or if there is, it returns the bool value that the callback has returned.
DoWithNearestPlayer
PositionVector3d
RangeLimitnumber
CallbackFunctionfunction
CheckLineOfSightboolean
IgnoreSpectatorboolean
boolean
Calls the specified callback function with the player nearest to the specified position as its parameter, if they are still within the range limit. The CallbackFunction has the following signature:
function Callback(Player)
The function returns false if the player was not found, or whatever bool value the callback returned if the player was found.
DoWithNoteBlockAt
BlockXnumber
BlockYnumber
BlockZnumber
CallbackFunctionfunction
boolean
If there is a note block at the specified coords, calls the CallbackFunction with the cNoteEntity parameter representing the note block. The CallbackFunction has the following signature:
function Callback(NoteEntity)
The function returns false if there is no note block, or if there is, it returns the bool value that the callback has returned.
DoWithPlayer
PlayerNamestring
CallbackFunctionfunction
boolean
If there is a player of the specified name (exact match), calls the CallbackFunction with the cPlayer parameter representing the player. The CallbackFunction has the following signature:
function Callback(Player)
The function returns false if the player was not found, or whatever bool value the callback returned if the player was found.
DoWithPlayerByUUID
PlayerUUIDcUUID
CallbackFunctionfunction
boolean
If there is the player with the uuid, calls the CallbackFunction with the cPlayer parameter representing the player. The CallbackFunction has the following signature:
function Callback(Player)
The function returns false if the player was not found, or whatever bool value the callback returned if the player was found.
DropBlockAsPickups
BlockPosVector3i
DiggercEntity
ToolcItem
IsSuccessboolean
Digs up the specified block and spawns the appropriate pickups for it. The optional Digger parameter specifies the entity who dug the block, usually a player. The optional Tool parameter specifies the tool used to dig the block, not present means an empty hand. Returns true on success, false if the chunk is not present. See also DigBlock() for the pickup-less version.
FastSetBlock
BlockCoordsVector3i
BlockTypenumber
BlockMetanumber
Sets the block at the specified coords, without waking up the simulators or replacing the block entities for the previous block type. Do not use if the block being replaced has a block entity tied to it!
FastSetBlock
BlockXnumber
BlockYnumber
BlockZnumber
BlockTypenumber
BlockMetanumber
Sets the block at the specified coords, without waking up the simulators or replacing the block entities for the previous block type. Do not use if the block being replaced has a block entity tied to it! OBSOLETE, use the vector-based overload instead.
FindAndDoWithPlayer
PlayerNamestring
CallbackFunctionfunction
boolean
Calls the given callback function for the player with the name best matching the name string provided.
This function is case-insensitive and will match partial names.
Returns false if player not found or there is ambiguity, true otherwise. The CallbackFunction has the following signature:
function Callback(Player)
ForEachBlockEntityInChunk
ChunkXnumber
ChunkZnumber
CallbackFunctionfunction
boolean
Calls the specified callback for each block entity in the chunk. Returns true if all block entities in the chunk have been processed (including when there are zero block entities), or false if the callback has aborted the enumeration by returning true. The CallbackFunction has the following signature:
function Callback(BlockEntity)
The callback should return false or no value to continue with the next block entity, or true to abort the enumeration.
ForEachBrewingstandInChunk
ChunkXnumber
ChunkZnumber
CallbackFunctionfunction
boolean
Calls the specified callback for each brewingstand in the chunk. Returns true if all brewingstands in the chunk have been processed (including when there are zero brewingstands), or false if the callback has aborted the enumeration by returning true. The CallbackFunction has the following signature:
function Callback(cBrewingstandEntity)
The callback should return false or no value to continue with the next brewingstand, or true to abort the enumeration.
ForEachChestInChunk
ChunkXnumber
ChunkZnumber
CallbackFunctionfunction
boolean
Calls the specified callback for each chest in the chunk. Returns true if all chests in the chunk have been processed (including when there are zero chests), or false if the callback has aborted the enumeration by returning true. The CallbackFunction has the following signature:
function Callback(ChestEntity)
The callback should return false or no value to continue with the next chest, or true to abort the enumeration.
ForEachEntity
CallbackFunctionfunction
boolean
Calls the specified callback for each entity in the loaded world. Returns true if all the entities have been processed (including when there are zero entities), or false if the callback function has aborted the enumeration by returning true. The callback function has the following signature:
function Callback(Entity)
The callback should return false or no value to continue with the next entity, or true to abort the enumeration.
ForEachEntityInBox
BoxcBoundingBox
CallbackFunctionfunction
boolean
Calls the specified callback for each entity in the specified bounding box. Returns true if all the entities have been processed (including when there are zero entities), or false if the callback function has aborted the enumeration by returning true. If any chunk within the bounding box is not valid, it is silently skipped without any notification. The callback function has the following signature:
function Callback(Entity)
The callback should return false or no value to continue with the next entity, or true to abort the enumeration.
ForEachEntityInChunk
ChunkXnumber
ChunkZnumber
CallbackFunctionfunction
boolean
Calls the specified callback for each entity in the specified chunk. Returns true if all the entities have been processed (including when there are zero entities), or false if the chunk is not loaded or the callback function has aborted the enumeration by returning true. The callback function has the following signature:
function Callback(Entity)
The callback should return false or no value to continue with the next entity, or true to abort the enumeration.
ForEachFurnaceInChunk
ChunkXnumber
ChunkZnumber
CallbackFunctionfunction
boolean
Calls the specified callback for each furnace in the chunk. Returns true if all furnaces in the chunk have been processed (including when there are zero furnaces), or false if the callback has aborted the enumeration by returning true. The CallbackFunction has the following signature:
function Callback(FurnaceEntity)
The callback should return false or no value to continue with the next furnace, or true to abort the enumeration.
ForEachLoadedChunk
CallbackFunctionfunction
boolean
Calls the specified callback for each loaded chunk in the world. Returns true if all chunks have been processed, or false if the callback has aborted the enumeration by returning true. The CallbackFunction has the following signature:
function Callback(ChunkX, ChunkZ)
The callback should return false or no value to continue with the next chunk, or true to abort the enumeration.
ForEachPlayer
CallbackFunctionfunction
boolean
Calls the specified callback for each player in the loaded world. Returns true if all the players have been processed (including when there are zero players), or false if the callback function has aborted the enumeration by returning true. The callback function has the following signature:
function Callback(Player)
The callback should return false or no value to continue with the next player, or true to abort the enumeration.
GenerateChunk
ChunkXnumber
ChunkZnumber
Queues the specified chunk in the chunk generator. Ignored if the chunk is already generated (use RegenerateChunk() to force chunk re-generation).
GetBiomeAt
BlockXnumber
BlockZnumber
eBiomeEMCSBiome
Returns the biome at the specified coords. Reads the biome from the chunk, if it is loaded, otherwise it uses the chunk generator to provide the biome value.
GetBlock
BlockXnumber
BlockYnumber
BlockZnumber
BLOCKTYPEnumber
Returns the block type of the block at the specified coords, or 0 if the appropriate chunk is not loaded. OBSOLETE, use the vector-based overload instead.
GetBlock
BlockCoordsVector3i
BLOCKTYPEnumber
Returns the block type of the block at the specified coords, or 0 if the appropriate chunk is not loaded.
GetBlockBlockLight
PosVector3i
number
Returns the amount of block light at the specified coords, or 0 if the appropriate chunk is not loaded.
GetBlockBlockLight
BlockXnumber
BlockYnumber
BlockZnumber
number
Returns the amount of block light at the specified coords, or 0 if the appropriate chunk is not loaded. OBSOLETE, use the vector-based overload instead.
GetBlockInfo
BlockXnumber
BlockYnumber
BlockZnumber
IsBlockValidboolean
BlockTypenumber
BlockMetanumber
BlockSkyLightnumber
BlockBlockLightnumber
Returns the complete block info for the block at the specified coords. The first value specifies if the block is in a valid loaded chunk, the other values are valid only if BlockValid is true.
GetBlockMeta
BlockCoordsVector3i
number
Returns the block metadata of the block at the specified coords, or 0 if the appropriate chunk is not loaded.
GetBlockMeta
BlockXnumber
BlockYnumber
BlockZnumber
number
Returns the block metadata of the block at the specified coords, or 0 if the appropriate chunk is not loaded. OBSOLETE, use the vector-based overload instead.
GetBlockSkyLight
BlockXnumber
BlockYnumber
BlockZnumber
number
Returns the block skylight of the block at the specified coords, or 0 if the appropriate chunk is not loaded.
GetBlockTypeMeta
BlockXnumber
BlockYnumber
BlockZnumber
IsBlockValidboolean
BlockTypenumber
BlockMetanumber
Returns the block type and metadata for the block at the specified coords. The first value specifies if the block is in a valid loaded chunk, the other values are valid only if BlockValid is true.
GetDataPath
string
Returns the path to the root of the world data.
GetDefaultWeatherInterval
WeathereWeather
number
Returns the default weather interval for the specific weather type. Returns -1 for any unknown weather.
GetDimension
eDimension
Returns the dimension of the world - dimOverworld, dimNether or dimEnd.
GetGameMode
eGameMode
Returns the gamemode of the world - gmSurvival, gmCreative or gmAdventure.
GetGeneratorQueueLength
number
Returns the number of chunks that are queued in the chunk generator.
GetHeight
BlockXnumber
BlockZnumber
number
DEPRECATED, use TryGetHeight instead. Returns the maximum height of the particular block column in the world. If the chunk is not loaded, this function used to block until the chunk was loaded, leading to possible deadlock. Now it returns 0 instead.
GetIniFileName
string
Returns the name of the world.ini file that the world uses to store the information.
GetLightingQueueLength
number
Returns the number of chunks in the lighting thread's queue.
GetLinkedEndWorldName
string
Returns the name of the end world this world is linked to.
GetLinkedNetherWorldName
string
Returns the name of the Netherworld linked to this world.
GetLinkedOverworldName
string
Returns the name of the world this world is linked to.
GetMapManager
cMapManager
Returns the MapManager object used by this world.
GetMaxCactusHeight
number
Returns the configured maximum height to which cacti will grow naturally.
GetMaxNetherPortalHeight
number
Returns the maximum height for a nether portal
GetMaxNetherPortalWidth
number
Returns the maximum width for a nether portal
GetMaxSugarcaneHeight
number
Returns the configured maximum height to which sugarcane will grow naturally.
GetMaxViewDistance
number
Returns the maximum viewdistance that players can see in this world. The view distance is the amount of chunks around the player that the player can see.
GetMinNetherPortalHeight
number
Returns the minimum height for a nether portal
GetMinNetherPortalWidth
number
Returns the minimum width for a nether portal
GetName
string
Returns the name of the world, as specified in the settings.ini file.
GetNumChunks
number
Returns the number of chunks currently loaded.
GetNumUnusedDirtyChunks
number
Returns the number of unused dirty chunks. That's the number of chunks that we can save and then unload.
GetScoreBoard
cScoreboard
Returns the Scoreboard object used by this world.
GetSeed
number
Returns the seed of the world.
GetSignLines
BlockXnumber
BlockYnumber
BlockZnumber
IsValidboolean
Line1string
Line2string
Line3string
Line4string
Returns true and the lines of a sign at the specified coords, or false if there is no sign at the coords.
GetSpawnPos
Vector3d
Returns the default spawn position
GetSpawnX
number
Returns the X coord of the default spawn
GetSpawnY
number
Returns the Y coord of the default spawn
GetSpawnZ
number
Returns the Z coord of the default spawn
GetStorageLoadQueueLength
number
Returns the number of chunks queued up for loading
GetStorageSaveQueueLength
number
Returns the number of chunks queued up for saving
GetTNTShrapnelLevel
ShrapnelLeveleShrapnelLevel
Returns the shrapnel level, representing the block types that are propelled outwards following an explosion. Based on this value and a random picker, blocks are selectively converted to physics entities (FallingSand) and flung outwards.
GetTicksUntilWeatherChange
number
Returns the number of ticks that will pass before the weather is changed
GetTimeOfDay
number
Returns the number of ticks that have passed from the sunrise, 0 .. 24000.
GetWeather
eWeather
Returns the current weather in the world (wSunny, wRain, wStorm). To check for weather, use IsWeatherXXX() functions instead.
GetWorldAge
number
Returns the total age of the world, in ticks. The age always grows, cannot be set by plugins and is unrelated to TimeOfDay.
GrowPlantAt
BlockPosVector3i
NumStagesnumber
number
Grows the plant at the specified block by the specified number of stages. Returns the number of stages actually grown. Returns zero for non-growable blocks.
GrowRipePlant
BlockPosVector3i
boolean
Grows the plant at the specified coords to maturity. Returns true if the plant was grown, false if not.
GrowTree
BlockPosVector3i
boolean
Grows a tree based at the specified coords. If there is a sapling there, grows the tree based on that sapling, otherwise chooses a tree image based on the biome. Returns true if the tree was grown, false if not (invalid chunk, insufficient space)
GrowTreeByBiome
BlockPosVector3i
boolean
Grows a tree based at the specified coords. The tree type is picked from types available for the biome at those coords. Returns true if the tree was grown, false if not (invalid chunk, insufficient space)
GrowTreeFromSapling
BlockPosVector3i
boolean
Grows a tree based at the specified coords. The tree type is determined from the sapling meta. If the sapling is part of a 2x2 sapling area, grows a large tree. Returns true if the tree was grown, false if not (invalid chunk, insufficient space)
IsBlockDirectlyWatered
BlockXnumber
BlockYnumber
BlockZnumber
boolean
Returns true if the specified block has a water block right next to it (on the X/Z axes)
IsDaylightCycleEnabled
boolean
Returns true if the daylight cycle is enabled.
IsDeepSnowEnabled
boolean
Returns whether the configuration has DeepSnow enabled.
IsFarmlandTramplingEnabled
boolean
Returns true if farmland trampling is enabled.
IsGameModeAdventure
boolean
Returns true if the current gamemode is gmAdventure.
IsGameModeCreative
boolean
Returns true if the current gamemode is gmCreative.
IsGameModeSpectator
boolean
Returns true if the current gamemode is gmSpectator.
IsGameModeSurvival
boolean
Returns true if the current gamemode is gmSurvival.
IsPVPEnabled
boolean
Returns whether PVP is enabled in the world settings.
IsSavingEnabled
boolean
Returns whether or not saving chunk data is enabled. If disabled, the world will keep dirty chunks in memory forever, and will simply regenerate non-dirty chunks that are unloaded.
IsSlimeChunk
ChunkXnumber
ChunkZnumber
boolean
Returns whether slimes can spawn in the chunk.
IsTrapdoorOpen
BlockXnumber
BlockYnumber
BlockZnumber
boolean
Returns false if there is no trapdoor there or if the block isn't a trapdoor or if the chunk wasn't loaded. Returns true if trapdoor is open.
IsWeatherRain
boolean
Returns true if the current weather is rainy.
IsWeatherRainAt
BlockXnumber
BlockZnumber
boolean
Returns true if it is rainy at the specified location. This takes into account biomes.
IsWeatherStorm
boolean
Returns true if the current weather is stormy.
IsWeatherStormAt
BlockXnumber
BlockZnumber
boolean
Returns true if it is stormy at the specified location. This takes into account biomes.
IsWeatherSunny
boolean
Returns true if the current weather is sunny.
IsWeatherSunnyAt
BlockXnumber
BlockZnumber
boolean
Returns true if it is sunny at the specified location. This takes into account biomes.
IsWeatherWet
boolean
Returns true if the world currently has any precipitation - rain, storm or snow.
IsWeatherWetAt
BlockXnumber
BlockZnumber
boolean
Returns true if it is raining or storming at the specified location. This takes into account biomes.
IsWeatherWetAtXYZ
PosVector3i
boolean
Returns true if the specified location has wet weather (rain or storm), using the same logic as IsWeatherWetAt, except that any rain-blocking blocks above the specified position will block the precipitation and this function will return false. Note if the chunk is unloaded then the weather state for the world will be returned.
PickupsFromBlock
BlockPosVector3i
DiggercEntity
ToolcItem
ItemscItems
Returns all the pickups that would result if the Digger dug up the block at BlockPos using Tool. Digger is usually a cPlayer, but can be nil for natural causes. Tool is usually the equipped item, can be nil for empty hand. Returns an empty cItems object if the chunk is not present.
PrepareChunk
ChunkXnumber
ChunkZnumber
Callbackfunction
Queues the chunk for preparing - making sure that it's generated and lit. It is legal to call with no callback. The callback function has the following signature:
function Callback(ChunkX, ChunkZ)
QueueBlockForTick
BlockXnumber
BlockYnumber
BlockZnumber
TicksToWaitnumber
Queues the specified block to be ticked after the specified number of gameticks.
QueueSaveAllChunks Queues all chunks to be saved in the world storage thread
QueueTask
TaskFunctionfunction
Queues the specified function to be executed in the tick thread. This is the primary means of interaction with a cWorld from the WebAdmin page handlers (see WebWorldThreads). The function signature is
function(World)
All return values from the function are ignored. Note that this function is actually called *after* the QueueTask() function returns. Note that it is unsafe to store references to Cuberite objects, such as entities, across from the caller to the task handler function; store the EntityID instead.
QueueUnloadUnusedChunks Queues a cTask that unloads chunks that are no longer needed and are saved.
RegenerateChunk
ChunkXnumber
ChunkZnumber
Queues the specified chunk to be re-generated, overwriting the current data. To queue a chunk for generating only if it doesn't exist, use the GenerateChunk() instead.
ScheduleTask
DelayTicksnumber
TaskFunctionfunction
Queues the specified function to be executed in the world's tick thread after a the specified number of ticks. This enables operations to be queued for execution in the future. The function signature is
function(World)
All return values from the function are ignored. Note that it is unsafe to store references to Cuberite objects, such as entities, across from the caller to the task handler function; store the EntityID instead.
SendBlockTo
BlockXnumber
BlockYnumber
BlockZnumber
PlayercPlayer
Sends the block at the specified coords to the specified player's client, as an UpdateBlock packet.
SetAreaBiome
MinXnumber
MaxXnumber
MinZnumber
MaxZnumber
BiomeEMCSBiome
boolean
Sets the biome in the rectangular area specified. Returns true if successful, false if any of the chunks were unloaded.
SetAreaBiome
CuboidcCuboid
BiomeEMCSBiome
boolean
Sets the biome in the cuboid specified. Returns true if successful, false if any of the chunks were unloaded. The cuboid needn't be sorted.
SetBiomeAt
BlockXnumber
BlockZnumber
BiomeEMCSBiome
boolean
Sets the biome at the specified block coords. Returns true if successful, false otherwise.
SetBlock
BlockXnumber
BlockYnumber
BlockZnumber
BlockTypenumber
BlockMetanumber
Sets the block at the specified coords, replaces the block entities for the previous block type, creates a new block entity for the new block, if appropriate, and wakes up the simulators. This is the preferred way to set blocks, as opposed to FastSetBlock(), which is only to be used under special circumstances.
SetBlockMeta
BlockCoordsVector3i
BlockMetanumber
Sets the meta for the block at the specified coords. Any call to SetBlockMeta will not generate a simulator update (water, lava, redstone), consider using SetBlock instead.
SetBlockMeta
BlockXnumber
BlockYnumber
BlockZnumber
BlockMetanumber
Sets the meta for the block at the specified coords. Any call to SetBlockMeta will not generate a simulator update (water, lava, redstone), consider using SetBlock instead.
SetChunkAlwaysTicked
ChunkXnumber
ChunkZnumber
IsAlwaysTickedboolean
Sets the chunk to always be ticked and loaded even when it doesn't contain any clients. IsAlwaysTicked set to true turns forced ticking on, set to false turns it off. Every call with 'true' should be paired with a later call with 'false', otherwise the ticking won't stop. Multiple actions can request ticking independently, the ticking will continue until the last call with 'false'.
SetCommandBlockCommand
BlockXnumber
BlockYnumber
BlockZnumber
Commandstring
boolean
Sets the command to be executed in a command block at the specified coordinates. Returns if command was changed.
SetCommandBlocksEnabled
AreEnabledboolean
Sets whether command blocks should be enabled on the (entire) server.
SetDaylightCycleEnabled
IsEnabledboolean
Starts or stops the daylight cycle.
SetLinkedEndWorldName
WorldNamestring
Sets the name of the world that the end portal should link to.
SetLinkedNetherWorldName
WorldNamestring
Sets the name of the world that the nether portal should link to.
SetLinkedOverworldName
WorldNamestring
Sets the name of the world that the nether portal should link to?
SetMaxNetherPortalHeight
Heightnumber
Sets the maximum height for a nether portal
SetMaxNetherPortalWidth
Widthnumber
Sets the maximum width for a nether portal
SetMaxViewDistance
MaxViewDistancenumber
Sets the maximum viewdistance of the players in the world. This maximum takes precedence over each player's ViewDistance setting.
SetMinNetherPortalHeight
Heightnumber
Sets the minimum height for a nether portal
SetMinNetherPortalWidth
Widthnumber
Sets the minimum width for a nether portal
SetNextBlockTick
BlockXnumber
BlockYnumber
BlockZnumber
DEPRECATED, use SetNextBlockToTick() instead.
SetNextBlockToTick
BlockPosVector3i
Requests that the specified block be ticked at the start of the next world tick. Only one block per chunk can be queued this way; a second call to the same chunk overwrites the previous call.
SetSavingEnabled
SavingEnabledboolean
Sets whether saving chunk data is enabled. If disabled, dirty chunks will stay in memory forever, which may cause performance and stability issues.
SetShouldUseChatPrefixes
ShouldUseChatPrefixesboolean
Sets whether coloured chat prefixes such as [INFO] is used with the SendMessageXXX() or BroadcastChatXXX(), or simply the entire message is coloured in the respective colour.
SetSignLines
BlockXnumber
BlockYnumber
BlockZnumber
Line1string
Line2string
Line3string
Line4string
PlayercPlayer
Sets the sign text at the specified coords. The sign-updating hooks are called for the change. The Player parameter is used to indicate the player from whom the change has come, it may be nil.
SetSpawn
Xnumber
Ynumber
Znumber
boolean
Sets the default spawn at the specified coords. Returns false if the new spawn couldn't be stored in the INI file.
SetTNTShrapnelLevel
ShrapnelLeveleShrapnelLevel
Sets the Shrapnel level of the world.
SetTicksUntilWeatherChange
NumTicksnumber
Sets the number of ticks after which the weather will be changed.
SetTimeOfDay
TimeOfDayTicksnumber
Sets the time of day, expressed as number of ticks past sunrise, in the range 0 .. 24000.
SetTrapdoorOpen
BlockXnumber
BlockYnumber
BlockZnumber
IsOpenboolean
boolean
Opens or closes a trapdoor at the specific coordinates. Returns true on success, false if there is no trapdoor or it's already in the requested state.
SetWeather
WeathereWeather
Sets the current weather (wSunny, wRain, wStorm) and resets the TicksUntilWeatherChange to the default value for the new weather. The normal weather-changing hooks are called for the change.
ShouldBroadcastAchievementMessages
boolean
Returns true if the server should broadcast achievement messages in this world.
ShouldBroadcastDeathMessages
boolean
Returns true if the server should broadcast death messages in this world.
ShouldLavaSpawnFire
boolean
Returns true if the world is configured to spawn fires near lava (world.ini: [Physics].ShouldLavaSpawnFire value)
ShouldUseChatPrefixes
boolean
Returns whether coloured chat prefixes are prepended to chat messages or the entire message is simply coloured.
SpawnBoat
PositionVector3d
MaterialeMaterial
EntityIDnumber
Spawns a boat at the specific coordinates. Returns the EntityID of the new boat, or cEntity#INVALID_ID if no boat was created.
SpawnBoat
Xnumber
Ynumber
Znumber
MaterialeMaterial
EntityIDnumber
Spawns a boat at the specific coordinates. Returns the EntityID of the new boat, or cEntity#INVALID_ID if no boat was created. (DEPRECATED, use vector-parametered version)
SpawnEnderCrystal
PosVector3d
ShowBottomboolean
EntityIDnumber
Spawns an ender crystal at the specified coords. Returns the EntityID of the new ender crystal, or cEntity#INVALID_ID if no ender crystal was created.
SpawnExperienceOrb
Xnumber
Ynumber
Znumber
Rewardnumber
EntityIDnumber
Spawns an experience orb at the specified coords, with the given reward. Returns the EntityID of the new experience orb, or cEntity#INVALID_ID if no experience orb was created.
SpawnFallingBlock
Xnumber
Ynumber
Znumber
BlockTypenumber
BlockMetanumber
EntityIDnumber
OBSOLETE, use the Vector3-based overloads instead. Spawns a Falling Block entity at the specified coords with the given block type/meta. Returns the EntityID of the new falling block, or cEntity#INVALID_ID if no falling block was created.
SpawnFallingBlock
BlockPosVector3i
BlockTypenumber
BlockMetanumber
EntityIDnumber
Spawns a Falling Block entity in the middle of the specified block, with the given block type/meta. Returns the EntityID of the new falling block, or cEntity#INVALID_ID if no falling block was created.
SpawnFallingBlock
PosVector3d
BlockTypenumber
BlockMetanumber
EntityIDnumber
Spawns a Falling Block entity at exactly the specified coords, with the given block type/meta. Returns the EntityID of the new falling block, or cEntity#INVALID_ID if no falling block was created.
SpawnItemPickup
PosXnumber
PosYnumber
PosZnumber
ItemcItem
SpeedXnumber
SpeedYnumber
SpeedZnumber
LifetimeTicksnumber
CanCombineboolean
EntityIDnumber
Creates a single pickup entity of the given item at the given position with the given speed, and returns the entities unique ID.
SpawnItemPickups
PickupscItems
Xnumber
Ynumber
Znumber
FlyAwaySpeednumber
IsPlayerCreatedboolean
Spawns the specified pickups at the position specified. The FlyAwaySpeed is a coefficient (default: 1) used to initialize the random speed in which the pickups fly away from the spawn position. The IsPlayerCreated parameter (default: false) is used to initialize the created cPickup object's IsPlayerCreated value.
SpawnItemPickups
PickupscItems
Xnumber
Ynumber
Znumber
SpeedXnumber
SpeedYnumber
SpeedZnumber
IsPlayerCreatedboolean
Spawns the specified pickups at the position specified. All the pickups fly away from the spawn position using the specified speed. The IsPlayerCreated parameter (default: false) is used to initialize the created cPickup object's IsPlayerCreated value.
SpawnMinecart
Xnumber
Ynumber
Znumber
MinecartTypenumber
ItemcItem
BlockHeightnumber
EntityIDnumber
Spawns a minecart at the specific coordinates. MinecartType is the item type of the minecart. If the minecart is an empty minecart then the given Item (default: empty) is the block to be displayed inside the minecart, and BlockHeight (default: 1) is the relative distance of the block from the minecart. Returns the EntityID of the new minecart, or cEntity#INVALID_ID if no minecart was created.
SpawnMob
Xnumber
Ynumber
Znumber
MonsterTypeeMonsterType
IsBabyboolean
EntityIDnumber
Spawns the specified type of mob at the specified coords. If the Baby parameter is true, the mob will be a baby. Returns the EntityID of the created entity, or cEntity#INVALID_ID on failure.
SpawnPrimedTNT
Xnumber
Ynumber
Znumber
FuseTicksnumber
InitialVelocityCoeffnumber
EntityIDnumber
Spawns a primed TNT entity at the specified coords, with the given fuse ticks. The entity gets a random speed multiplied by the InitialVelocityCoeff, 1 being the default value. Returns the EntityID of the new spawned primed tnt, or cEntity#INVALID_ID if no primed tnt was created. (DEPRECATED, use vector-parametered version)
SpawnPrimedTNT
PositionVector3d
FuseTicksnumber
InitialVelocityCoeffnumber
ShouldPlayFuseSoundboolean
EntityIDnumber
Spawns a primed TNT entity at the specified coords, with the given fuse ticks. The entity gets a random speed multiplied by the InitialVelocityCoeff, 1 being the default value. Returns the EntityID of the new spawned primed tnt, or cEntity#INVALID_ID if no primed tnt was created.
SpawnSplitExperienceOrbs
PositionVector3d
Rewardnumber
EntityIDtable
Spawns experience orbs of the specified total value at the given location. The orbs' values are split according to regular Minecraft rules. Returns an array-table of UniqueID of all the orbs.
TryGetHeight
BlockXnumber
BlockZnumber
IsValidboolean
Heightnumber
Returns true and height of the highest non-air block if the chunk is loaded, or false otherwise.
UpdateSign
BlockXnumber
BlockYnumber
BlockZnumber
Line1string
Line2string
Line3string
Line4string
PlayercPlayer
(DEPRECATED) Please use SetSignLines().
UseBlockEntity
PlayercPlayer
BlockXnumber
BlockYnumber
BlockZnumber
Makes the specified Player use the block entity at the specified coords (open chest UI, etc.) If the cords are in an unloaded chunk or there's no block entity, ignores the call.
VillagersShouldHarvestCrops
boolean
Returns true if villagers can harvest crops.
WakeUpSimulators
BlockVector3i
Wakes up the simulators for the specified block.
WakeUpSimulatorsInArea
AreacCuboid
Wakes up the simulators for all the blocks in the specified area (edges inclusive).

Using callbacks

To avoid problems with stale objects, the cWorld class will not let plugins get a direct pointer to an entity, block entity or a player. Such an object could be modified or even destroyed by another thread while the plugin holds it, so it would be rather unsafe.

Instead, the cWorld provides access to these objects using callbacks. The plugin provides a function that is called and receives the object as a parameter; cWorld guarantees that while the callback is executing, the object will stay valid. If a plugin needs to "remember" the object outside of the callback, it needs to store the entity ID, blockentity coords or player name.

The following code examples show how to use the callbacks

This code teleports player Player to another player named ToName in the same world:

-- Player is a cPlayer object
-- ToName is a string
-- World is a cWorld object
World:ForEachPlayer(
	function (a_OtherPlayer)
	if (a_OtherPlayer:GetName() == ToName) then
		Player:TeleportToEntity(a_OtherPlayer);
	end
);

This code fills each furnace in the chunk with 64 coals:

-- Player is a cPlayer object
-- World is a cWorld object
World:ForEachFurnaceInChunk(Player:GetChunkX(), Player:GetChunkZ(),
	function (a_Furnace)
		a_Furnace:SetFuelSlot(cItem(E_ITEM_COAL, 64));
	end
);

This code teleports all spiders up by 100 blocks:

-- World is a cWorld object
World:ForEachEntity(
	function (a_Entity)
		if not(a_Entity:IsMob()) then
			return;
		end

		-- Now that we know the entity represents a mob, we can use cMonster functions:
		if (a_Entity:GetMobType() == mtSpider) then
			a_Entity:TeleportToCoords(a_Entity:GetPosX(), a_Entity:GetPosY() + 100, a_Entity:GetPosZ());
		end
	end
);

Generated by APIDump on 2024-12-05 00:47:58, Build ID 88, Commit 4b2b02a8ba1cf259ead477cc256c4ac2a994809c