Implement testing for blocks in front/above/below the turtle so we don't mine chests

.luarc.json

@@ -0,0 +1,9 @@
+{
+    "diagnostics.globals": [
+        "printError",
+        "turtle",
+        "shell",
+        "peripheral",
+        "parallel"
+    ]
+}

.vscode/settings.json

@@ -2,6 +2,8 @@
     "Lua.diagnostics.globals": [
         "printError",
         "turtle",
-        "shell"
+        "shell",
+        "peripheral",
+        "parallel"
     ]
 }

controller/audio_controller.lua

@@ -0,0 +1,87 @@
+local dfpwm = require("cc.audio.dfpwm")
+
+---@alias AudioControllerConfig {buffer_length_seconds: number}
+
+---@class AudioController
+---@field config AudioControllerConfig
+---@field play boolean
+local AudioController = {}
+AudioController.__index = AudioController
+
+---@return AudioController
+function AudioController:Create()
+	local t = {}
+	setmetatable(t, AudioController)
+
+	-----------------------------------------------------------------------------------------------
+	-- Fields
+	-----------------------------------------------------------------------------------------------
+	t.config = {
+		buffer_length_seconds = 1,
+	}
+	t.play = false
+
+	return t
+end
+
+-----------------------------------------------------------------------------------------------
+-- Audio Methods
+-----------------------------------------------------------------------------------------------
+
+function AudioController:PlayAudio(filename)
+	self.play = true
+
+	local decoder = dfpwm.make_decoder()
+	while self.play do
+		for chunk in io.lines(("audio/%s.dfpwm"):format(filename), self.config.buffer_length_seconds * 1024) do
+			if not self.play then
+				break
+			end
+
+			local buffer = decoder(chunk)
+
+			while not self:GetSpeaker().playAudio(buffer) do
+				if not self.play then
+					break
+				end
+
+				---@diagnostic disable-next-line: undefined-field
+				os.pullEvent("speaker_audio_empty")
+			end
+		end
+	end
+end
+
+function AudioController:PlayAudioFactory(filename)
+	local function play()
+		self:PlayAudio(filename)
+	end
+
+	return play
+end
+
+-----------------------------------------------------------------------------------------------
+-- Management Methods
+-----------------------------------------------------------------------------------------------
+
+---@return table | nil
+function AudioController:GetSpeaker()
+	return peripheral.find("speaker")
+end
+
+function AudioController:StopPlaying()
+	self.play = false
+	self:GetSpeaker().stop()
+end
+
+-----------------------------------------------------------------------------------------------
+-- Main Method
+-----------------------------------------------------------------------------------------------
+
+function AudioController:Run()
+	-- self:Configure()
+
+	self:PlayAudio("bangarang")
+end
+
+return AudioController

controller/audio_testing_controller.lua

@@ -0,0 +1,82 @@
+local TurtleController = require("controller.turtle_controller")
+local AudioController = require("controller.audio_controller")
+
+---@class AudioTestingController
+---@field controller TurtleController
+---@field audio AudioController
+local AudioTestingController = {}
+AudioTestingController.__index = AudioTestingController
+
+---@return AudioTestingController
+function AudioTestingController:Create()
+	local t = {}
+	setmetatable(t, AudioTestingController)
+
+	-----------------------------------------------------------------------------------------------
+	-- Fields
+	-----------------------------------------------------------------------------------------------
+	t.controller = TurtleController:Create()
+	t.audio = AudioController:Create()
+
+	return t
+end
+
+-----------------------------------------------------------------------------------------------
+-- Behavior Methods
+-----------------------------------------------------------------------------------------------
+
+function AudioTestingController:TestAudioWithoutMovement()
+	local function dancing()
+		for _ = 1, 256 do
+			self.controller:TurnRelative(1)
+		end
+		self.audio:StopPlaying()
+	end
+
+	parallel.waitForAll(dancing, self.audio:PlayAudioFactory("bangarang"))
+end
+
+function AudioTestingController:TestAudioWithMovement()
+	local function movement()
+		for _ = 1, 10 do
+			self.controller:MoveForward(10)
+			self.controller:MoveVertical(3)
+			self.controller:TurnRelative(2)
+			self.controller:MoveForward(10)
+			self.controller:MoveVertical(-3)
+			self.controller:TurnRelative(2)
+		end
+		self.audio:StopPlaying()
+	end
+
+	parallel.waitForAll(movement, self.audio:PlayAudioFactory("bangarang"))
+end
+
+-----------------------------------------------------------------------------------------------
+-- Main Method
+-----------------------------------------------------------------------------------------------
+
+function AudioTestingController:Run()
+	self.controller:Configure()
+	self.controller:DisableMiningForward()
+	self.controller:DisableMiningAbove()
+	self.controller:DisableMiningBelow()
+
+	print("There are multiple tests available:")
+	print("1: Audio without movement")
+	print("2: Audio with movement")
+
+	local choice = 0
+	while choice < 1 or choice > 2 do
+		print("Choose a test by entering its number:")
+		choice = tonumber(io.read()) or 0
+	end
+
+	if choice == 1 then
+		self:TestAudioWithoutMovement()
+	elseif choice == 2 then
+		self:TestAudioWithMovement()
+	end
+end
+
+return AudioTestingController

controller/excavation_controller.lua

