cBlockArea


Index:
Articles
Classes
Hooks

Quick navigation:
cArrowEntity
cBeaconEntity
cBlockArea
cBlockEntity
cBlockEntityWithItems
cBlockInfo
cBoundingBox
cBrewingstandEntity
cChatColor
cChestEntity
cChunkDesc
cClientHandle
cCommandBlockEntity
cCompositeChat
cCraftingGrid
cCraftingRecipe
cCryptoHash
cCuboid
cDispenserEntity
cDropperEntity
cDropSpenserEntity
cEnchantments
cEntity
cEntityEffect
cExpBottleEntity
cFile
cFireChargeEntity
cFireworkEntity
cFloater
cFlowerPotEntity
cFurnaceEntity
cGhastFireballEntity
cHangingEntity
cHopperEntity
cIniFile
cInventory
cItem
cItemFrame
cItemGrid
cItems
cJson
cJukeboxEntity
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
cStatManager
cStringCompression
cTCPLink
cTeam
cThrownEggEntity
cThrownEnderPearlEntity
cThrownSnowballEntity
cTNTEntity
cTracer
cUDPEndpoint
cUrlClient
cUrlParser
cWebAdmin
cWindow
cWitherSkullEntity
cWorld
HTTPFormData
HTTPRequest
HTTPTemplateRequest
ItemCategory
lxp
sqlite3
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.

cBlockArea can hold any combination of the following datatypes:

  • block types
  • block metas
  • blocklight
  • skylight
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 (FIXME).

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


Constants

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

NameValueNotes
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
DataTypesstring
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
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
DataTypesstring
Initializes this BlockArea to an empty area of the specified size and origin of {0, 0, 0}. Any previous contents are lost.
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.
Crop
AddMinXnumber
SubMaxXnumber
AddMinYnumber
SubMaxYnumber
AddMinZnumber
SubMaxZnumber
Crops the specified number of blocks from each border. Modifies the size of this blockarea object.
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
DataTypesstring
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
DataTypesstring
BlockTypenumber
BlockMetanumber
BlockLightnumber
BlockSkyLightnumber
Fills the specified cuboid (in relative coords) with the same values (like Fill() ).
FillRelCuboid
MinRelXnumber
MaxRelXnumber
MinRelYnumber
MaxRelYnumber
MinRelZnumber
MaxRelZnumber
DataTypesstring
BlockTypenumber
BlockMetanumber
BlockLightnumber
BlockSkyLightnumber
Fills the specified cuboid with the same values (like Fill() ).
GetBlockLight
BlockXnumber
BlockYnumber
BlockZnumber
NIBBLETYPEnumber
Returns the blocklight at the specified absolute coords
GetBlockMeta
BlockXnumber
BlockYnumber
BlockZnumber
NIBBLETYPEnumber
Returns the block meta at the specified absolute coords
GetBlockSkyLight
BlockXnumber
BlockYnumber
BlockZnumber
NIBBLETYPEnumber
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
NIBBLETYPEnumber
Returns the block type and meta at the specified absolute coords
GetCoordRange
MaxXnumber
MaxYnumber
MaxZnumber
Returns the maximum relative coords in all 3 axes. See also GetSize().
GetDataTypes
number
Returns the mask of datatypes 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}.
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
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
RelXnumber
RelYnumber
RelZnumber
Strategystring
Merges BlockAreaSrc into this object at the specified relative coords, using the specified strategy
Merge
BlockAreaSrccBlockArea
RelMinCoordsnumber
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
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.
Read
WorldcWorld
CuboidcCuboid
IsSuccessboolean
Reads the area from World, returns true if successful. baTypes and baMetas are read.
Read
WorldcWorld
Point1Vector3i
Point2Vector3i
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
MinXnumber
MaxXnumber
MinYnumber
MaxYnumber
MinZnumber
MaxZnumber
boolean
Reads the area from World, returns true if successful. baTypes and baMetas are 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
DataTypesstring
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
OriginVector3i
Resets the origin for the absolute coords. Only affects how absolute coords are translated into relative coords.
SetOrigin
OriginXnumber
OriginYnumber
OriginZnumber
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
MinXnumber
MinYnumber
MinZnumber
IsSuccessboolean
Writes the area into World at the specified coords, returns true if successful. baTypes and baMetas 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
MinPointVector3i
IsSuccessboolean
Writes the area into World at the specified coords, returns true if successful. baTypes and baMetas 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 on 2017-03-29 13:00:06, Build ID Unknown, Commit approx: 5dc0189a160a9ab4d6c9c2865fc8ff5d7ca32d69