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 BlockAreaSrc Copies contents from BlockAreaSrc into self
CopyTo BlockAreaDst 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 BlockType number Counts the number of occurences of the specified blocktype contained in the area.
CountSpecificBlocks BlockType, BlockMeta number Counts the number of occurrences of the specified blocktype + blockmeta combination contained in the area.
Create SizeX, SizeY, SizeZ 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 SizeX, SizeY, SizeZ, DataTypes Initializes this BlockArea to an empty area of the specified size and origin of {0, 0, 0}. Any previous contents are lost.
Create Size 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 Size, DataTypes 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.
Crop AddMinX, SubMaxX, AddMinY, SubMaxY, AddMinZ, SubMaxZ Crops the specified number of blocks from each border. Modifies the size of this blockarea object.
DumpToRawFile FileName Dumps the raw data into a file. For debugging purposes only.
Expand SubMinX, AddMaxX, SubMinY, AddMaxY, SubMinZ, AddMaxZ 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 DataTypes, BlockType, [BlockMeta], [BlockLight], [BlockSkyLight] Fills the entire block area with the same values, specified. Uses the DataTypes param to determine which content types are modified.
FillRelCuboid MinRelX, MaxRelX, MinRelY, MaxRelY, MinRelZ, MaxRelZ, DataTypes, BlockType, [BlockMeta], [BlockLight], [BlockSkyLight] Fills the specified cuboid with the same values (like Fill() ).
FillRelCuboid RelCuboid, DataTypes, BlockType, [BlockMeta], [BlockLight], [BlockSkyLight] Fills the specified cuboid (in relative coords) with the same values (like Fill() ).
GetBlockLight BlockX, BlockY, BlockZ NIBBLETYPE Returns the blocklight at the specified absolute coords
GetBlockMeta BlockX, BlockY, BlockZ NIBBLETYPE Returns the block meta at the specified absolute coords
GetBlockSkyLight BlockX, BlockY, BlockZ NIBBLETYPE Returns the skylight at the specified absolute coords
GetBlockType BlockX, BlockY, BlockZ BLOCKTYPE Returns the block type at the specified absolute coords
GetBlockTypeMeta BlockX, BlockY, BlockZ BLOCKTYPE, NIBBLETYPE Returns the block type and meta at the specified absolute coords
GetCoordRange MaxX, MaxY, MaxZ 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 [IgnoreBlockType] MinRelX, MinRelY, MinRelZ, MaxRelX, MaxRelY, MaxRelZ Returns the minimum and maximum coords in each direction for the first non-ignored block in each direction. 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 OriginX, OriginY, OriginZ 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 RelBlockX, RelBlockY, RelBlockZ NIBBLETYPE Returns the blocklight at the specified relative coords
GetRelBlockMeta RelBlockX, RelBlockY, RelBlockZ NIBBLETYPE Returns the block meta at the specified relative coords
GetRelBlockSkyLight RelBlockX, RelBlockY, RelBlockZ NIBBLETYPE Returns the skylight at the specified relative coords
GetRelBlockType RelBlockX, RelBlockY, RelBlockZ BLOCKTYPE Returns the block type at the specified relative coords
GetRelBlockTypeMeta RelBlockX, RelBlockY, RelBlockZ BLOCKTYPE, NIBBLETYPE Returns the block type and meta at the specified relative coords
GetSize SizeX, SizeY, SizeZ 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 bool Returns true if current datatypes include blocklight
HasBlockMetas bool Returns true if current datatypes include block metas
HasBlockSkyLights bool Returns true if current datatypes include skylight
HasBlockTypes bool Returns true if current datatypes include block types
LoadFromSchematicFile FileName 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 SchematicData 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 BlockAreaSrc, RelX, RelY, RelZ, Strategy Merges BlockAreaSrc into this object at the specified relative coords, using the specified strategy
Merge BlockAreaSrc, RelMinCoords, Strategy 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 World, MinX, MaxX, MinY, MaxY, MinZ, MaxZ bool Reads the area from World, returns true if successful. baTypes and baMetas are read.
Read World, MinX, MaxX, MinY, MaxY, MinZ, MaxZ, DataTypes bool Reads the area from World, returns true if successful
Read World, Point1, Point2 bool Reads the area from World, returns true if successful. baTypes and baMetas are read.
Read World, Point1, Point2, DataTypes bool Reads the area from World, returns true if successful
Read World, Cuboid bool Reads the area from World, returns true if successful. baTypes and baMetas are read.
Read World, Cuboid, DataTypes bool Reads the area from World, returns true if successful
RelLine RelX1, RelY1, RelZ1, RelX2, RelY2, RelZ2, DataTypes, BlockType, [BlockMeta], [BlockLight], [BlockSkyLight] Draws a line between the two specified points. Sets only datatypes specified by DataTypes (baXXX constants).
RelLine RelPoint1, RelPoint2, DataTypes, BlockType, [BlockMeta], [BlockLight], [BlockSkyLight] 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 FileName 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 BlockX, BlockY, BlockZ, BlockLight Sets the blocklight at the specified absolute coords
SetBlockMeta BlockX, BlockY, BlockZ, BlockMeta Sets the block meta at the specified absolute coords
SetBlockSkyLight BlockX, BlockY, BlockZ, SkyLight Sets the skylight at the specified absolute coords
SetBlockType BlockX, BlockY, BlockZ, BlockType Sets the block type at the specified absolute coords
SetBlockTypeMeta BlockX, BlockY, BlockZ, BlockType, BlockMeta Sets the block type and meta at the specified absolute coords
SetOrigin OriginX, OriginY, OriginZ Resets the origin for the absolute coords. Only affects how absolute coords are translated into relative coords.
SetOrigin Origin Resets the origin for the absolute coords. Only affects how absolute coords are translated into relative coords.
SetRelBlockLight RelBlockX, RelBlockY, RelBlockZ, BlockLight Sets the blocklight at the specified relative coords
SetRelBlockMeta RelBlockX, RelBlockY, RelBlockZ, BlockMeta Sets the block meta at the specified relative coords
SetRelBlockSkyLight RelBlockX, RelBlockY, RelBlockZ, SkyLight Sets the skylight at the specified relative coords
SetRelBlockType RelBlockX, RelBlockY, RelBlockZ, BlockType Sets the block type at the specified relative coords
SetRelBlockTypeMeta RelBlockX, RelBlockY, RelBlockZ, BlockType, BlockMeta Sets the block type and meta at the specified relative coords
SetWEOffset OffsetX, OffsetY, OffsetZ 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 Offset 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 World, MinX, MinY, MinZ bool Writes the area into World at the specified coords, returns true if successful. baTypes and baMetas are written.
Write World, MinX, MinY, MinZ, DataTypes bool Writes the area into World at the specified coords, returns true if successful
Write World, MinPoint bool Writes the area into World at the specified coords, returns true if successful. baTypes and baMetas are written.
Write World, MinPoint, DataTypes bool Writes the area into World at the specified coords, returns true if successful

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 2016-08-22 23:53:06, Build ID Unknown, Commit approx: 2ed4af74edd14ae17e1c6c64d44caa7b7fc30d5a