@@ -0,0 +1,330 @@
+local Direction = require("lib.direction")
+local TurtleController = require("controller.turtle_controller")
+local AudioController = require("controller.audio_controller")
+
+---@alias ExcavationControllerConfig {slice_length: number, slice_height: number, center_slice_width: number, slice_width: number, slice_padding: number, slices_left: number, slices_right: number}
+
+---@class ExcavationController
+---@field controller TurtleController
+---@field audio AudioController
+---@field config ExcavationControllerConfig
+local ExcavationController = {}
+ExcavationController.__index = ExcavationController
+
+---@return ExcavationController
+function ExcavationController:Create()
+	local t = {}
+	setmetatable(t, ExcavationController)
+
+	-----------------------------------------------------------------------------------------------
+	-- Fields
+	-----------------------------------------------------------------------------------------------
+
+	t.controller = TurtleController:Create()
+	t.audio = AudioController:Create()
+	t.config = {
+		slice_length = 0,
+		slice_height = 0,
+		center_slice_width = 0,
+		slice_width = 0,
+		slice_padding = 0,
+		slices_left = 0,
+		slices_right = 0,
+	}
+
+	return t
+end
+
+-----------------------------------------------------------------------------------------------
+-- Behavior Methods
+-----------------------------------------------------------------------------------------------
+
+---Excavates a single 1x1/1x2 tunnel of configured length.
+---Will leave the turtle wherever it ends up.
+---Only unstocks/refuels if required.
+---@param mine_above boolean
+---@param mine_below boolean
+function ExcavationController:Excavate_1x1or2or3xL(mine_above, mine_below)
+	self.controller:EnableMiningForward()
+	if mine_above then
+		self.controller:EnableMiningAbove()
+	end
+	if mine_below then
+		self.controller:EnableMiningBelow()
+	end
+
+	self.controller:MoveForward(self.config.slice_length)
+
+	self.controller:DisableMiningForward()
+	self.controller:DisableMiningAbove()
+	self.controller:DisableMiningBelow()
+end
+
+---Excavates a single 1xH partial slice of configured length.
+---Will leave the turtle in its starting position.
+---Only unstocks/refuels if required.
+function ExcavationController:Excavate_1xHxL()
+	self.controller:StorePosition()
+
+	-- We can mine 2 blocks heigh in a single go
+	local number_of_1x3xL = math.floor(self.config.slice_height / 3)
+
+	-- Prepare for mining the blocks below the turtle
+	if number_of_1x3xL > 0 then
+		self.controller:EnableMiningAbove()
+		self.controller:MoveVertical(1)
+		self.controller:DisableMiningAbove()
+	end
+
+	-- Mine 1x3xL
+	for i = 1, number_of_1x3xL do
+		self:Excavate_1x1or2or3xL(true, true)
+
+		self.controller:TurnRelative(2)
+
+		-- Don't move upwards in the last iteration so we can decide
+		-- how much to move depending on how much we still have to excavate
+		if i == number_of_1x3xL then
+			break
+		end
+
+		self.controller:EnableMiningAbove()
+		self.controller:MoveVertical(4)
+		self.controller:MoveVertical(-1)
+		self.controller:DisableMiningAbove()
+	end
+
+	-- Mine remaining 1x2xL or 1x1xL
+	if self.config.slice_height % 3 == 2 then
+		self.controller:EnableMiningAbove()
+		self.controller:MoveVertical(3)
+		self.controller:MoveVertical(-1)
+		self.controller:DisableMiningAbove()
+
+		self:Excavate_1x1or2or3xL(true, false)
+	elseif self.config.slice_height % 3 == 1 then
+		self.controller:EnableMiningAbove()
+		self.controller:MoveVertical(3)
+		self.controller:MoveVertical(-1)
+		self.controller:DisableMiningAbove()
+
+		self:Excavate_1x1or2or3xL(false, false)
+	end
+
+	self.controller:EnableMiningBelow()
+	self.controller:MoveBack()
+	self.controller:DisableMiningBelow()
+end
+
+---Excavates a single WxH slice of configured length (EAST to WEST).
+---Will leave the turtle in its starting position.
+---Only unstocks/refuels if required.
+---@param center_slice boolean | nil
+function ExcavationController:Excavate_WxHxL(center_slice)
+	self.controller:StorePosition()
+
+	center_slice = center_slice or false
+	local width = center_slice and self.config.center_slice_width or self.config.slice_width
+
+	for i = 1, width do
+		self:Excavate_1xHxL()
+
+		if i == width then
+			break
+		end
+
+		self.controller:TurnToDirection(Direction.WEST)
+		self.controller:EnableMiningForward()
+		self.controller:EnableMiningAbove()
+		self.controller:MoveForward(1)
+		self.controller:DisableMiningForward()
+		self.controller:DisableMiningAbove()
+		self.controller:TurnToDirection(Direction.NORTH)
+	end
+
+	self.controller:MoveBack()
+end
+
+---Excavates all slices.
+---Will leave the turtle refueled and unstocked in its 0x0x0 position.
+function ExcavationController:Excavate()
+	-- Enter excavation area
+	self.controller:EnableMiningForward()
+	self.controller:EnableMiningAbove()
+	self.controller:MoveForward(1)
+	self.controller:DisableMiningForward()
+	self.controller:DisableMiningAbove()
+
+	-- Excavate center slice (start from right/back/bottom)
+	-- Uneven center widths will be centered, even center widths will have a block more on the right
+	print("Excavating center slice...")
+	local center_width_right = math.floor(self.config.center_slice_width / 2)
+	self.controller:StorePosition()
+	self.controller:TurnToDirection(Direction.EAST)
+	self.controller:EnableMiningForward()
+	self.controller:EnableMiningAbove()
+	self.controller:MoveForward(center_width_right)
+	self.controller:DisableMiningForward()
+	self.controller:DisableMiningAbove()
+	self.controller:TurnToDirection(Direction.NORTH)
+	self:Excavate_WxHxL(true)
+	self.controller:MoveBack() -- (0, 0, 1)
+
+	if self.config.slices_right > 0 then
+		-- Move to right slices starting location
+		local padded_width_right = self.config.slices_right * (self.config.slice_width + self.config.slice_padding)
+		self.controller:StorePosition()
+		self.controller:TurnToDirection(Direction.EAST)
+		self.controller:EnableMiningForward()
+		self.controller:EnableMiningAbove()
+		self.controller:MoveForward(center_width_right + padded_width_right)
+		self.controller:DisableMiningForward()
+		self.controller:DisableMiningAbove()
+		self.controller:TurnToDirection(Direction.NORTH)
+
+		-- Excavate right slices
+		print("Excavating right slices")
+		for i = 1, self.config.slices_right do
+			self:Excavate_WxHxL()
+
+			if i == self.config.slices_right then
+				break
+			end
+
+			-- Move to the next slice
+			self.controller:TurnToDirection(Direction.WEST)
+			self.controller:EnableMiningForward()
+			self.controller:EnableMiningAbove()
+			self.controller:MoveForward(self.config.slice_width + self.config.slice_padding)
+			self.controller:DisableMiningForward()
+			self.controller:DisableMiningAbove()
+			self.controller:TurnToDirection(Direction.NORTH)
+		end
+		self.controller:MoveBack() -- (0, 0, 1)
+	end
+
+	if self.config.slices_left > 0 then
+		-- Move to left slices starting location
+		local center_width_left = self.config.center_slice_width - center_width_right
+		self.controller:StorePosition()
+		self.controller:TurnToDirection(Direction.WEST)
+		self.controller:EnableMiningForward()
+		self.controller:EnableMiningAbove()
+		self.controller:MoveForward(center_width_left)
+		self.controller:DisableMiningForward()
+		self.controller:DisableMiningAbove()
+		self.controller:TurnToDirection(Direction.NORTH)
+
+		-- Excavate left slices
+		print("Excavate left slices")
+		for i = 1, self.config.slices_left do
+			-- Move to the next slice
+			self.controller:TurnToDirection(Direction.WEST)
+			self.controller:EnableMiningForward()
+			self.controller:EnableMiningAbove()
+			self.controller:MoveForward(self.config.slice_padding)
+			self.controller:DisableMiningForward()
+			self.controller:DisableMiningAbove()
+			self.controller:TurnToDirection(Direction.NORTH)
+
+			self:Excavate_WxHxL()
+
+			if i == self.config.slices_left then
+				break
+			end
+
+			self.controller:TurnToDirection(Direction.WEST)
+			self.controller:EnableMiningForward()
+			self.controller:EnableMiningAbove()
+			self.controller:MoveForward(self.config.slice_width)
+			self.controller:DisableMiningForward()
+			self.controller:DisableMiningAbove()
+			self.controller:TurnToDirection(Direction.NORTH)
+		end
+		self.controller:MoveBack() -- (0, 0, 1)
+	end
+
+	-- Finish up
+	self.controller:MoveToPosition(0, 0, 0, self.controller.config.storage_direction)
+	self.controller:DropInventoryIntoChest()
+	self.controller:TurnToDirection(Direction.NORTH)
+	self.audio:StopPlaying()
+end
+
+-----------------------------------------------------------------------------------------------
+-- Management Methods
+-----------------------------------------------------------------------------------------------
+
+function ExcavationController:Configure()
+	local config_complete = false
+
+	while not config_complete do
+		print("How long should each slice be?")
+		self.config.slice_length = tonumber(io.read()) or 3
+
+		print("How high should each slice be?")
+		self.config.slice_height = tonumber(io.read()) or 3
+
+		print("How wide should the center slice be?")
+		self.config.center_slice_width = tonumber(io.read()) or 1
+
+		print("How wide should the other slices be?")
+		self.config.slice_width = tonumber(io.read()) or 1
+
+		print("How many blocks should remain between each slice?")
+		self.config.slice_padding = tonumber(io.read()) or 0
+
+		print("How many slices should the turtle mine to its right?")
+		self.config.slices_right = tonumber(io.read()) or 1
+
+		print("How many slices should the turtle mine to its left?")
+		self.config.slices_left = tonumber(io.read()) or 1
+
+		local padded_width_left = self.config.slices_left * (self.config.slice_width + self.config.slice_padding)
+		local padded_width_right = self.config.slices_right * (self.config.slice_width + self.config.slice_padding)
+		local padded_width = padded_width_left + padded_width_right + self.config.center_slice_width
+		local mined_width_left = self.config.slices_left * self.config.slice_width
+		local mined_width_right = self.config.slices_right * self.config.slice_width
+		local mined_width = mined_width_left + mined_width_right + self.config.center_slice_width
+
+		print("Configuration complete!")
+		print(
+			("Mining area spans %d x %d x %d (width x height x forward), totalling %d blocks."):format(
+				padded_width,
+				self.config.slice_height,
+				self.config.slice_length,
+				padded_width * self.config.slice_height * self.config.slice_length
+			)
+		)
+		print(
+			("Turtle will mine %d block wide slices (%d wide in the center) with %d blocks of padding, totalling %d mined blocks."):format(
+				self.config.slice_width,
+				self.config.center_slice_width,
+				self.config.slice_padding,
+				mined_width * self.config.slice_height * self.config.slice_length
+			)
+		)
+		print("Do you want to accept the configuration (enter 1, otherwise 0)?")
+		config_complete = tonumber(io.read()) == 1
+	end
+end
+
+-----------------------------------------------------------------------------------------------
+-- Main Method
+-----------------------------------------------------------------------------------------------
+
+function ExcavationController:Run()
+	self.controller:Configure()
+	self:Configure()
+
+	-- Consume our starting fuel and refuel to the full amount
+	turtle.select(1)
+	turtle.refuel()
+	self.controller:RefuelIfEmpty()
+
+	parallel.waitForAll(function()
+		self:Excavate()
+	end, self.audio:PlayAudioFactory("bangarang"))
+end
+
+return ExcavationController

