cBlockArea


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


cBlockArea class

This class is used when multiple adjacent blocks are to be manipulated. Because of chunking and multithreading, manipulating single blocks using cWorld:SetBlock() is a rather time-consuming operation (locks for exclusive access need to be obtained, chunk lookup is done for each block), so whenever you need to manipulate multiple adjacent blocks, it's better to wrap the operation into a cBlockArea access. cBlockArea is capable of reading / writing across chunk boundaries, has no chunk lookups for get and set operations and is not subject to multithreading locking (because it is not shared among threads).

cBlockArea remembers its origin (MinX, MinY, MinZ coords in the Read() call) and therefore supports absolute as well as relative get / set operations. Despite that, the contents of a cBlockArea can be written back into the world at any coords. Most functions in this class come in pair, one that works with the absolute coords (what the coords would have been in the original world the area was read from) and one (usually with "Rel" in their name) that work on the relative coords (those range from zero to Size - 1). Also note that most functions will raise an error if an out-of-range coord is supplied to them.

cBlockArea can hold any combination of the following datatypes:

  • block types
  • block metas
  • blocklight
  • skylight
  • block entities (only together with block types)
Read() and Write() functions have parameters that tell the class which datatypes to read / write. Note that a datatype that has not been read cannot be written.

Block entities stored inside a cBlockArea object have their position set to the relative position within the area.

Typical usage:

  • Create cBlockArea object
  • Read an area from the world / load from file / create anew
  • Modify blocks inside cBlockArea
  • Write the area back to a world / save to file

Calls to any setter of this class will not trigger simulator updates (lava, water, redstone).


Constants

The following constants are used to signalize the datatype to read or write:

NameValueNotes
baBlockEntities 32 Operations should work on block entities. Note that this flag is invalid without baTypes.
baLight 4 Operations should work on block (emissive) light
baMetas 2 Operations should work on block metas
baSkyLight 8 Operations should work on skylight
baTypes 1 Operation should work on block types


The Merge() function can use different strategies to combine the source and destination blocks. The following constants are used:

NameValueNotes
msDifference 5 Block becomes air if 'self' and src are the same. Otherwise it becomes the src block.
msFillAir 1 'self' is overwritten by Src only where 'self' has air blocks
msImprint 2 Src overwrites 'self' anywhere where 'self' has non-air blocks
msLake 3 Special mode for merging lake images
msMask 7 The blocks that are exactly the same are kept in 'self', all differing blocks are replaced by air
msOverwrite 0 Src overwrites anything in 'self'
msSimpleCompare 6 The blocks that are exactly the same are replaced with air, all differing blocks are replaced by stone
msSpongePrint 4 Similar to msImprint, sponge block doesn't overwrite anything, all other blocks overwrite everything
See below for a detailed explanation of the individual merge strategies.



Functions

