cBlockArea

[xoft]

cBlockArea is somewhat like the Clipboard in Windows - you press Ctrl+C, it remembers. You press Ctrl+V, it writes whatever is stored within. But cBlockArea is even better, because you can modify its contents between the copy and paste operations.

So, the usual workflow is:
1, Create a new empty cBlockArea object: local Area = cBlockArea();
2, Read an area from cWorld (Ctrl+C): Area:Read(World, MinX, MaxX, MinY, MaxY, MinZ, MaxZ);
3, Query or modify the contents: Area:SetRelBlockTypeMeta(RelX, RelY, RelZ, E_BLOCK_AIR, 0); etc.
4, Write the area to cWorld (Ctrl+V): Area:Write(World, MinX, MinY, MinZ);

For example, the following code reads an area around a player and replaces all air with cobwebs (off the top of my head, not checked, may need tweaking / fixing):

Code:

local Area = cBlockArea();
local BlockX = Player:GetPosX();
local BlockY = Player:GetPosY();
local BlockZ = Player:GetPosZ();
Area:Read(Player:GetWorld(),
    BlockX - 8, BlockX + 8,  -- 17 blocks across the X coord
    BlockY - 8, BlockY + 8,  -- 17 blocks across the Y coord
    BlockZ - 8, BlockZ + 8   -- 17 blocks across the Z coord
);
for y = 0, 17 do
    for z = 0, 17 do
        for x = 0, 17 do
            if (Area:GetRelBlockType(x, y, z) == E_BLOCK_AIR) then
                Area:SetRelBlockTypeMeta(x, y, z, E_BLOCK_COBWEB, 0);
            end
        end
    end
end
Area:Write(Player:GetWorld, BlockX - 8, BlockY - 8, BlockZ - 8);

Alternatively, instead of reading a block area from cWorld, you can either create an empty one from scratch (cBlockArea:Create() ) or load from disk (cBlockArea:LoadFromSchematicFile() )

The benefit of using cBlockArea over cWorld:GetBlock() is really seen when it comes to multiple blocks being manipulated.
cWorld:GetBlock has to do all this each time it is called:
1, Lock the chunkmap (so that no other thread can modify or unload chunks)
2, Find the chunk corresponding to the coords
3, Retrieve (or set) the block type in the found chunk
4, Unlock the chunkmap
If you do this for many blocks, soon you will find out that the locking and searching (steps 1 & 2) are really eating away your performance.

For example, if you wanted to do the same thing as my previous example did (replace air blocks around the player with cobwebs) using cWorld:GetBlock() and cWorld:SetBlock(), it would make 17x17x17 locks and searches for the GetBlock() and up to 17x17x17 locks and searches for SetBlock(). That's a whopping 9826 locks and searches. Compare that to a single lock and search for cBlockArea:Read() and another single lock and search for cBlockArea:Write().