controller/testing_controller.lua

@@ -1,57 +0,0 @@
-local Direction = require("lib.direction")
-local TurtleController = require("controller.turtle_controller")
-
----@class TestingController
----@field controller TurtleController
-local TestingController = {}
-TestingController.__index = TestingController
-
-
----@return TestingController
-function TestingController:Create()
-    local t = {}
-    setmetatable(t, TestingController)
-
-    t.controller = TurtleController:Create()
-
-    return t
-end
-
-
------------------------------------------------------------------------------------------------
--- Behavior Methods
------------------------------------------------------------------------------------------------
-
-
-function TestingController:TestSimpleMovement()
-end
-
-
-function TestingController:TestComplexMovement()
-end
-
-
-function TestingController:TestUnloading()
-end
-
-
-function TestingController:TestRefueling()
-end
-
-
------------------------------------------------------------------------------------------------
--- Main Method
------------------------------------------------------------------------------------------------
-
-
-function TestingController:Run()
-    self.controller:Configure()
-
-    self:TestSimpleMovement()
-    self:TestComplexMovement()
-    self:TestUnloading()
-    self:TestRefueling()
-end
-
-
-return TestingController

controller/turtle_controller.lua

@@ -8,25 +8,21 @@ local Stack = require("lib.stack")
 ---@field config TurtleControllerConfig
 ---@field position Position
 ---@field last_positions Stack
----@field mine boolean
+---@field mine_forward boolean
+---@field mine_above boolean
+---@field mine_below boolean
 local TurtleController = {}
 TurtleController.__index = TurtleController
 
-
--- TODO: Test if there's a chest when dropping/sucking/mining (don't mine chests!)
-
-
 ---@return TurtleController
 function TurtleController:Create()
 	local t = {}
 	setmetatable(t, TurtleController)
 
-
 	-----------------------------------------------------------------------------------------------
 	-- Fields
 	-----------------------------------------------------------------------------------------------
 
-
 	t.config = {
 		fuel_direction = Direction.EAST,
 		fuel_name = turtle.getItemDetail(1) == nil and "" or turtle.getItemDetail(1).name,
@@ -36,35 +32,36 @@ function TurtleController:Create()
 	}
 	t.position = Position:Empty()
 	t.last_positions = Stack:Create()
-    t.mine = false
+	t.mine_forward = false
-
+	t.mine_above = false
+	t.mine_below = false
 
 	return t
 end
 
-
 -----------------------------------------------------------------------------------------------
 -- Movement Methods
 -----------------------------------------------------------------------------------------------
 
-
 ---Positive numbers turn clockwise, negative numbers turn counterclockwise
 ---@param number_of_turns number
 function TurtleController:TurnRelative(number_of_turns)
-    if number_of_turns == 0 then
+	if number_of_turns % 4 == 0 then
 		return
 	end
 
-    print(("Turtle is turning by %d..."):format(number_of_turns))
-
-    self:RefuelIfEmpty()
-
 	-- Turn turtle
-    for _ = 1,math.abs(number_of_turns) do
+	local turns = number_of_turns % 4
-        if number_of_turns > 0 then
+	if turns == 3 then
-            turtle.turnRight()
+		-- print(("Turtle is turning by %d (shortened to %d)..."):format(number_of_turns, -1))
-        else
+
+		-- If we're rotating by 3, we could turn faster by rotating by 1 in the opposite direction
 		turtle.turnLeft()