NameParametersReturn valueNotes
() (constructor)
cBlockArea
Creates a new empty cBlockArea object
Clear Clears the object, resets it to zero size
CopyFrom
BlockAreaSrccBlockArea
Copies contents from BlockAreaSrc into self
CopyTo
BlockAreaDstcBlockArea
Copies contents from self into BlockAreaDst.
CountNonAirBlocks
number
Returns the count of blocks that are not air. Returns 0 if blocktypes not available. Block metas are ignored (if present, air with any meta is still considered air).
CountSpecificBlocks
BlockTypenumber
number
Counts the number of occurences of the specified blocktype contained in the area.
CountSpecificBlocks
BlockTypenumber
BlockMetanumber
number
Counts the number of occurrences of the specified blocktype + blockmeta combination contained in the area.
Create
SizeVector3i
DataTypesnumber
Creates a new area of the specified size and contents. Origin is set to all zeroes. BlockTypes are set to air, block metas to zero, blocklights to zero and skylights to full light.
Create
SizeVector3i
Creates a new area of the specified size. Datatypes are set to baTypes + baMetas. Origin is set to all zeroes. BlockTypes are set to air, block metas to zero, blocklights to zero and skylights to full light.
Create
SizeXnumber
SizeYnumber
SizeZnumber
Initializes this BlockArea to an empty area of the specified size and origin of {0, 0, 0}. Datatypes are set to baTypes + baMetas. Any previous contents are lost.
Create
SizeXnumber
SizeYnumber
SizeZnumber
DataTypesnumber
Initializes this BlockArea to an empty area of the specified size and origin of {0, 0, 0}. Any previous contents are lost.
Crop
AddMinXnumber
SubMaxXnumber
AddMinYnumber
SubMaxYnumber
AddMinZnumber
SubMaxZnumber
Crops the specified number of blocks from each border. Modifies the size of this blockarea object.
DoWithBlockEntityAt
BlockXnumber
BlockYnumber
BlockZnumber
Callbackfunction
Calls the specified callback with the block entity at the specified absolute coords. The CallbackFunction has the following signature:
function Callback(BlockEntity)
Returns false if there's no block entity at the specified coords. Returns the value that the callback has returned otherwise.
DoWithBlockEntityAt
CoordsVector3i
Callbackfunction
Calls the specified callback with the block entity at the specified absolute coords. The CallbackFunction has the following signature:
function Callback(BlockEntity)
Returns false if there's no block entity at the specified coords. Returns the value that the callback has returned otherwise.
DoWithBlockEntityRelAt
RelCoordsVector3i
Callbackfunction
Calls the specified callback with the block entity at the specified relative coords. The CallbackFunction has the following signature:
function Callback(BlockEntity)
Returns false if there's no block entity at the specified coords. Returns the value that the callback has returned otherwise.
DoWithBlockEntityRelAt
RelXnumber
RelYnumber
RelZnumber
Callbackfunction
Calls the specified callback with the block entity at the specified relative coords. The CallbackFunction has the following signature:
function Callback(BlockEntity)
Returns false if there's no block entity at the specified coords. Returns the value that the callback has returned otherwise.
DumpToRawFile
FileNamestring
Dumps the raw data into a file. For debugging purposes only.
Expand
SubMinXnumber
AddMaxXnumber
SubMinYnumber
AddMaxYnumber
SubMinZnumber
AddMaxZnumber
Expands the specified number of blocks from each border. Modifies the size of this blockarea object. New blocks created with this operation are filled with zeroes.
Fill
DataTypesnumber
BlockTypenumber
BlockMetanumber
BlockLightnumber
BlockSkyLightnumber
Fills the entire block area with the same values, specified. Uses the DataTypes param to determine which content types are modified.
FillRelCuboid
RelCuboidcCuboid
DataTypesnumber
BlockTypenumber
BlockMetanumber
BlockLightnumber
BlockSkyLightnumber
Fills the specified cuboid (in relative coords) with the same values (like Fill() ).
FillRelCuboid
MinRelXnumber
MaxRelXnumber
MinRelYnumber
MaxRelYnumber
MinRelZnumber
MaxRelZnumber
DataTypesnumber
BlockTypenumber
BlockMetanumber
BlockLightnumber
BlockSkyLightnumber
Fills the specified cuboid with the same values (like Fill() ).
ForEachBlockEntity
CoordsVector3i
Callbackfunction
Calls the specified callback with the block entity for each block entity contained in the object. Returns true if all block entities 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.
GetBlockLight
BlockXnumber
BlockYnumber
BlockZnumber
BlockLightnumber
Returns the blocklight (emissive light) at the specified absolute coords
GetBlockMeta
BlockXnumber
BlockYnumber
BlockZnumber
BlockMetanumber
Returns the block meta at the specified absolute coords
GetBlockSkyLight
BlockXnumber
BlockYnumber
BlockZnumber
BlockSkyLightnumber
Returns the skylight at the specified absolute coords
GetBlockType
BlockXnumber
BlockYnumber
BlockZnumber
BLOCKTYPEnumber
Returns the block type at the specified absolute coords
GetBlockTypeMeta
BlockXnumber
BlockYnumber
BlockZnumber
BlockTypenumber
BlockMetanumber
Returns the block type and meta at the specified absolute coords
GetBounds
BoundscCuboid
Returns the cuboid that specifies the original coords of the world from which the area was read. Basically constructs a cCuboid out of GetOrigin() and GetOrigin() + GetCoordRange().
GetCoordRange
MaxXnumber
MaxYnumber
MaxZnumber
Returns the maximum relative coords in all 3 axes. See also GetSize().
GetDataTypes
number
Returns the mask of datatypes (ba* constants added together) that the object is currently holding.
GetNonAirCropRelCoords
IgnoredBlockTypenumber
MinRelXnumber
MinRelYnumber
MinRelZnumber
MaxRelXnumber
MaxRelYnumber
MaxRelZnumber
Returns the minimum and maximum coords in each direction for the first block in each direction of type different to IgnoredBlockType (E_BLOCK_AIR by default). If there are no non-ignored blocks within the area, or blocktypes are not present, the returned values are reverse-ranges (MinX <- m_RangeX, MaxX <- 0 etc.). IgnoreBlockType defaults to air.
GetOrigin
OriginXnumber
OriginYnumber
OriginZnumber
Returns the origin coords of where the area was read from.
GetOriginX
number
Returns the origin x-coord
GetOriginY
number
Returns the origin y-coord
GetOriginZ
number
Returns the origin z-coord
GetRelBlockLight
RelBlockXnumber
RelBlockYnumber
RelBlockZnumber
NIBBLETYPEnumber
Returns the blocklight at the specified relative coords
GetRelBlockMeta
RelBlockXnumber
RelBlockYnumber
RelBlockZnumber
NIBBLETYPEnumber
Returns the block meta at the specified relative coords
GetRelBlockSkyLight
RelBlockXnumber
RelBlockYnumber
RelBlockZnumber
NIBBLETYPEnumber
Returns the skylight at the specified relative coords
GetRelBlockType
RelBlockXnumber
RelBlockYnumber
RelBlockZnumber
BLOCKTYPEnumber
Returns the block type at the specified relative coords
GetRelBlockTypeMeta
RelBlockXnumber
RelBlockYnumber
RelBlockZnumber
BLOCKTYPEnumber
NIBBLETYPEnumber
Returns the block type and meta at the specified relative coords
GetSize
SizeXnumber
SizeYnumber
SizeZnumber
Returns the size of the area in all 3 axes. See also GetCoordRange().
GetSizeX
number
Returns the size of the held data in the x-axis
GetSizeY
number
Returns the size of the held data in the y-axis
GetSizeZ
number
Returns the size of the held data in the z-axis
GetVolume
number
Returns the volume of the area - the total number of blocks stored within.
GetWEOffset
Vector3i
Returns the WE offset, a data value sometimes stored in the schematic files. Cuberite doesn't use this value, but provides access to it using this method. The default is {0, 0, 0}.
HasBlockEntities
boolean
Returns true if current datatypes include block entities.
HasBlockLights
boolean
Returns true if current datatypes include blocklight
HasBlockMetas
boolean
Returns true if current datatypes include block metas
HasBlockSkyLights
boolean
Returns true if current datatypes include skylight
HasBlockTypes
boolean
Returns true if current datatypes include block types
IsValidCoords
BlockXnumber
BlockYnumber
BlockZnumber
boolean
Returns true if the specified absolute coords are within the area.
IsValidCoords
CoordsVector3i
boolean
Returns true if the specified absolute coords are within the area.
IsValidDataTypeCombination
DataTypesnumber
boolean
(STATIC) Returns true if the specified combination of datatypes (ba* constants added together) is valid. Most combinations are valid, but for example baBlockEntities without baTypes is an invalid combination.
IsValidRelCoords
RelBlockXnumber
RelBlockYnumber
RelBlockZnumber
boolean
Returns true if the specified relative coords are within the area.
IsValidRelCoords
RelCoordsVector3i
boolean
Returns true if the specified relative coords are within the area.
LoadFromSchematicFile
FileNamestring
boolean
Clears current content and loads new content from the specified schematic file. Returns true if successful. Returns false and logs error if unsuccessful, old content is preserved in such a case.
LoadFromSchematicString
SchematicDatastring
boolean
Clears current content and loads new content from the specified string (assumed to contain .schematic data). Returns true if successful. Returns false and logs error if unsuccessful, old content is preserved in such a case.
Merge
BlockAreaSrccBlockArea
RelMinCoordsnumber
Strategystring
Merges BlockAreaSrc into this object at the specified relative coords, using the specified strategy
Merge
BlockAreaSrccBlockArea
RelXnumber
RelYnumber
RelZnumber
Strategystring
Merges BlockAreaSrc into this object at the specified relative coords, using the specified strategy
MirrorXY Mirrors this block area around the XY plane. Modifies blocks' metas (if present) to match (i. e. furnaces facing the opposite direction).
MirrorXYNoMeta Mirrors this block area around the XY plane. Doesn't modify blocks' metas.
MirrorXZ Mirrors this block area around the XZ plane. Modifies blocks' metas (if present)
MirrorXZNoMeta Mirrors this block area around the XZ plane. Doesn't modify blocks' metas.
MirrorYZ Mirrors this block area around the YZ plane. Modifies blocks' metas (if present)
MirrorYZNoMeta Mirrors this block area around the YZ plane. Doesn't modify blocks' metas.
Read
WorldcWorld
CuboidcCuboid
IsSuccessboolean
Reads the area from World, returns true if successful. baTypes and baMetas are read.
Read
WorldcWorld
CuboidcCuboid
DataTypesnumber
IsSuccessboolean
Reads the area from World, returns true if successful. DataTypes is the sum of baXXX datatypes to be read
Read
WorldcWorld
Point1Vector3i
Point2Vector3i
IsSuccessboolean
Reads the area from World, returns true if successful. baTypes and baMetas are read.
Read
WorldcWorld
MinXnumber
MaxXnumber
MinYnumber
MaxYnumber
MinZnumber
MaxZnumber
boolean
Reads the area from World, returns true if successful. baTypes and baMetas are read.
Read
WorldcWorld
MinXnumber
MaxXnumber
MinYnumber
MaxYnumber
MinZnumber
MaxZnumber
DataTypesnumber
boolean
Reads the area from World, returns true if successful. DataTypes is a sum of baXXX datatypes to read.
Read
WorldcWorld
Point1Vector3i
Point2Vector3i
DataTypesnumber
IsSuccessboolean
Reads the area from World, returns true if successful. DataTypes is a sum of baXXX datatypes to be read.
RelLine
RelPoint1Vector3i
RelPoint2Vector3i
DataTypesnumber
BlockTypenumber
BlockMetanumber
BlockLightnumber
BlockSkyLightnumber
Draws a line between the two specified points. Sets only datatypes specified by DataTypes (baXXX constants).
RelLine
RelX1number
RelY1number
RelZ1number
RelX2number
RelY2number
RelZ2number
DataTypesnumber
BlockTypenumber
BlockMetanumber
BlockLightnumber
BlockSkyLightnumber
Draws a line between the two specified points. Sets only datatypes specified by DataTypes (baXXX constants).
RotateCCW Rotates the block area around the Y axis, counter-clockwise (east -> north). Modifies blocks' metas (if present) to match.
RotateCCWNoMeta Rotates the block area around the Y axis, counter-clockwise (east -> north). Doesn't modify blocks' metas.
RotateCW Rotates the block area around the Y axis, clockwise (north -> east). Modifies blocks' metas (if present) to match.
RotateCWNoMeta Rotates the block area around the Y axis, clockwise (north -> east). Doesn't modify blocks' metas.
SaveToSchematicFile
FileNamestring
boolean
Saves the current contents to a schematic file. Returns true if successful.
SaveToSchematicString
string
Saves the current contents to a string (in a .schematic file format). Returns the data if successful, nil if failed.
SetBlockLight
BlockXnumber
BlockYnumber
BlockZnumber
BlockLightnumber
Sets the blocklight at the specified absolute coords
SetBlockMeta
BlockXnumber
BlockYnumber
BlockZnumber
BlockMetanumber
Sets the block meta at the specified absolute coords.
SetBlockSkyLight
BlockXnumber
BlockYnumber
BlockZnumber
BlockSkyLightnumber
Sets the skylight at the specified absolute coords
SetBlockType
BlockXnumber
BlockYnumber
BlockZnumber
BlockTypenumber
Sets the block type at the specified absolute coords
SetBlockTypeMeta
BlockXnumber
BlockYnumber
BlockZnumber
BlockTypenumber
BlockMetanumber
Sets the block type and meta at the specified absolute coords
SetOrigin
OriginXnumber
OriginYnumber
OriginZnumber
Resets the origin for the absolute coords. Only affects how absolute coords are translated into relative coords.
SetOrigin
OriginVector3i
Resets the origin for the absolute coords. Only affects how absolute coords are translated into relative coords.
SetRelBlockLight
RelBlockXnumber
RelBlockYnumber
RelBlockZnumber
BlockLightnumber
Sets the blocklight at the specified relative coords
SetRelBlockMeta
RelBlockXnumber
RelBlockYnumber
RelBlockZnumber
BlockMetanumber
Sets the block meta at the specified relative coords
SetRelBlockSkyLight
RelBlockXnumber
RelBlockYnumber
RelBlockZnumber
BlockSkyLightnumber
Sets the skylight at the specified relative coords
SetRelBlockType
RelBlockXnumber
RelBlockYnumber
RelBlockZnumber
BlockTypenumber
Sets the block type at the specified relative coords
SetRelBlockTypeMeta
RelBlockXnumber
RelBlockYnumber
RelBlockZnumber
BlockTypenumber
BlockMetanumber
Sets the block type and meta at the specified relative coords
SetWEOffset
OffsetVector3i
Sets the WE offset, a data value sometimes stored in the schematic files. Mostly used for WorldEdit. Cuberite doesn't use this value, but provides access to it using this method.
SetWEOffset
OffsetXnumber
OffsetYnumber
OffsetZnumber
Sets the WE offset, a data value sometimes stored in the schematic files. Mostly used for WorldEdit. Cuberite doesn't use this value, but provides access to it using this method.
Write
WorldcWorld
MinPointVector3i
IsSuccessboolean
Writes the area into World at the specified coords, returns true if successful. All present data types are written.
Write
WorldcWorld
MinPointVector3i
DataTypesnumber
IsSuccessboolean
Writes the area into World at the specified coords, returns true if successful. DataTypes is the sum of baXXX datatypes to write.
Write
WorldcWorld
MinXnumber
MinYnumber
MinZnumber
IsSuccessboolean
Writes the area into World at the specified coords, returns true if successful. All present data types are written.
Write
WorldcWorld
MinXnumber
MinYnumber
MinZnumber
DataTypesnumber
IsSuccessboolean
Writes the area into World at the specified coords, returns true if successful. DataTypes is the sum of baXXX datatypes to write.

