init.lua

--- Combines submodules.
-- This file combines all submodules into one module to tie everything together.
-- @module Pathfinder

-- Get the prefix to be used for requiring submodules.
-- This allows this folder to be named anything.
local prefix = ... .. "."

-- Simple sub-require function. Makes life easier.
local function _require( module )
  return require( prefix .. module )
end

-- Include all of the required files.
local Map = _require "Map"
local Path = _require "Path"
local TrackingTurtle = _require "TrackingTurtle"
local DontStop = _require "data.DontStopMovement"

-- Include CC modules
local expect = require "cc.expect".expect

-- Create our module
local M = {}

--- Create a new Pathfinder object.
-- @treturn table The pathfinder object.
function M.create()
  -- create all of the objects we will need.
  local map = Map.create()
  local trackingTurtle = TrackingTurtle.create()

  -- create the returned object
  local pathfinder = {}

  --- Take the result of a block scan and add it to the map.
  -- If the map is offset, this will add those offsets to the map.
  -- @tparam {{name=string,x=number,y=number,z=number,tags={string,...}},...} scanResult Pass the result of a scan (in specified format) to this function to add the information from it to the map.
  -- @tparam number? offsetx The offset to be applied to the X position of each scanned block.
  -- @tparam number? offsety The offset to be applied to the Y position of each scanned block.
  -- @tparam number? offsetz The offset to be applied to the Z position of each scanned block.
  function pathfinder.scan(scanResult, offsetx, offsety, offsetz)
    expect(1, scanResult, "table")
    expect(2, offsetx, "number", "nil")
    expect(3, offsety, "number", "nil")
    expect(4, offsetz, "number", "nil")
    offsetx = offsetx or 0
    offsety = offsety or 0
    offsetz = offsetz or 0
  end

  --- Sets a function which is run after every movement.
  -- This is useful for scanning! Set this to a function which scans the area then passes that to pathfinder.scan.
  -- Acts as a passthrough for TrackingTurtle.setMovementFunction
  -- @tparam function|nil f The function to run after each movement.
  function pathfinder.setMovementFunction(f)
    expect(1, f, "function", "nil")
    TrackingTurtle.setMovementFunction(f)
  end

  --- Get the current movement function.
  -- Acts as a passthrough for TrackingTurtle.getMovementFunction
  -- @treturn function|nil The function which is being run after each movement.
  function pathfinder.getMovementFunction()
    return TrackingTurtle.getMovementFunction()
  end

  --- Pathfind from one position to another.
  -- @tparam number x1 The starting X coordinate.
  -- @tparam number y1 The starting Y coordinate.
  -- @tparam number z1 The starting Z coordinate.
  -- @tparam number x2 The desired X coordinate.
  -- @tparam number y2 The desired Y coordinate.
  -- @tparam number z2 The desired Z coordinate.
  -- @treturn {{number,number,number},...} The path determined by the pathfinder.
  function pathfinder.pathfind(x1, y1, z1, x2, y2, z2)
    expect(1, x1, "number")
    expect(2, y1, "number")
    expect(3, z1, "number")
    expect(4, x2, "number")
    expect(5, y2, "number")
    expect(6, z2, "number")
  end

  --- Follow a path generated by the pathfind function.
  -- @tparam {{number,number,number},...} path The path to follow.
  -- @tparam number startIndex The position in the path to start from, useful if you needed to abort following the path and wish to return to it.
  -- @tparam boolean canBreakBlocks Enable if the turtle can break blocks.
  -- @tparam boolean canAttackMobs Enable if the turtle can attack mobs that get in the way.
  -- @tparam boolean canGoBack Enable if the turtle should optimize it's movements by moving backwards if needed.
  -- @treturn boolean, number? Whether or not pathfinding was successful. On failure, also returns the index the movement failed at.
  function pathfinder.followPath(path, startIndex, canBreakBlocks, canAttackMobs, canGoBack)
    expect(1, path, "table")
    expect(2, startIndex, "number", "nil")
    expect(3, canBreakBlocks, "boolean", "nil")
    expect(4, canAttackMobs, "boolean", "nil")
    expect(5, canGoBack, "boolean", "nil")
    startIndex = startIndex or 1

    for index, success, newPosition in Path.iteratePath(path, trackingTurtle, startIndex, canBreakBlocks, canAttackMobs, canGoBack) do
      if not success then return false, index end
    end

    return true
  end

  --- Get the Map object associated with this pathfinder object.
  -- @treturn table Map object.
  function pathfinder.getMap()
    return map
  end

  --- Get the Path object associated with this pathfinder object.
  -- @treturn table Path object.
  function pathfinder.getPathfinder()
    return path
  end

  --- Get the Tracking Turtle object associated with this pathfinder object.
  -- @treturn table TrackingTurtle object.
  function pathfinder.getTrackingTurtle()
    return trackingTurtle
  end

  return pathfinder
end

--- Load a pathfinder object from a file.
-- Acts mostly as a passthrough to Map.load().
-- @tparam string filename The file to load from, in absolute form.
-- @treturn boolean,table Whether the file loading was successful, and the data as a pathfinder object.
function M.load(filename)
  expect(1, filename, "string")
end

--- Save a pathfinder object to a file.
-- Acts mostly as a passthrough to Map.save().
-- @tparam string filename The file to save to, in absolute form.
-- @tparam table pathfinder The pathfinder object that was created via either create or load.
-- @treturn boolean Whether saving the file[s] was successful or not.
function M.save(filename, pathfinder)
  expect(1, filename, "string")
  expect(2, pathfinder, "table")
end

return M