+	else
+		-- print(("Turtle is turning by %d (shortened to %d)..."):format(number_of_turns, turns))
+
+		for _ = 1, turns do
+			turtle.turnRight()
 		end
 	end
 
@@ -72,54 +69,61 @@ function TurtleController:TurnRelative(number_of_turns)
 	self.position.dir = (self.position.dir + number_of_turns) % 4
 end
 
-
 ---@param direction Direction
 function TurtleController:TurnToDirection(direction)
 	if self.position.dir == direction then
 		return
 	end
 
-    print(("Turtle is turning to direction %d..."):format(direction))
+	self:TurnRelative(direction - self.position.dir)
-
-    self:RefuelIfEmpty()
-
-    local rotation = direction - self.position.dir
-    if math.abs(rotation) == 3 then
-        -- If we're rotating by 3, we could turn faster by rotating by 1 in the opposite direction
-        rotation = -1 * (rotation - 1)
 end
 
-    self:TurnRelative(rotation)
-end
-
-
 ---Move forward by a number of blocks depending on the current rotation
 ---@param number_of_blocks number
-function TurtleController:MoveRelative(number_of_blocks)
+---@param skip_unstocking boolean | nil
+---@param skip_refueling boolean | nil
+function TurtleController:MoveForward(number_of_blocks, skip_unstocking, skip_refueling)
+	skip_unstocking = skip_unstocking or false
+	skip_refueling = skip_refueling or false
 	if number_of_blocks == 0 then
 		return
 	end
 
-    print(("Turtle is moving forward by %d blocks..."):format(number_of_blocks))
+	-- print(("Turtle is moving forward by %d blocks..."):format(number_of_blocks))
 
 	for _ = 1, math.abs(number_of_blocks) do
+		if not skip_refueling then
 			self:RefuelIfEmpty()
+		end
+		if not skip_unstocking then
 			self:UnstockIfFull()
+		end
 
-        -- Break blocks
+		-- Mine/Move
-        if self.mine then
+		if self.mine_forward then
 			while not turtle.forward() do
+				if self:TestForBlock("minecraft:chest") then
+					error("Won't mine because a chest is in the way!")
+				end
 				turtle.dig()
 			end
-            turtle.digUp()
+		elseif not turtle.forward() then
-            turtle.digDown()
+			error("Turtle failed to move forward!")
-        else
-            if not turtle.forward() then
-                printError("Turtle wants to move without mining but is blocked!")
 		end
+		if self.mine_above then
+			if self:TestForBlock("minecraft:chest", true, false) then
+				error("Won't mine because a chest is in the way!")
+			end
+			turtle.digUp()
+		end
+		if self.mine_below then
+			if self:TestForBlock("minecraft:chest", false, true) then
+				error("Won't mine because a chest is in the way!")
+			end
+			turtle.digDown()
 		end
 
-        -- Update current_position
+		-- Update current position
 		if self.position.dir == Direction.NORTH then
 			self.position.z = self.position.z + 1
 		elseif self.position.dir == Direction.SOUTH then
@@ -132,28 +136,85 @@ function TurtleController:MoveRelative(number_of_blocks)
 	end
 end
 
+---Positive numbers move up, negative numbers move down.
+---@param number_of_blocks number
+---@param skip_unstocking boolean | nil
+---@param skip_refueling boolean | nil
+function TurtleController:MoveVertical(number_of_blocks, skip_unstocking, skip_refueling)
+	skip_unstocking = skip_unstocking or false
+	skip_refueling = skip_refueling or false
+	if number_of_blocks == 0 then
+		return
+	end
 
----@param x number
+	-- print(("Turtle is moving vertically by %d blocks..."):format(number_of_blocks))
----@param y number
+
----@param z number
+	local move_function = number_of_blocks > 0 and turtle.up or turtle.down
+	local mine_function = number_of_blocks > 0 and turtle.digUp or turtle.digDown
+	local mine_enabled = number_of_blocks > 0 and self.mine_above or self.mine_below
+
+	for _ = 1, math.abs(number_of_blocks) do
+		if not skip_refueling then
+			self:RefuelIfEmpty()
+		end
+		if not skip_unstocking then
+			self:UnstockIfFull()
+		end
+
+		-- Mine/Move
+		if mine_enabled then
+			while not move_function() do
+				if self:TestForBlock("minecraft:chest", number_of_blocks > 0, number_of_blocks < 0) then
+					error("Won't mine because a chest is in the way!")
+				end
+				mine_function()
+			end
+		elseif not move_function() then
+			error("Turtle failed to move vertically!")
+		end
+
+		-- Update current position
+		if number_of_blocks > 0 then
+			self.position.y = self.position.y + 1
+		elseif number_of_blocks < 0 then
+			self.position.y = self.position.y - 1
+		end
+	end
+end
+
+---Stores the current position on the stack so we can return using TurtleController:MoveBack()
+function TurtleController:StorePosition()
+	self.last_positions:Push(Position:Copy(self.position))
+end
+
+---Move to an absolute position. Stores the current position on the stack so we can return using TurtleController:MoveBack()
+---@param x number The EAST/WEST axis (grows from WEST to EAST)
+---@param y number The UP/DOWN axis (grows from DOWN to UP)
+---@param z number The NORTH/SOUTH axis (grows from SOUTH to NORTH)
 ---@param dir Direction
-function TurtleController:MoveToPosition(x, y, z, dir)
+---@param skip_unstocking boolean | nil
-    print(("Turtle is moving to (%d, %d, %d)..."):format(x, y, z))
+---@param skip_refueling boolean | nil
+function TurtleController:MoveToPosition(x, y, z, dir, skip_unstocking, skip_refueling)
+	-- print(("Turtle is moving to (%d, %d, %d)..."):format(x, y, z))
 
-    self:DisableMining()
+	-- Store the current position on the stack, so we can return using TurtleController:MoveBack()
 	self.last_positions:Push(Position:Copy(self.position))
 
-    -- Move south once (if possible) to not be blocked by the slice that is currently mined
+	-- Store mining config so we can restore it later
-    self:TurnToDirection(Direction.SOUTH)
+	local mine_forward = self.mine_forward
-    self:MoveRelative(1)
+	local mine_above = self.mine_above
+	local mine_below = self.mine_below
 
-    -- EAST/WEST axis (do first to not interfere with chests or unmined walls)
+	-- EAST/WEST axis (do first to not interfere with chests)
+	self:EnableMiningForward()
+	self:DisableMiningAbove()
+	self:DisableMiningBelow()
 	if self.position.x > x then
 		self:TurnToDirection(Direction.WEST)
 	elseif self.position.x < x then
 		self:TurnToDirection(Direction.EAST)
 	end