Merge strategies

The strategy parameter specifies how individual blocks are combined together, using the table below.

area blockresult
this Src msOverwrite msFillAir msImprint
air air air air air
A air air A A
air B B B B
A B B A B
A A A A A

So to sum up:

  1. msOverwrite completely overwrites all blocks with the Src's blocks
  2. msFillAir overwrites only those blocks that were air
  3. msImprint overwrites with only those blocks that are non-air

Special strategies

For each strategy, evaluate the table rows from top downwards, the first match wins.

msDifference - changes all the blocks which are the same to air. Otherwise the source block gets placed.

area block Notes
* B B The blocks are different so we use block B
B B Air The blocks are the same so we get air.

msLake - used for merging areas with lava and water lakes, in the appropriate generator.

area block Notes
self Src result
A sponge A Sponge is the NOP block
* air air Air always gets hollowed out, even under the oceans
water * water Water is never overwritten
lava * lava Lava is never overwritten
* water water Water always overwrites anything
* lava lava Lava always overwrites anything
dirt stone stone Stone overwrites dirt
grass stone stone ... and grass
mycelium stone stone ... and mycelium
A stone A ... but nothing else
A * A Everything else is left as it is

msSpongePrint - used for most prefab-generators to merge the prefabs. Similar to msImprint, but uses the sponge block as the NOP block instead, so that the prefabs may carve out air pockets, too.

area block Notes
self Src result
A sponge A Sponge is the NOP block
* B B Everything else overwrites anything

msMask - the blocks that are the same in the other area are kept, all the differing blocks are replaced with air. Meta is used in the comparison, too, two blocks of the same type but different meta are considered different and thus replaced with air.

area block Notes
self Src result
A A A Same blocks are kept
A non-A air Differing blocks are replaced with air

msDifference - the blocks that are the same in both areas are replaced with air, all the differing blocks are kept from the first area. Meta is used in the comparison, too, two blocks of the same type but different meta are considered different.

area block Notes
self Src result
A A air Same blocks are replaced with air
A non-A A Differing blocks are kept from 'self'

msSimpleCompare - the blocks that are the same in both areas are replaced with air, all the differing blocks are replaced with stone. Meta is used in the comparison, too, two blocks of the same type but different meta are considered different.

area block Notes
self Src result
A A air Same blocks are replaced with air
A non-A stone Differing blocks are replaced with stone
Generated by APIDump on 2024-07-12 00:49:19, Build ID 63, Commit 5f4d2f004bc41bc44d0df7376e48cbb5567db1be