WIP MinecraftSetter

-------------------------------
-- /lib/MinecraftSetter
-------------------------------
--- This package keeps all functions that modify the minecraft game world:
-- setblock, fill, clone, teleport, title, tellraw, scoreboard, weather, gamerule, etc.
-- the rest of twenty-k code should not use Minecraft commands directly but only through this package

local mc = {}
mcset = mc

CLONE_MASK_MODE = {
    REPLACE = "replace", -- Clones all blocks, including air.
    MASKED = "masked", -- Clones only blocks that are not air.
    FILTERED = "filtered" -- Clones only blocks that match the tileName.
}

CLONE_MODE = {
    NORMAL = "normal", -- Clone the blocks from the source region to the destination region.
    FORCE = "force", -- Force the clone if the source region and destination region overlap.
    MOVE = "move" -- Clone the blocks from the source region to the destination region. Then replace the cloned blocks in the source region with air (blocks not cloned in the source region will remain unchanged if CLONE_MASK_MODE.FILTERED was used).
}


local FILL_LIMIT = 32768

--- Places a block of type block.block and variant block.variant at x,y,z
function mc.setBlock(x,y,z,block)
    commands.setblock(x,y,z,block.block,block.variant)
end

--- Moves the contents of a box from one location to another in the Minecraft World
-- the reference points are the centers of the two boxes
-- returns the new box object it moved to
function mc.moveBoxCenter(from_box,to_box)
    mc.cloneBox(
        from,
        to.corner_x-(from.size_x-to.size_x)/2, to.corner_y, to.corner_z-(from.size_z-to.size_z)/2,
        CLONE_MASK_MODE.REPLACE, CLONE_MODE.MOVE
    )
    return to_box
end

--- Copies the contents of a box from one location to another in the Minecraft World
-- the reference points are the centers of the two boxes
-- returns the new box object it copied to
function mc.copyBoxCenter(from_box,to_box)
    mc.cloneBox(
        from,
        to.corner_x-(from.size_x-to.size_x)/2, to.corner_y, to.corner_z-(from.size_z-to.size_z)/2,
        CLONE_MASK_MODE.REPLACE, CLONE_MODE.FORCE
    )
    return to_box
end

--- Copies the contents of a box from one location to another in the Minecraft World
-- uses the masked option to copy only blocks that are not air.
-- the reference points are the centers of the two boxes
-- returns the new box object it copied to
function mc.copyBoxCenterMasked(from_box,to_box, with_base)
    mc.cloneBox(
        from,
        to.corner_x-(from.size_x-to.size_x)/2, to.corner_y, to.corner_z-(from.size_z-to.size_z)/2,
        CLONE_MASK_MODE.MASKED, CLONE_MODE.FORCE
    )
    return to_box
end

--- Fills a region recursively even if it is bigger by the allowed number of blocks.
-- @param x
-- @param y
-- @param z
-- @param sizeX
-- @param sizeY
-- @param sizeZ
-- @param fill_material A table with field .block and .variant
-- @param replace_material Optional, A table with fields .block and .variant
function mc.fillBox(_box, fill_material,replace_material)
    --check if volume is bigger than maximum blocks 32768
    if _box then
        local x, y, z = _box.corner_x, _box.corner_y, _box.corner_z
        local w, h, l = _box.size_x, _box.size_y, _box.size_z
        if math.abs(w*l*h) <= FILL_LIMIT then
            --if not then do simple fill
            if replace_material then
                commands.async.fill(x,y,z,x+w-(w/math.abs(w)),y+h-(h/math.abs(h)),z+l-(l/math.abs(l)),fill_material.block, fill_material.variant, "replace", replace_material.block, replace_material.variant)
            else
                commands.async.fill(x,y,z,x+w-(w/math.abs(w)),y+h-(h/math.abs(h)),z+l-(l/math.abs(l)),fill_material.block, fill_material.variant )
            end
            --return true
        else
            --otherwise divide in 8 sub-boxes and run again
            local subboxes = box_subdivide(_box)
            if subboxes then
                for i, sbox in ipairs(subboxes) do
                    mc.fillBox(sbox, fill_material, replace_material)
                end
            end
            --return true
        end
    end
    --return false
end

--- Creates a ring of blocks using coordinates.
function mc.fillRing(_box, fill_material,replace_material)
    local x, y, z = _box.corner_x, _box.corner_y, _box.corner_z
    local w, h, l = _box.size_x, _box.size_y, _box.size_z
    mc.fillBox( box(x,y,z,w,h,1),       fill_material, replace_material)
    mc.fillBox( box(x,y,z,1,h,l),       fill_material, replace_material)
    mc.fillBox( box(x+w-1,y,z,1,h,l),   fill_material, replace_material)
    mc.fillBox( box(x,y,z+l-1,w,h,1),   fill_material, replace_material)
end