-    self:MoveRelative(math.abs(self.position.x - x))
+	self:MoveForward(math.abs(x - self.position.x), skip_unstocking, skip_refueling)
 
 	-- NORTH/SOUTH axis
 	if self.position.z > z then
@@ -161,35 +222,146 @@ function TurtleController:MoveToPosition(x, y, z, dir)
 	elseif self.position.z < z then
 		self:TurnToDirection(Direction.NORTH)
 	end
-    self:MoveRelative(math.abs(self.position.z - z))
+	self:MoveForward(math.abs(z - self.position.z), skip_unstocking, skip_refueling)
+
+	-- UP/DOWN axis
+	self:DisableMiningForward()
+	if y < self.position.y then
+		self:EnableMiningBelow()
+	elseif y > self.position.y then
+		self:EnableMiningAbove()
+	end
+	self:MoveVertical(y - self.position.y, skip_unstocking, skip_refueling)
 
 	-- Direction
 	self:TurnToDirection(dir or Direction.NORTH)
 
+	-- Restore mining config
+	if mine_forward then
+		self:EnableMiningForward()
+	else
+		self:DisableMiningForward()
+	end
+	if mine_above then
+		self:EnableMiningAbove()
+	else
+		self:DisableMiningAbove()
+	end
+	if mine_below then
+		self:EnableMiningBelow()
+	else
+		self:DisableMiningBelow()
+	end
+
 	-- Sanity check
 	if not (self.position.x == x and self.position.y == y and self.position.z == z and self.position.dir == dir) then
-        printError("TurtleController:MoveToPosition failed to move to target position!")
+		error("TurtleController:MoveToPosition failed to move to target position!")
 	end
 end
 
+---Move by a vector. Stores the current position on the stack so we can return using TurtleController:MoveBack()
+---@param x number The EAST/WEST axis (grows from WEST to EAST)
+---@param y number The UP/DOWN axis (grows from DOWN to UP)
+---@param z number The NORTH/SOUTH axis (grows from SOUTH to NORTH)
+---@param dir Direction
+---@param skip_unstocking boolean | nil
+---@param skip_refueling boolean | nil
+function TurtleController:MoveByVector(x, y, z, dir, skip_unstocking, skip_refueling)
+	self:MoveToPosition(
+		self.position.x + x,
+		self.position.y + y,
+		self.position.z + z,
+		dir,
+		skip_unstocking,
+		skip_refueling
+	)
+end
 
-function TurtleController:MoveBack()
+---Move to the previously stored position and pop this position from the stack.
-    local target_position = self.last_positions:Pop()
+---@param skip_unstocking boolean | nil
+---@param skip_refueling boolean | nil
+function TurtleController:MoveBack(skip_unstocking, skip_refueling)
+	local last_position = self.last_positions:Pop()
 
-    self:MoveToPosition(target_position.x, target_position.y, target_position.z, target_position.dir)
+	if last_position == nil then
+		error("Failed to obtain last_position to move back!")
+	else
+		self:MoveToPosition(
+			last_position.x,
+			last_position.y,
+			last_position.z,
+			last_position.dir,
+			skip_unstocking,
+			skip_refueling
+		)
+
+		-- Pop the stack because MoveToPosition pushes our current position
 		self.last_positions:Pop()
 	end
+end
 
+-----------------------------------------------------------------------------------------------
+-- Testing Methods
+-----------------------------------------------------------------------------------------------
+
+---@param block_name string
+---@param above boolean | nil
+---@param below boolean | nil
+---@return boolean
+function TurtleController:TestForBlock(block_name, above, below)
+	above = above or false
+	below = below or false
+	if above and below then
+		error("Can only test for blocks in one direction!")
+	end
+
+	local inspect_function = turtle.inspect
+	if above then
+		inspect_function = turtle.inspectUp
+	elseif below then
+		inspect_function = turtle.inspectDown
+	end
+
+	local has_block, block_data = inspect_function()
+
+	if not has_block then
+		return false
+	end
+
+	return block_data.name == block_name
+end
 
 -----------------------------------------------------------------------------------------------
 -- Inventory Methods
 -----------------------------------------------------------------------------------------------
 
+---@return boolean
+function TurtleController:HasFuel()
+	local level = turtle.getFuelLevel()
+	local distance_home = self.position.x + self.position.y + self.position.z
+
+	return level > distance_home + self.config.refuel_safety_margin
+end
+
+---@return boolean
+function TurtleController:HasInventorySpace()
+	for slot = 1, 16 do
+		if turtle.getItemDetail(slot) == nil then
+			return true
+		end
+	end
+
+	return false
+end
 
 ---@param slot number
 ---@param count number
 ---@return boolean
-function TurtleController:SuckItem(slot, count)
+function TurtleController:SuckItemFromChest(slot, count)
+	if not self:TestForBlock("minecraft:chest") then
+		error("Can't suck item: no chest!")
+	end
+
 	local previous_slot = turtle.getSelectedSlot()
 
 	turtle.select(slot or 1)
@@ -200,11 +372,14 @@ function TurtleController:SuckItem(slot, count)
 	return sucked
 end
 
-
 ---@param slot number
 ---@param count number
 ---@return boolean
-function TurtleController:DropItem(slot, count)
+function TurtleController:DropItemIntoChest(slot, count)
+	if not self:TestForBlock("minecraft:chest") then
+		error("Can't drop item: no chest!")
+	end
+
 	local previous_slot = turtle.getSelectedSlot()
 
 	turtle.select(slot or 1)
@@ -215,8 +390,11 @@ function TurtleController:DropItem(slot, count)
 	return dropped
 end
 
+function TurtleController:DropInventoryIntoChest()
+	if not self:TestForBlock("minecraft:chest") then
+		error("Can't drop item: no chest!")
+	end
 
-function TurtleController:DropInventory()
 	print("Dropping inventory into chest...")
 
 	for slot = 1, 16 do
@@ -227,32 +405,42 @@ function TurtleController:DropInventory()
 	turtle.select(1)
 end
 
-
+---@param skip_inventory_check boolean | nil
-function TurtleController:UnstockIfFull()
+function TurtleController:UnstockIfFull(skip_inventory_check)
-    if self:HasInventorySpace() then
+	skip_inventory_check = skip_inventory_check or false
+	if not skip_inventory_check and self:HasInventorySpace() then
 		return
 	end
+	if skip_inventory_check then
+		print(("HasInventorySpace() returned %s"):format(self:HasInventorySpace()))
+	end
 
 	print("Turtle is unstocking...")
 
-    self:MoveToPosition(0, 0, 0, self.config.storage_direction)
+	self:MoveToPosition(0, 0, 0, self.config.storage_direction, true, true)
-    self:DropInventory()
+	self:DropInventoryIntoChest()
 	self:RefuelIfEmpty()
 
