Quarry

--[[

  Rectangular Quarry Program 1.2b
  by Adam Smith "shiphorns"
  March 7 2013

  1.0b -    Original public release
  1.1b -    Fixes bug with turtle using the wrong axis order when trying to return home after hitting
            and undiggable block. I erroneously had it trying to do moveTo(0,0,0) instead of goHome()
            which would result in the turtle trying to move in the x-direction first, and possibly
            getting blocked by bedrock when trying to move home.
  1.2b -    Fix for turtle getting stuck if turtle simultaneous encounters bedrock in front and above it.

--]]
local tArgs = { ... }
local sizeZ -- Quarry is this long in direction turtle is initially facing, including block turtle is on
local sizeX -- Quarry is this wide to the right of where turtle is facing, including block turtle is on
local sizeY -- Quarry removes this many layers of blocks including layer where turtle starts
local bDebug= false

local goUnload  -- Forward declaration

if (#tArgs == 1) then
    sizeZ,sizeX,sizeY = tonumber(tArgs[1]),tonumber(tArgs[1]),256
elseif (#tArgs == 2) then
    sizeZ,sizeX,sizeY = tonumber(tArgs[1]),tonumber(tArgs[2]),256
elseif (#tArgs >= 3) then
    sizeZ,sizeX,sizeY = tonumber(tArgs[1]),tonumber(tArgs[2]),tonumber(tArgs[3])
    if (#tArgs > 3) then
        bDebug = (tonumber(tArgs[4])==1)
    end
else
    print( "Usage: quarry <sq. size> <optional width > <optional fixed depth> <optional 1 for debug mode>" )
    return
end

-- Validate dimensions
if (sizeX<2 or sizeZ<2 or sizeY<1) then
  print( "Dimensions given must be at least 2L x 2W x 1D. Efficiency is optimal if fixed depth is a multiple of 3." )
  return
end

local minFuel = math.ceil((math.ceil(sizeY/3)*(sizeX*sizeY)+(2*sizeY))/1200)
local maxFuel = "TBD"

if not (turtle.getFuelLevel()=="unlimited") then
  print("Place fuel reserves in slot 1 (upper left) if desired and hit any key to start.")
  os.pullEvent("key")
end

local tX,tZ,tY = 0,0,0    -- Place the turtle starts is considered block 0,0,0 in the turtle's local coordinate system
local xDir,zDir = 0,1     -- Turtle is considered as initially facing positive z direction, regardless of global world facing direction
local refuelSlot = 1      -- Turtle can fuel from any slot, but it will never dump this slot's contents so this is where fuel should be placed

-- Notice that all coordinates formated as 0,0,0 are in X,Z,Y order, NOT alphabetical X,Y,Z order, where Y is up/down axis
-- Y axis is always the minecraft world Y-axis, but X and Z in this turtle's local coordinate system won't necessarily match his
-- orientation in the global world system (turtle's system is relative to how he is initially facing, +Z is his facing direction)

local function checkFuel(bMovingAwayFromOrigin)
    if bDebug then print("checkFuel()") end
    -- This function returns true only if there is enough fuel left to move 1 block in any direction,
    -- and still have enough left over for a return trip to 0,0,0 that might be needed for refuel or at
    -- the end of the quarrying. This ensures the turtle is never stranded in the quarry.
    local fuelLevel = turtle.getFuelLevel()

    if (fuelLevel == "unlimited") then
        -- Server has fuel requirement turned off in configs
        return true
    end

    -- If the turtle is attempting to move away from its starting location, it is going to
    -- consume the normal 1 fuel cost to move, but it will also add +1 to the cost of the
    -- trip to return home to dump/refuel/finish. If we know the turtle is moving closer to
    -- home, there is no extra cost since it is effectively part of the return trip.
    local fuelNeeded = math.abs(tX)+math.abs(tY)+math.abs(tZ)
    if (bMovingAwayFromOrigin == nil or bMovingAwayFromOrigin == true) then
        -- Turtle is moving away from 0,0,0 or direction is unspecified (assume worst case), add 2 fuel
        fuelNeeded = fuelNeeded + 2
    end

    if (fuelLevel >= fuelNeeded) then
        -- Turtle has enough fuel to do the next 1-block movement, plus enough to
        -- return home from there.
        return true
    end

    -- If we get here, turtle does not have enough fuel for the move plus a return to base
    -- First we will try to refuel from anything we find in the turtle's inventory. Failing that
    -- We will return to home and prompt the user to add fuel

    local slot = 1
    turtle.select(slot)

    if bDebug then print("Entering while true do in checkFuel") end
    while true do
        if turtle.refuel(1) then
            -- Found fuel in current slot, consume 1, see if it's enough, if not loop again
            if (turtle.getFuelLevel()>=fuelNeeded) then
                print("Refueled from inventory, resuming quarrying...")
                return true
            end
        else
            -- Couldn't refuel from currently-selected slot, try next slot. If there are no more slots, ask for player help.
            if (slot < 16) then
                slot = slot + 1
                turtle.select(slot)
            else
                -- There are no more slots to look in, reset selection so that we're ready to loop over all slots again, and so that the
                -- player sees slot 1 highlighted (fastest for turtle to find fuel in). Return to 0,0,0 if we can (in case turtle is
                -- under lava or otherwise inaccessible), prompt player to add fuel.

                return goUnload(true)
            end
        end
    end
end

local function turnLeft()
  turtle.turnLeft()
  xDir,zDir = -zDir,xDir
  return true
end

local function turnRight()
  turtle.turnRight()
  xDir,zDir = zDir,-xDir
  return true
end

local function goForward(bCheckFuel)
    if bDebug then print("goForward()") end
    -- Can't move without fuel. checkFuel() will wait on player if necessary.
    if (bCheckFuel==true or bCheckFuel==nil) then
    checkFuel((xDir>0 and tX>=0) or (xDir<0 and tX<=0) or (zDir>0 and tZ>=0) or (zDir<0 and tZ<=0)) -- Passes boolean true if moving away from 0,0,0
  end

    local tries = 3
    while not turtle.forward() do
        if bDebug then print("goForward: while not turtle.forward() do tries="..tries) end
        if turtle.detect() then
            if bDebug then print("goForward: detect") end
            if not turtle.dig() then
                print("Undiggable block encountered. Will retry in 5 seconds.")
                -- Turtle is blocked. In case this is a temporary glitch, we try 3 times before conceding hard failure
                tries = tries - 1
                if (tries <= 0) then
                  return false
                else
                    if bDebug then print("goForward: sleep(5)") end
                    sleep(5) -- Wait 5 seconds, hope the problem resolves itself
                end
            end
        elseif turtle.attack() then
            if bDebug then print("goForward: attack") end
            -- Had to attack player or mob. You can add additional code here such
            -- as turtle.suck() if you want to collect killed mob loot. This is a quarry program
            -- to collect ores, not rotten flesh and bones, so this block is empty.
        else
            -- Unknown obstruction, possibly a player in
            -- peaceful or creative mode. Try again in 0.5 seconds and hope it's gone.
            if bDebug then
                print("goForward: sleep(0.5) else block")
                print("Turtle fuel="..turtle.getFuelLevel())
            end
            sleep(0.5)
        end
    end

    tX = tX + xDir  -- If we're moving in the xDir, this will change tX by + or - 1
    tZ = tZ + zDir  -- If we're moving in the zDir, this will change tZ by + or - 1

    return true -- Turtle moved successfully
end

local function goDown(bCheckFuel)
    if bDebug then print("goDown()") end
    -- Can't move without fuel. checkFuel() will wait on player if necessary.
    if (bCheckFuel==true or bCheckFuel==nil) then
    checkFuel(tY<=0)    -- Passes boolean true if moving away from 0,0,0
  end

  local tries = 3
    while not turtle.down() do
        if bDebug then print("goDown: while not turtle.down() do tries="..tries) end
        if turtle.detectDown() then
            if bDebug then print("goDown: detectDown") end
            if not turtle.digDown() then
                print("Undiggable block encountered. Will retry in 5 seconds")
                -- Turtle is blocked. In case this is a temporary glitch, we try 3 times before conceding hard failure
                tries = tries - 1
                if (tries <= 0) then
                  return false
                else
                    if bDebug then print("goDown: sleep(5)") end
                  sleep(5) -- Wait 5 seconds, hope the problem resolves itself
                end
            end
        elseif turtle.attackDown() then
            if bDebug then print("goDown: attack") end
            -- Had to attack player or mob. You can add additional code here such
            -- as turtle.suck() if you want to collect killed mob loot. This is a quarry program
            -- to collect ores, not rotten flesh and bones, so this block is empty.
        else
            -- Unknown obstruction, possibly a player in
            -- peaceful or creative mode. Try again in 0.5 seconds and hope it's gone.
            if bDebug then print("goDown: sleep(0.5)") end
            sleep(0.5)
        end
    end

    tY = tY - 1
    return true -- Turtle moved successfully
end

local function goUp(bCheckFuel)
    if bDebug then print("goUp()") end

  -- Can't move without fuel. checkFuel() will wait on player if necessary.
  if (bCheckFuel==true or bCheckFuel==nil) then
    checkFuel(tY>=0)    -- Passes boolean true if moving away from 0,0,0
  end

  local tries = 3
    while not turtle.up() do
        if bDebug then print("goUp: while not loop tries="..tries) end
        if turtle.detectUp() then
            if bDebug then print("goUp: detectUp") end
              if not turtle.digUp() then
                        print("Undiggable block encountered. Will retry in 5 seconds.")
                        -- Turtle is blocked. In case this is a temporary glitch, we try 3 times before conceding hard failure
                tries = tries - 1
                if (tries <= 0) then
                  return false
                else
                  sleep(10) -- Wait 10 seconds, hope the problem resolves itself
                end
            end
        elseif turtle.attackUp() then
            if bDebug then print("goUp: attack") end
            -- Had to attack player or mob. You can add additional code here such
            -- as turtle.suck() if you want to collect killed mob loot. This is a quarry program
            -- to collect ores, not rotten flesh and bones, so this block is empty.
        else
            -- Unknown obstruction, possibly a player in
            -- peaceful or creative mode. Try again in 0.5 seconds and hope it's gone.
            if bDebug then print("goUp: sleep(0.5)") end
            sleep(0.5)
        end
    end

    tY = tY + 1
    return true -- Turtle moved successfully
end

local function orient(targetXdir, targetZdir)
    -- One of the supplied directions should be -1 or +1, the other should be 0.
    if ((targetXdir ~= 0) and (targetZdir ~= 0)) or ((targetXdir==0) and (targetZdir==0)) then
        print("orient() given mutually exclusive values: "..targetXdir..", "..targetZdir)
        return false
    end

    if (((targetXdir ~= 0) and (math.abs(targetXdir) ~= 1)) or ((targetZdir ~= 0) and (math.abs(targetZdir) ~= 1))) then
        print("orient() given bad values: "..targetXdir..", "..targetZdir)
        return false
    end

    if (targetXdir ~= 0) and (targetXdir ~= xDir) then
        -- x axis alignment requested, and differs from current alignment
        if (xDir ~= 0) then
            -- Turtle is x-axis aligned 180 from target
            turnLeft()
            turnLeft()
        elseif (zDir == targetXdir) then
            turnRight()
        else
            turnLeft()
        end
     elseif (targetZdir ~= 0) and (targetZdir ~= zDir) then
         -- z axis alignment requested, and differs from current alignment
        if (zDir ~= 0) then
            -- Turtle is z-axis aligned 180 from target
            turnLeft()
            turnLeft()
        elseif (xDir == targetZdir) then
            turnLeft()
        else
            turnRight()
        end
    end

    return true
end

local function goHome()
  -- This is similar to moveTo(0,0,0) but axis ordering of movement is reversed, so that turtle takes
  -- the same path to and from home location and where it left off. Also, this function passes false to
  -- goDown, goUp and goForward to make them skip the per-move fuel check, because making that check
  -- could result in circular function calling: goHome()->goFoward()->checkFuel()->goHome()->goFoward()->checkFuel().. etc.
  -- This function is set up to move along Y-axis first, then X, then finally Z, unless bReverse is true
  -- Note: The order doesn't matter much when digging out a space, but can matter when building something
  -- so that you don't dig a tunnel through what you're building.

  local fuelNeeded = math.abs(tX)+math.abs(tY)+math.abs(tZ)
  if not (turtle.getFuelLevel()=="unlimited") then
    if not (turtle.getFuelLevel()>=fuelNeeded) then
      print("Error: Turtle ended up in the unexpected state of not having enough fuel to return home.")
      return false
    end
  end

    while (tY<0) do
        if bDebug then print("goHome while tY<0 tY="..tY) end
        if not goUp(false) then
            -- Critical movement fail, bail
            return false
        end
    end

    while (tY>0) do
        if bDebug then print("goHome while tY>0 tY="..tY) end
        if not goDown(false) then
            -- Critical movement fail, bail
            return false
        end
    end

    -- If not at tX==targetX, move the right direction until tX==targetX
    if (tX>0) then orient(-1,0) end
    if (tX<0) then orient(1,0) end
    while (tX~=0) do
        if bDebug then print("goHome while tX~=0 tX="..tX) end
        if not goForward(false) then
        -- Critical movement fail, bail
        return false
        end
    end

    -- If not at tZ==targetZ, move the right direction until tZ==targetZ
    if (tZ>0) then orient(0,-1) end
    if (tZ<0) then orient(0,1) end
    while (tZ~=0) do
        if bDebug then print("goHome while tZ~=0 tZ="..tZ) end
        if not goForward(false) then
            -- Critical movement fail, bail
            return false
        end
    end

    return true
end

local function moveTo(targetX,targetZ,targetY)

    local fuelNeeded = math.abs(tX-targetX)+math.abs(tY-targetY)+math.abs(tZ-targetZ)
  if not (turtle.getFuelLevel()=="unlimited") then
    if not (turtle.getFuelLevel()>=fuelNeeded) then
      print("Error: Turtle ended up in the unexpected state of not having enough fuel to return home.")
      return false

    end
  end

    -- If not at tZ==targetZ, move the right direction until tZ==targetZ
    if (tZ>targetZ) then orient(0,-1) end
    if (tZ<targetZ) then orient(0,1) end
    while (tZ~=targetZ) do
        if bDebug then print("moveTo while tZ~=targetZ tZ="..tZ.." targetZ="..targetZ) end
        if not goForward(false) then
            -- Critical movement fail, bail
            return false
        end
    end

  -- If not at tX==targetX, move the right direction until tX==targetX
    if (tX>targetX) then orient(-1,0) end
    if (tX<targetX) then orient(1,0) end
    while (tX~=targetX) do
        if bDebug then print("moveTo while tX~=targetX tX="..tX.." targetX="..targetX) end
        if not goForward(false) then
            -- Critical movement fail, bail
            return false
        end
    end

    while (tY<targetY) do
        if bDebug then print("moveTo while tY<targetY tY="..tY.." targetY="..targetY) end
        if not goUp(false) then
            -- Critical movement fail, bail
            return false
        end
    end

    while (tY>targetY) do
        if bDebug then print("moveTo while tY>targetY tY="..tY.." targetY="..targetY) end
        if not goDown(false) then
            -- Critical movement fail, bail
            return false
        end
    end

  return true
end

function goUnload(bNeedsFuel)
    if bDebug then print("goUnload()") end
    -- Save position and orientation
    local saveX = tX
    local saveZ = tZ
    local saveY = tY
    local saveXdir = xDir
    local saveZdir = zDir

    if not goHome() then
    -- Critical failure to move
        return false
    end

    orient(0,-1)

    -- Drop items. Turtle will not empty the slot designated as the refuel slot.
    for i=1,16 do
        if (i ~= refuelSlot or turtle.getFuelLevel()=="unlimited") then
          turtle.select(i)
          turtle.drop()
        end
    end

    orient(0,1)

    -- Select first empty slot, might be a now-empty fuel slot, we don't really care
    for i=1,16 do
        if (turtle.getItemCount(i)==0) then
          turtle.select(i)
          break
        end
    end


    -- Since we had to bring the turtle all the way home, calculate
    -- the fuel needed to get back to where turtle left off mining, do at least one
    -- full layer's worth of work, plus approximately enough to get back home again. It would be
    -- silly to leave base with anything less than that, since the fuel would go nearly all to moving
    -- the turtle through already-mined space doing no work...
    local fuelNeeded = 2 * (math.abs(tX-saveX) + math.abs(tY-saveY) + math.abs(tZ-saveZ)) + (sizeX * sizeZ)
    if not (turtle.getFuelLevel()=="unlimited") then
      while (turtle.getFuelLevel() < fuelNeeded) do

        if bDebug then print("Entering while true do in goUnload fuel check stage") end

        -- Scan inventory for fuel
        local slot = 1
        turtle.select(slot)
        local bRefueled = false

        while true do
            if turtle.refuel(1) then
                -- Found fuel in current slot, consume 1, see if it's enough, if not loop again
                print("Consuming fuel item from slot "..slot)
                if (turtle.getFuelLevel()>=fuelNeeded) then
                    print("Refueled from inventory, resuming quarrying...")
                    bRefueled = true
                    break
                end
            else
                -- Couldn't refuel from currently-selected slot, try next slot. If there are no more slots, ask for player help.
                if (slot < 16) then
                    slot = slot + 1
                    turtle.select(slot)
                else
                    -- There are no more slots to look in, reset selection so that we're ready to loop over all slots again, and so that the
                    slot = 1
                    break
                end
            end
        end

        if not bRefueled then
            turtle.select(1)
            print("Please add more fuel items to the turtle and press any key. Has:"..turtle.getFuelLevel().." Needs:"..fuelNeeded)
            os.pullEvent("key")    -- suspend code execution awaiting user keypress
        end
      end
    end
    if not moveTo(saveX,saveZ,saveY) then
        -- Critical failure to move
        return false
    end

    orient(saveXdir,saveZdir)

    return true
end

local function checkFreeSlot()
  -- This function will return true if the designated refuelSlot is empty, because if there is no fuel reserve there, there
  -- is no reason not to allow item collection into this slot.
    for i=1,16 do
        if turtle.getItemCount(i)==0 then
          return true
        end
    end

  -- Turtle does not have empty slot, goUnload
    if not goUnload() then
        return false
    end

    return true
end

--[[

  START OF THE MAIN PROGRAM

--]]

checkFreeSlot()

local abort = false
local traversal = 1 -- Counts x-z layers we're rasterizing. Used to determine turning directions at end of columns and layers
local lowestY = 1-sizeY
local bDigBelow, bDigAbove = false, false -- initially false
while true do -- This loops digging layers
  print("Main loop traversal="..traversal.." tY="..tY.." lowestY="..lowestY)

  if (traversal==1) then --special case since turtle initially starts NOT on a layer that it just dug out.
    if ((tY - lowestY) == 0) then
        bDigBelow, bDigAbove = false, false
    elseif ((tY - lowestY) == 1) then
        bDigBelow, bDigAbove = true, false
    elseif ((tY - lowestY) >= 2) then
        bDigBelow, bDigAbove = true, true
        if not goDown() then
          -- Turtle can't dig down, adjust lowestY because we can't go as deep as planned
          lowestY = tY - 1
        end
    else
        -- Error: turtle is not in an expected place
        print("Error: Turtle vertical position is not what we expect on 1st traversal. Aborting, please debug.")
        abort = true
        break
    end
  else
    -- Not our first traversal, and turtle should now be on the last layer it dug out.
    if ((tY - lowestY) == 1) then
        bDigBelow, bDigAbove = true, false
    elseif ((tY - lowestY) == 2) then
        bDigBelow, bDigAbove = true, false
        if not goDown() then
          -- Turtle can't go down, adjust lowestY because we can't go as deep as planned
          lowestY = tY - 1
        end
    elseif ((tY - lowestY) >= 3) then
        bDigBelow, bDigAbove = true, true
        -- Try to descend 2, if either fails, adjust lowestY to just below where turtle is able to get to, and
        -- cancel the need to digAbove
        for j=1,2 do
            if not goDown() then
              -- Turtle can't dig down, adjust lowestY because we can't go as deep as planned
              lowestY = tY - 1
              bDigAbove = false
            end
        end
    else
        -- Error: turtle is not in an expected place
        print("Error: Turtle vertical position is not what we expect on traversal>1. Aborting, please debug.")
        abort = true
        break
    end
  end



  for column=1,sizeX  do  -- This loops sizeX times digging out columns
    for block=1,(sizeZ-1) do -- this loops (sizeZ-1) times doing digDown and goForward to do all but the end of each column

      -- Since we're about to do a potentially ore-digging move, check for free space in inventory.
      -- hasFreeSlot() calls goUnload if necessary
      if not checkFreeSlot() then
        print("Error: checkFreeSlot failure.")
        abort = true
        break
      end

      if bDigBelow and turtle.detectDown() then
        if not turtle.digDown() then
          -- Turtle can't dig down, but we're not moving down so this is not a fatal error.
          -- It might be bedrock below turtle, but that's not a concern until turtle is level with it.
        end
      end

      if bDigAbove and turtle.detectUp() then
        if not turtle.digUp() then
          -- Turtle can't dig up. This is actually concerning since we don't want to get him trapped under bedrock.
          -- Because of the danger of entrapment, we're ending our quarrying here.
          print("Turtle below undiggable block, backing out and returning home.")
          turnRight()
          turnRight()
          if not goForward() then
            -- This failure we care about, because there is something blocking us that we
            -- can't dig, attack or otherwise resolve. Bust out of our digging loops and attempt to return home
            print("Fatal Error during column goForward tX="..tX.." tZ="..tZ.." tY="..tY)
          end
          abort = true
          break
        end
        sleep(0.5) -- wait to see if anything falls on turtle from above (sand, gravel)

        -- First dig up was successful, so we haven't got an undiggable block above, and undiggables can't fall, so we can
        -- safely loop trying to dig up as long as something is falling on us (gravel, sand)
        while turtle.detectUp() do
            if bDebug then print("in while turtrle.detectUp() loop.") end
            if not turtle.digUp() then
                -- whatever is up there, we couldn't dig it, but it's not bedrock. Just move on...
                break
            end
            sleep(0.5)
        end
      end

      if not goForward() then
        -- This failure we care about, because there is something blocking us that we
        -- can't dig, attack or otherwise resolve. Bust out of our digging loops and attempt to return home
        -- after first checking to be sure the turtle is not under bedrock (if digging above)
        print("Fatal Error during column goForward tX="..tX.." tZ="..tZ.." tY="..tY)
        abort = true
        break
      end
    end -- end of block loop

    -- If movement failed while traversing column, escape out, backing out from under bedrock if needed
    if abort then
      if bDigAbove and turtle.detectUp() then
        if not turtle.digUp() then
          -- Turtle can't dig up. This is actually concerning since we don't want to get him trapped under bedrock.
          -- Because of the danger of entrapment, we're ending our quarrying here.
          print("Turtle below undiggable block, backing out and returning home.")
          turnRight()
          turnRight()
          if not goForward() then
            -- This failure we care about, because there is something blocking us that we
            -- can't dig, attack or otherwise resolve. Bust out of our digging loops and attempt to return home
            print("Fatal Error during column goForward tX="..tX.." tZ="..tZ.." tY="..tY)
          end
        end
      end

      -- unwinding
      break
    end

    -- Dig out the last block of this column
    if bDigBelow and turtle.detectDown() then
      if not turtle.digDown() then
        -- Turtle can't dig down, but we're not moving down so this is not a fatal error.
        -- It might be bedrock below turtle, but that's not a concern until turtle is level with it.
      end
    end

    -- Do last digUp in this column, if required by bDigAbove
    if bDigAbove and turtle.detectUp() then
        if not turtle.digUp() then
          -- Turtle can't dig up. This is actually concerning since we don't want to get him trapped under bedrock.
          -- Because of the danger of entrapment, we're ending our quarrying here.
          print("Turtle below undiggable block, backing out and returning home.")
          turnRight()
          turnRight()
          if not goForward() then
            -- This failure we care about, because there is something blocking us that we
            -- can't dig, attack or otherwise resolve. Bust out of our digging loops and attempt to return home
            print("Fatal Error during column goForward tX="..tX.." tZ="..tZ.." tY="..tY)
          end
          abort = true
          break
        end
        sleep(0.5) -- wait to see if anything falls on turtle from above (sand, gravel)

        -- First dig up was successful, so we haven't got an undiggable block above, and undiggables can't fall, so we can
        -- safely loop trying to dig up as long as something is falling on us (gravel, sand)
        while turtle.detectUp() do
            if bDebug then print("in while turtrle.detectUp() loop.") end
            if not turtle.digUp() then
                -- whatever is up there, we couldn't dig it, but it's not bedrock. Just move on...
                break
            end
            sleep(0.5)
        end
    end

    -- Turtle just finished the column, figure out if we need to advance to a new column, or
    -- if we've finished the layer. If we need to turn to start a new column, we have to figure out which
    -- direction to turn
    if (column<sizeX) then
      -- Turtle is at the end of a z column, but not the end of the whole x-z layer traversal

      -- FYI: These odd/even values are based on 1-based block, column, traversal numbers not 0-based tX, tZ, tY
      -- sorry if that's confusing, but Lua convention is to start loop indicies at 1
      local evenCol = ((column%2)==0)
      local evenWidth = ((sizeX%2)==0)
      local evenLayer = ((traversal%2)==0)
      local backtrackingLayer = (evenWidth and evenLayer)

      if ((not evenCol and not backtrackingLayer) or (evenCol and backtrackingLayer)) then
        turnRight() -- turn towards next row
        if not goForward() then
          print("Fatal Error during goForward from column "..column.." to column "..(column+1).." tX="..tX.." tZ="..tZ.." tY="..tY)
          abort = true
          break
        end

        -- Danger check to see if we've moved under an undiggable block
        if bDigAbove and turtle.detectUp() and not turtle.digUp() then
          print("Turtle below undiggable block, backing out 1 and returning home.")
          turnRight()
          turnRight()
          if not goForward() then
            -- This failure we care about, because there is something blocking us that we
            -- can't dig, attack or otherwise resolve. Bust out of our digging loops and attempt to return home
            print("Fatal Error during column goForward tX="..tX.." tZ="..tZ.." tY="..tY)
          end
          abort = true
          break
        end

        turnRight()
      else
        turnLeft()
        if not goForward() then
          print("Fatal Error during goForward from column "..column.." to column "..(column+1).." tX="..tX.." tZ="..tZ.." tY="..tY)
          abort = true
          break
        end

        -- Danger check to see if we've moved under an undiggable block
        if bDigAbove and turtle.detectUp() and not turtle.digUp() then
          print("Turtle below undiggable block, backing out 1 and returning home.")
          turnRight()
          turnRight()
          if not goForward() then
            -- This failure we care about, because there is something blocking us that we
            -- can't dig, attack or otherwise resolve. Bust out of our digging loops and attempt to return home
            print("Fatal Error during column goForward tX="..tX.." tZ="..tZ.." tY="..tY)
          end
          abort = true
          break
        end

        turnLeft()
      end
      -- Turtle is now ready to start the next column
    else
      -- Turtle is at the end of the layer, rotate 180
      turnRight()
      turnRight()
    end
  end -- end of column loop

  if abort then
    print("Abort breaking out of while true loop.")
    -- abort in progress, unwinding out of loops
    break
  end

  -- See if we're done yet
  if ((tY - lowestY) == 0) or (((tY - lowestY) == 1) and (bDigBelow == true)) then
    -- We're done. We've finished digging our lowest layer either by digging forward or with digDown.
    done = true
    break
  end

  -- If we got past the last if-then, we are not done, so we need to descend in preparation for next layer traversal
  if bDigBelow then
    -- We were digging below us on the traversal we just finished, so we need to drop down 2 levels to be on an undug layer
    -- First we try to descend through the dug-down layer, but since that could have bedrock (we we skimming above it not caring)
    -- we need to test to see if we can descend into that layer at our current tX,tZ location
    if not goDown() then
      print("Turtle finished a traversal and was digging below. Turtle can't go further down, we're done quarrying.")
      abort = true
      break
    end
  end

  traversal = traversal + 1
end -- end of while not done loop

-- Quarrying ended, either normally or because of encountering undiggable block. Try to return to 0,0,0
if not goHome(0,0,0) then
  -- Can't even get back home :-( Notify the user
  print("Turtle was not able to safely get back to starting location")
  abort = true
else
    orient(0,-1)

    -- Drop everything
    -- Drop items. Turtle will not empty the slot designated as the refuel slot.
  print("Unloading all contents...")
    for i=1,16 do
        turtle.select(i)
        turtle.drop()
    end
    orient(0,1)
end

if abort then
  print("Quarrying ended due to encounter with undiggable block.")
else
  print("Quarrying complete to desired depth.")
end