-- Fills a horizontal region with grid markers.
-- takes the grid origin point from the box's base_center
-- and the grid step from grid_step
function mc.fillGrid( _box, center_x, center_y, center_z, grid_step, fill_material)
    --x,y,z,sizeX,sizeZ, center_x, center_z

    --safeguard the arguments
    assert((type(grid_step) == 'number' and grid_step~=0), "fillGrid(): invalid argument [grid_step]: must be a number different from 0")
    assert(type(fill_material) == 'table', "fillGrid(): invalid argument [fill_material]: must be a table")
    assert(fill_material.block, "fillGrid(): invalid argument [fill_material]: missing .block field")
    assert(fill_material.variant, "fillGrid(): invalid argument [fill_material]: missing .variant field")
    -- run the function
    local x, y, z = _box.corner_x, _box.corner_y, _box.corner_z
    local uX = _box.size_x/math.abs(_box.size_x)
    local uY = _box.size_y/math.abs(_box.size_y)
    local uZ = _box.size_z/math.abs(_box.size_z)
    for ix = x, x+_box.size_x-uX, uX do
        --for iy = y, y+_box.size_y-uY, uY do
            for iz = z, z+_box.size_z-uZ, uZ do
                --check if the coordinate is a grid point
                if (ix-center_x) % grid_step == 0
                    --[[and (iy-center_y) % grid_step == 0]]
                    and (iz-center_z) % grid_step == 0 then
                    --debug.log("fillGrid(): placing grid marker at: { "..ix..", "..y..", "..iz.." }")
                    commands.async.setblock(ix, y, iz, fill_material.block, fill_material.variant)
                end
            end
            --end
    end
end

--- Clones an area even if it is bigger than the minecraft limit.
-- @param maskMode from CLONE_MASK_MODE
-- @param cloneMode from CLONE_MODE
-- @param filteredMaterial table with .block and .variant
function mc.cloneBox(_box, to_x, to_y, to_z, maskMode, cloneMode, filteredMaterial)
    -- clone command works as this: https://www.digminecraft.com/game_commands/clone_command.php
    -- /clone <x1> <y1> <z1>  <x2> <y2> <z2>  <x> <y> <z> [maskMode] [cloneMode] [tileName] [tileData]
    --check if volume is bigger than maximum blocks 32768
    if _box then
        local x, y, z = _box.corner_x, _box.corner_y, _box.corner_z
        local w, h, l = _box.size_x, _box.size_y, _box.size_z
        if math.abs(w*l*h) <= FILL_LIMIT then
            --if not then do simple clone
            if filteredMaterial then
                commands.async.clone(
                    x, y, z,
                    x+w-(w/math.abs(w)), y+h-(h/math.abs(h)), z+l-(l/math.abs(l)),
                    to_x, to_y, to_z,
                    maskMode or CLONE_MASK_MODE.REPLACE, cloneMode or CLONE_MODE.NORMAL, filteredMaterial.block, filteredMaterial.variant)
            else
                commands.async.clone(
                    x, y, z,
                    x+w-(w/math.abs(w)), y+h-(h/math.abs(h)), z+l-(l/math.abs(l)),
                    to_x, to_y, to_z,
                    maskMode or CLONE_MASK_MODE.REPLACE, cloneMode or CLONE_MODE.NORMAL)
            end
            --return true
        else
            --otherwise divide in 8 sub-boxes and run again
            local subboxes = box_subdivide(_box)
            if subboxes then
                for i, sbox in ipairs(subboxes) do
                    mc.cloneBox(sbox, to_x, to_y, to_z, maskMode, cloneMode, filteredMaterial)
                end
            end
        end
    end
    --return false
end

-- ENTITY FUNCTIONS

--- Kills all entities
--if entity_type is specified as string then kills all from that entity type
function mc.killAllEntities(entity_type)
    local selector = ""
    if type(entity_type) == 'string' then selector = "[type="..entity_type.."]" end
    commands.exec("kill @e"..selector)
end

--- Removes all labels from the world by killing all ArmorStands
function mc.removeAllLabels()
    mc.killAllEntities("ArmorStand")
end

--- Places a label in the world
-- Uses an invisible ArmorStand to do this
function mc.placeLabel(x,y,z,label_text)
    commands.summon("ArmorStand",x,y,z,'{CustomName:"'..label_text..'",Invisible:1b,CustomNameVisible:1b}')
end

--PARTICLE FUNCTIONS
--particles shown to player while their key shape is being checked for match
function mc.searchParticle(x,y,z)
    commands.async.particle("fireworksSpark",x,y,z,0.01,3,0.01,0.01,100)
end
-- particles shown to player on successful key match
function mc.successParticle(x,y,z)
    commands.async.particle("happyVillager",x,y,z,2,2,2,1,1000)
    commands.async.playsound("random.levelup","@a",x,y,z,1,1.2)
end
--- particles shown to player on failed key match
function mc.failParticle(x,y,z)
    commands.async.particle("reddust",x,y,z,0.1,0.1,1.5,1,200)
    commands.async.particle("reddust",x,y,z,1.5,0.1,0.1,1,200)
    commands.async.playsound("random.bowhit","@a",x,y,z,1,0.8)
end