-    self:MoveBack()
+	self:TurnToDirection(Direction.NORTH)
+	self:MoveForward(1)
+	self:MoveBack(true, true)
 end
 
-
+---@param skip_fuel_check boolean | nil
-function TurtleController:RefuelIfEmpty()
+function TurtleController:RefuelIfEmpty(skip_fuel_check)
-    if self:HasFuel() then
+	skip_fuel_check = skip_fuel_check or false
+	if not skip_fuel_check and self:HasFuel() then
 		return
 	end
+	if skip_fuel_check then
+		print(("HasFuel() returned %s"):format(self:HasFuel()))
+	end
 
 	print("Turtle is refueling...")
 
 	-- Clear our inventory into the storage chest
-    self:MoveToPosition(0, 0, 0, self.config.storage_direction)
+	self:MoveToPosition(0, 0, 0, self.config.storage_direction, true, true)
-    self:DropInventory()
+	self:DropInventoryIntoChest()
 
 	-- Prepare refueling
 	self:TurnToDirection(self.config.fuel_direction)
@@ -260,31 +448,41 @@ function TurtleController:RefuelIfEmpty()
 
 	-- Include the distance to the last position when refueling
 	-- to keep the amount of work done between refuelings constant
+	local target_fuel_level = self.config.refuel_amount
 	local last_position = self.last_positions:Peek()
-    local target_fuel_level = self.config.refuel_amount + last_position.x + last_position.y + last_position.z
+	if last_position == nil then
+		error("Failed to obtain last_position while refueling!")
+	else
+		target_fuel_level = target_fuel_level + last_position.x + last_position.y + last_position.z
+	end
 
 	-- Refuel until we hit the refuel_amount
 	local before_level = turtle.getFuelLevel()
 	repeat
-        if not self:SuckItem(1, 1) then
+		if not self:SuckItemFromChest(1, 1) then
-            printError("Failed to suck fuel out of fuel chest!")
+			error("Failed to suck fuel out of fuel chest!")
-            shell.exit()
 		end
 		turtle.refuel()
 	until turtle.getFuelLevel() >= target_fuel_level
 	local after_level = turtle.getFuelLevel()
 
-    self:MoveBack()
+	self:TurnToDirection(Direction.NORTH)
+	self:MoveForward(1)
+	self:MoveBack(true, true)
 
-    print(("Refuelled %d units, current level is %d (old level was %d)"):format(after_level - before_level, after_level, before_level))
+	print(
+		("Refuelled %d units, current level is %d (old level was %d)"):format(
+			after_level - before_level,
+			after_level,
+			before_level
+		)
+	)
 end
 
-
 -----------------------------------------------------------------------------------------------
 -- Management Methods
 -----------------------------------------------------------------------------------------------
 
-
 function TurtleController:Configure()
 	local config_complete = false
 
@@ -311,39 +509,38 @@ function TurtleController:Configure()
 		self.config.storage_direction = tonumber(io.read()) or Direction.EAST
 
 		print("Configuration complete!")
-        print(("Turtle will consume \"%s\" for fuel. Put the desired fuel into the first slot to change."):format(self.config.fuel_name))
+		print(
+			('Turtle will consume "%s" for fuel. Put the desired fuel into the first slot to change.'):format(
+				self.config.fuel_name
+			)
+		)
 		print("Do you want to accept the configuration (enter 1, otherwise 0)?")
 		config_complete = tonumber(io.read()) == 1
 	end
 end
 
-
+function TurtleController:EnableMiningForward()
-function TurtleController:EnableMining()
+	self.mine_forward = true
-    self.mine = true
 end
 
-
+function TurtleController:DisableMiningForward()
-function TurtleController:DisableMining()
+	self.mine_forward = false
-    self.mine = false
 end
 
-
+function TurtleController:EnableMiningAbove()
-function TurtleController:HasFuel()
+	self.mine_above = true
-    local level = turtle.getFuelLevel()
-    local distance_home = self.position.x + self.position.y + self.position.z
-
-    return level > distance_home + self.config.refuel_safety_margin
 end
 
-
+function TurtleController:DisableMiningAbove()
-function TurtleController:HasInventorySpace()
+	self.mine_above = false
-    for slot = 1,16 do
-        if turtle.getItemDetail(slot) == nil then
-            return true
-        end
 end
 
-    return false
+function TurtleController:EnableMiningBelow()
+	self.mine_below = true
+end
+
+function TurtleController:DisableMiningBelow()
+	self.mine_below = false
 end
 
 return TurtleController

controller/turtle_testing_controller.lua

