Turtle Tracker - The turtle now magically keeps track of where she is

What it does:

It modifies the default Turtle's API's functions to add a tracking functionnality.
It adds four new variables that you may use in any program:

• turtle.x
• turtle.y
• turtle.z
• turtle.facing
• turtle.goto(x,y,z)
• y being the height if you choose to install the version with the good ole' weird minecraft coordinates
• It's not optimized. See this post
• turtle.turnTo(direction)
• It's optimized ! It will never turn thrice.

By default, the turtle thinks she's located at 0,0,0 and that it mentally faces the north. You can change that by modifying yourself those variables.
To correct that, you could ask the user where the turtle is currently located and modify them upon startup.

These variables are updated in real time when you use turtle.forward, turtle.back, turtle.up, turtle.down, turtle.turnRight or turtle.turnLeft.

If you are a cool person, you could save the content of the variables upon shutdown with bwhodle's great .ini config files API on this very forum
Details for advanced users

A fifth variable was also added, it is a function called

• turtle.onEachMove

This function is called every time the turtle turns or moves. You modify it like so:

local function myFunc()
	--do stuff
end
turtle.onEachMove=myFunc

You can use it for various things, for instance, displaying the coordinates of the turtle in real time:


How do I use it ?

The API must be launched before the turtle turns or moves, for accuracy.
It can be launched at startup automatically by using

shell.run("turtleAPI")

That's it.
Installing

I made two versions, one with regular coordinates (north is x+1, east is y+1, up is z+1) for sane people

pastebin get GXABjDpr turtleAPI

And one with real minecraft coordinates (north is z-1, east is x+1, up is y+1) so that the turtle's mental position and its real coordinates will match up, for those who might need it

pastebin get Su3BWPb8 turtleAPI

Useful to quickly code a "return to home" program. Any plans to build some other apis and/or programs on top of this?

--#movement
turtle.goto(x,y,z,facing,break) --# break being a bool whether to break occupying blocks or to abort.
turtle.find(x,y,z,facing,searchLimit) --#trying to find alternative route, when blocks are occupying. searchLimit being a factor to the shortest path determining when to abort. So searchLimit 2 will abort, after the turtle has made 2 times the amount of moves it takes to get to target in a straight line.
turtle.memorize(yes) --#enable/disable saving of the movements
turtle.backtrack(x,y,z,facing,break) --#works, when memorize is enabled; will use the same path to get back to the specific block

--#mapping
turtle.scan(yes) --#enable/disable saving block data after/before each movement
turtle.getBlock(x,y,z) --#return memorized block at mental position. (possibly with an extra field of how long ago the last scan to this block occured?)
turtle.clearCache() --#clear all blocks memorized so far.

I initially wrote it for my personnal use so I don't have any plans to further develop it, sorry :(/>
I added a turtle.onEachMove function though.

Actually, I stand corrected.

I added a (very bad) turtle.goto(x,y,z) function and a turtle.turnTo(x,y,z) function.

The turtle.goto() is hard to optimize because turning a turtle takes as much time as going backward/forward, so, you would have to calculate the benefits of turning every X blocks and find a sweet spot.



It doesn't look like easy maths. Every red block is a turn AND a move, so it counts double. Count the time it takes:
The first path is 20 time units, the second is 13 and the third is 11.
So, basically, if you turn at every block except for two you get
T = 2 * sqrt( X² + Y²) - 2
So, you may now think that you have an approximation but you're dead wrong because that, for the first one, would be 15. That's not even close.

The proper way to do it is to say alright, if you turn once you get T = X+Y-1+1, the length, the width, minus where they cross, plus the turn. That's X+Y.
If you turn once every two block that's like doing twice 3 up, 2 right, 3up, 2 right…
And so on
I don't reaaally want to do that sorry :(/>

Also, if you want to make the goto function more "powerful" for your mining turtles, you can make sure your turtle arrives to destination (by destroying everything on its path) by creating another file with that code in it and run both this one and the api:

local old={}

old.forward = turtle.forward
local function forward()
	while not old.forward() do
		turtle.dig()
		turtle.attack()
	end
	return true
end
turtle.forward = forward

old.up = turtle.up
local function up()
	while not old.up() do
		turtle.digUp()
		turtle.attackUp()
	end
	return true
end
turtle.up = up

old.down = turtle.down
local function down()
	while not old.down() do
		turtle.digDown()
		turtle.attackDown()
	end
	return true
end
turtle.down = down

old.place = turtle.place
local function place()
	while not old.place() do
		turtle.dig()
		turtle.attack()
	end
	return true
end
turtle.place = place

old.placeUp = turtle.placeUp
local function placeUp()
	while not old.placeUp() do
		turtle.digUp()
		turtle.attackUp()
	end
	return true
end
turtle.placeUp = placeUp

old.placeDown = turtle.placeDown
local function placeDown()
	while not old.placeDown() do
		turtle.digDown()
		turtle.attackDown()
	end
	return true
end
turtle.placeDown = placeDown