@@ -0,0 +1,220 @@
+local Direction = require("lib.direction")
+local TurtleController = require("controller.turtle_controller")
+
+---@class TurtleTestingController
+---@field controller TurtleController
+local TurtleTestingController = {}
+TurtleTestingController.__index = TurtleTestingController
+
+---@return TurtleTestingController
+function TurtleTestingController:Create()
+	local t = {}
+	setmetatable(t, TurtleTestingController)
+
+	t.controller = TurtleController:Create()
+
+	return t
+end
+
+-----------------------------------------------------------------------------------------------
+-- Behavior Methods
+-----------------------------------------------------------------------------------------------
+
+function TurtleTestingController:TestRelativeMovementWithRelativeRotation()
+	print("Testing relative movement with relative rotation...")
+
+	-- N: BackCenter (Center)
+	self.controller:MoveForward(3)
+	self.controller:TurnRelative(1) -- E: FrontCenter (Center)
+	self.controller:MoveForward(3)
+	self.controller:TurnRelative(2) -- W: FrontRight (Center)
+	self.controller:MoveVertical(3)
+	self.controller:TurnRelative(8) -- W: FrontRight (Top)
+	self.controller:MoveForward(3)
+	self.controller:TurnRelative(3) -- S: FrontCenter (Top)
+	self.controller:MoveForward(3)
+	self.controller:TurnRelative(9) -- W: BackCenter (Top)
+	self.controller:MoveVertical(-3)
+	self.controller:TurnRelative(1) -- N: BackCenter (Center)
+
+	print("The turtle should be in its original location.")
+	print(
+		("The turtle has internal position (%d, %d, %d) and internal direction %d"):format(
+			self.controller.position.x,
+			self.controller.position.y,
+			self.controller.position.z,
+			self.controller.position.dir
+		)
+	)
+	print("Press Enter to continue")
+	_ = io.read()
+end
+
+function TurtleTestingController:TestRelativeMovementWithAbsoluteRotation()
+	print("Testing relative movement with absolute rotation...")
+
+	-- N: BackCenter (Center)
+	self.controller:MoveForward(3)
+	self.controller:TurnToDirection(Direction.EAST) -- E: FrontCenter (Center)
+	self.controller:MoveForward(3)
+	self.controller:TurnToDirection(Direction.WEST) -- W: FrontRight (Center)
+	self.controller:MoveVertical(3)
+	self.controller:TurnToDirection(Direction.WEST) -- W: FrontRight (Top)
+	self.controller:MoveForward(3)
+	self.controller:TurnToDirection(Direction.SOUTH) -- S: FrontCenter (Top)
+	self.controller:MoveForward(3)
+	self.controller:TurnToDirection(Direction.WEST) -- W: BackCenter (Top)
+	self.controller:MoveVertical(-3)
+	self.controller:TurnToDirection(Direction.NORTH) -- N: BackCenter (Center)
+
+	print("The turtle should be in its original location.")
+	print(
+		("The turtle has internal position (%d, %d, %d) and internal direction %d"):format(
+			self.controller.position.x,
+			self.controller.position.y,
+			self.controller.position.z,
+			self.controller.position.dir
+		)
+	)
+	print("Press Enter to continue")
+	_ = io.read()
+end
+
+function TurtleTestingController:TestAbsoluteMovementWithoutStack()
+	print("Testing absolute movement without stack...")
+
+	-- N: BackCenter (Center)
+	self.controller:MoveToPosition(0, 0, 3, Direction.EAST) -- E: FrontCenter (Center)
+	self.controller:MoveToPosition(3, 0, 3, Direction.WEST) -- W: FrontRight (Center)
+	self.controller:MoveToPosition(3, 3, 3, Direction.WEST) -- W: FrontRight (Top)
+	self.controller:MoveToPosition(0, 3, 3, Direction.SOUTH) -- S: FrontCenter (Top)
+	self.controller:MoveToPosition(0, 3, 0, Direction.WEST) -- W: BackCenter (Top)
+	self.controller:MoveToPosition(0, 0, 0, Direction.NORTH) -- N: BackCenter (Center)
+
+	print("The turtle should be in its original location.")
+	print(
+		("The turtle has internal position (%d, %d, %d) and internal direction %d"):format(
+			self.controller.position.x,
+			self.controller.position.y,
+			self.controller.position.z,
+			self.controller.position.dir
+		)
+	)
+	print("Press Enter to continue")
+	_ = io.read()
+end
+
+function TurtleTestingController:TestAbsoluteMovementWithStack()
+	print("Testing absolute movement with stack...")
+
+	-- N: BotCenter (Center)
+	self.controller:MoveToPosition(0, 0, 3, Direction.EAST) -- E: TopCenter (Center)
+	self.controller:MoveBack() -- N: BotCenter (Center)
+	self.controller:MoveToPosition(3, 3, 3, Direction.WEST) -- W: TopRight (Top)
+	self.controller:MoveBack() -- N: BotCenter (Center)
+
+	print("The turtle should be in its original location.")
+	print(
+		("The turtle has internal position (%d, %d, %d) and internal direction %d"):format(
+			self.controller.position.x,
+			self.controller.position.y,
+			self.controller.position.z,
+			self.controller.position.dir
+		)
+	)
+	print("Press Enter to continue")
+	_ = io.read()
+end
+
+function TurtleTestingController:TestUnstocking()
+	print("Testing inventory unloading...")
+
+	self.controller:MoveToPosition(3, 0, 3, Direction.WEST)
+	print("Please fill the entire inventory with items.")
+	print("Press Enter to continue")
+	_ = io.read()
+	self.controller:UnstockIfFull(true)
+	print("Press Enter to continue")
+	_ = io.read()
+	self.controller:MoveBack()
+
+	print("The turtle should be in its original location.")
+	print("Press Enter to continue")
+	_ = io.read()
+end
+
+function TurtleTestingController:TestRefueling()
+	print("Testing refueling...")
+
+	self.controller:MoveToPosition(3, 0, 3, Direction.WEST)
+	print("Please fill multiple inventory slots with items.")
+	print("Press Enter to continue")
+	_ = io.read()
+	self.controller:RefuelIfEmpty(true)
+	print("Press Enter to continue")
+	_ = io.read()
+	self.controller:MoveBack()
+
+	print("The turtle should be in its original location.")
+	print("Press Enter to continue")
+	_ = io.read()
+end
+
+-----------------------------------------------------------------------------------------------
+-- Main Method
+-----------------------------------------------------------------------------------------------
+
+function TurtleTestingController:Run()
+	self.controller:Configure()
+	self.controller:DisableMiningForward()
+	self.controller:DisableMiningAbove()
+	self.controller:DisableMiningBelow()
+
+	print("There are multiple tests available:")
+	print("1: Relative movement with relative rotation")
+	print("2: Relative movement with absolute rotation")
+	print("3: Absolute movement without stack")
+	print("4: Absolute movement with stack")
+	print("5: All movement tests")
+	print("6: Unloading")
+	print("7: Refueling")
+	print("8: All non-movement tests")
+	print("9: All tests")
+
+	local choice = 0
+	while choice < 1 or choice > 9 do
+		print("Choose a test by entering its number:")
+		choice = tonumber(io.read()) or 0
+	end
+
+	if choice == 1 then
+		self:TestRelativeMovementWithRelativeRotation()
+	elseif choice == 2 then
+		self:TestRelativeMovementWithAbsoluteRotation()
+	elseif choice == 3 then
+		self:TestAbsoluteMovementWithoutStack()
+	elseif choice == 4 then
+		self:TestAbsoluteMovementWithStack()
+	elseif choice == 5 then
+		self:TestRelativeMovementWithRelativeRotation()
+		self:TestRelativeMovementWithAbsoluteRotation()
+		self:TestAbsoluteMovementWithoutStack()
+		self:TestAbsoluteMovementWithStack()
+	elseif choice == 6 then
+		self:TestUnstocking()
+	elseif choice == 7 then
+		self:TestRefueling()
+	elseif choice == 8 then
+		self:TestUnstocking()
+		self:TestRefueling()
+	elseif choice == 9 then
+		self:TestRelativeMovementWithRelativeRotation()
+		self:TestRelativeMovementWithAbsoluteRotation()
+		self:TestAbsoluteMovementWithoutStack()
+		self:TestAbsoluteMovementWithStack()
+		self:TestUnstocking()
+		self:TestRefueling()
+	end
+end
+
+return TurtleTestingController

controller/volume_excavation_controller.lua

@@ -1,130 +0,0 @@
-local Direction = require("lib.direction")
-local TurtleController = require("controller.turtle_controller")
-
----@alias VolumeExcavationControllerConfig {mine_forward: number, mine_left: number, mine_right: number}
-
----@class VolumeExcavationController
----@field controller TurtleController
----@field config VolumeExcavationControllerConfig
-local VolumeExcavationController = {}
-VolumeExcavationController.__index = VolumeExcavationController
-
-
----@return VolumeExcavationController
-function VolumeExcavationController:Create()
-    local t = {}
-    setmetatable(t, VolumeExcavationController)
-
-
-    -----------------------------------------------------------------------------------------------
-    -- Fields
-    -----------------------------------------------------------------------------------------------
-
-
-    t.controller = TurtleController:Create()
-    t.config = {
-        mine_forward = 0,
-        mine_left = 0,
-        mine_right = 0,
-    }
-
-
-    return t
-end
-
-
------------------------------------------------------------------------------------------------
--- Behavior Methods
------------------------------------------------------------------------------------------------
-
-
-function VolumeExcavationController:Excavate()
-    print(("Turtle is mining layer at y=%d..."):format(self.controller.position.y))
-
-    -- Enter the excavation area
-    self.controller:EnableMining()
-    self.controller:MoveRelative(1)
-
-    -- Move to the bottom right corner of the layer
-    self.controller:TurnToDirection(Direction.EAST)
-    self.controller:MoveRelative(self.config.mine_right)
-    self.controller:TurnToDirection(Direction.WEST)
-
-    -- Zig zag mine back to front
-    -- The direction is important so we can travel to start without colliding with unminded walls
-    local turn_dir = 1
-    for i = 1,self.config.mine_forward do
-        self.controller:MoveRelative(self.config.mine_left + self.config.mine_right)
-
-        -- Skip the last turn, as we won't mine that slice
-        -- We want to stay in the mined area so we can move back freely
-        if i == self.config.mine_forward then
-            break
-        end
-
-        self.controller:TurnRelative(turn_dir)
-        self.controller:MoveRelative(1)
-        self.controller:TurnRelative(turn_dir)
-
-        turn_dir = -1 * turn_dir
-    end
-
-    self.controller:MoveToPosition(0, 0, 0, Direction.NORTH)
-
-    -- Unload before doing the next layer
-    self.controller:TurnToDirection(self.controller.config.storage_direction)
-    self.controller:DropInventory()
-    self.controller:TurnToDirection(Direction.NORTH)
-end
-
-
------------------------------------------------------------------------------------------------
--- Management Methods
------------------------------------------------------------------------------------------------
-
-
-function VolumeExcavationController:Configure()
-    local config_complete = false
-
-    while not config_complete do
-        print("How many blocks should the turtle mine forward?")
-        self.config.mine_forward = tonumber(io.read()) or 3
-
-        print("How many blocks should the turtle to its right?")
-        self.config.mine_right = tonumber(io.read()) or 3
-
-        print("How many blocks should the turtle mine to its left?")
-        self.config.mine_left = tonumber(io.read()) or 3
-
-        local width = self.config.mine_left + self.config.mine_right + 1
-        local height = 3
-
-        print("Configuration complete!")
-        print(("Turtle will mine an area of %d x %d x %d (forward x width x height) totalling %d blocks."):format(
-            self.config.mine_forward, width, height, self.config.mine_forward * width * height
-        ))
-        print("Do you want to accept the configuration (enter 1, otherwise 0)?")
-        config_complete = tonumber(io.read()) == 1
-    end
-end
-
-
------------------------------------------------------------------------------------------------
--- Main Method
------------------------------------------------------------------------------------------------
-
-
-function VolumeExcavationController:Run()
-    self.controller:Configure()
-    self:Configure()
-
-    -- Consume our starting fuel and refuel to the full amount
-    turtle.select(1)
-    turtle.refuel()
-    self.controller:RefuelIfEmpty()
-
-    self:Excavate()
-end
-
-
-return VolumeExcavationController

lib/direction.lua

@@ -3,7 +3,7 @@ local Direction = {
 	NORTH = 0,
 	EAST = 1,
 	SOUTH = 2,
-    WEST = 3
+	WEST = 3,
 }
 
 return Direction

lib/position.lua

@@ -8,7 +8,6 @@ local Direction = require("lib.direction")
 local Position = {}
 Position.__index = Position
 
-
 ---@return Position
 function Position:Empty()
 	local t = {}

lib/stack.lua

@@ -1,9 +1,8 @@
 ---@class Stack
----@field elements table[]
+---@field elements Position[]
 local Stack = {}
 Stack.__index = Stack
 
-
 ---@return Stack
 function Stack:Create()
 	-- stack table
@@ -16,33 +15,39 @@ function Stack:Create()
 	return t
 end
 
-
+---@param element Position
----@param element table
 function Stack:Push(element)
 	if element == nil or element == {} then
+		printError("Failed to push empty element to the stack!")
 		return
 	end
 
 	table.insert(self.elements, element)
 end
 
-
+---@return Position | nil
----@return table
 function Stack:Pop()
+	if self:Count() == 0 then
+		printError("Failed to pop element from the empty stack!")
+		return nil
+	end
+
 	return table.remove(self.elements)
 end
 
-
+---@return Position | nil
----@return table
 function Stack:Peek()
-    return table[#self.elements]
+	if self:Count() == 0 then
+		printError("Failed to peek element from the empty stack!")
+		return nil
 	end
 
+	return self.elements[#self.elements]
+end
 
 ---@return number
 function Stack:Count()
 	return #self.elements
 end
 
-
 return Stack

main.lua

@@ -1,15 +1,20 @@
-local TestingController = require("controller.testing_controller")
+local TurtleTestingController = require("controller.turtle_testing_controller")
-local VolumeExcavationController = require("controller.volume_excavation_controller")
+local AudioTestingController = require("controller.audio_testing_controller")
-
+local ExcavationController = require("controller.excavation_controller")
+local AudioController = require("controller.audio_controller")
 
 local controllers = {
-    TestingController:Create(),
+	TurtleTestingController:Create(),
-    VolumeExcavationController:Create(),
+	AudioTestingController:Create(),
+	ExcavationController:Create(),
+	AudioController:Create(),
 }
 
 print("Multiple controllers are available:")
-print("1: Testing Mode")
+print("1: Turtle Testing Mode")
-print("2: Volume Excavation")
+print("2: Audio Testing Mode")
+print("3: Volume Excavation")
+print("4: Play Bangarang")
 
 local choice = 0
 while choice < 1 or choice > #controllers do
@@ -18,3 +23,14 @@ while choice < 1 or choice > #controllers do
 end
 
 controllers[choice]:Run()
+
+-- TODO: When refueling but chest is missing, wait there until the user puts a chest with fuel
+-- TODO: Improve error handling: Don't abort the program in all cases,
+--       but wait until the user fixes the issue (e.g. places a chest)
+
+-- TODO: Add shortcuts for the volume excavation:
+--       - Tunnel forward 3x2 or 3x3 with specified length
+--       - Excavate downwards (quarry) in a square, specify side length
+-- TODO: Add controller to build rooms with walls of a specified material
+-- TODO: Add a stair building mode (specify side length, min 2x2)
+-- TODO: Add configurable trash_list with items that won't be picked up