View source for Turtle GPS self-tracker expansion (tutorial)

This tutorial will teach you how to make a [[Turtle]] more efficient in keeping track of its location when using the [[Gps_(API)|GPS API]]. This is essentially an API that uses the native Turtle movement API while using its own movement as a sensor to keep track of its location, so it only requires a GPS signal once, until it is turned off. This API requires every Turtle you want to use the API with to have it installed. I recommend using an [[Advanced_Computer|Advanced Computer]] to write it on, move it to a [[Disk]] with a [[Disk_Drive|disk drive]] and moving it to the Turtle. Alternatively, if you are on Singleplayer or a Multiplayer admin and have access to the mod file, you can move it into the turtle/rom folder to have it automatically installed on every new turtle that is placed.

Important: When starting, the program assumes that it is facing west, so first you must face West and then place the turtle. Here are some ways to check where you are facing:
You can see the sun/moon rising right in front of you. You are facing East.
You can see the sun/moon falling right in front of you. You are facing West.
Clouds go west. Check where they go.
Press F3 and locate the number behind "f". This one is below "x", "y" and "z". If this number is 0, you are facing North. If this number is 1, you are facing West. If this number is 2, you are facing South. If this number is 3, you are facing East.

== Code ==
''Note: This will only work on a Turtle. That said, even if it worked on a [[Computer|computer]], it wouldnt have any practical use because a computer cant move.''<br />
Before you start, you must add this to the program that you want to use it with at the top line:
 os.loadApi("tst")
This will allow the program to use the API. This tutorial assumes that you use the file name "tst" for the API, but if you like to you can change it. You must then also change every reference to "tst" in your program, including the line above.
Write this in the computer/turtle:

 -- Turtle Self-tracking System created by Latias1290.
 
 local xPos, yPos, zPos = nil
 face = 1
 cal = false
 
 function setLocation() -- get gps using other computers
  xPos, yPos, zPos = gps.locate()
  cal = true
 end
 
 function manSetLocation(number x, number y, number z) -- manually set location
  xPos = x
  yPos = y
  zPos = z
  cal = true
 end
 
 function getLocation() -- return the location
  if xPos != nil then
   return xPos, yPos, zPos
  elseif xPos == nil then
   return nil
  end
 end
 
 function turnLeft() -- turn left
  if face == 0 then
   face = 1
  elseif face == 1 then
   face = 2
  elseif face == 2 then
   face = 3
  elseif face == 3 then
   face = 0
  end
 end
 
 function turnRight() -- turn right
  if face == 0 then
   face = 3
  elseif face == 1 then
   face = 0
  elseif face == 2 then
   face = 1
  elseif face == 3 then
   face = 2
  end
 end
 
 function forward() -- go forward
  turtle.forward()
  if cal == true then
   if face == 0 then
    zPos = zPos - 1
   elseif face == 1 then
    xPos = xPos - 1
   elseif face == 2 then
    zPos = zPos + 1
   elseif face == 3 then
    xPos = xPos + 1
   end
  else
   print("Not Calibrated.")
  end
 end
 
 function back() -- go back
  turtle.back()
  if cal == true then
   if face == 0 then
    zPos = zPos + 1
   elseif face == 1 then
    xPos = xPos + 1
   elseif face == 2 then
    zPos = zPos - 1
   elseif face == 2 then
    xPos = xPos - 1
   end
  else
   print("Not Calibrated.")
  end
 end
 
 function up() -- go up
  turtle.up()
  if cal == true then
   yPos = yPos + 1
  else
   print("Not Calibrated.")
  end
 end
 
 function down() -- go down
  turtle.down()
  if cal == true then
   yPos = yPos - 1
  else
   print("Not Calibrated.")
  end
  
  function jump() -- perform a jump. useless? yup!
   turtle.up()
   turtle.down()
  end

== How to Use ==
This might seem daunting at the first moment. But dont worry, I will walk you through it. Note that to use it properly, you must always put "tst." in front of it, or how you named it followed by a dot. So if I wanted to have my turtle go 1 block forward, I typed "tst.forward()". Note that if you do not do either tst.getLocation OR tst.setLocation(coords), the API will print "Not Calibrated." every time you use a command. This will not prevent you from using it, however.

=== setLocation ===
To use this, you will need at least 4 computers equipped with a Wireless Modem, and having it host a GPS. More info about that [[Gps_(API)|here]] and [[Gps_(program)|here]].

=== manSetLocation ===
For this one you will need to know the location of your turtle. Any location will work, but the API loses its point if you use another coordinate set.
A good way to obtain the coordinates is to open up the debug screen(press F3), stand on the turtle, write down the x, y and z fields, substract 1 from the Y coordinate and use these.

=== getLocation ===
This one is pretty simple. It returns the coordinates. Note that you will have to overwrite all of them.
For example, if we had the variables x, y and z, and we wanted to have the value set to our location, we did this:
 x, y, z = tst.getLocation()
Simple right? Note that this will return nil if you are not calibrated, which means if you do it before you do setLocation or manSetLocation, x, y and z will be null!

=== forward, back, up, down, turnLeft and turnRight ===
This one is pretty easy as well. It makes your turtle move 1 block in the direction you used(its obvious which function goes where) and update its location according to where it went.

=== jump ===
This one works a bit different. It makes the turtle go up, then go down. "But thats useless!" you might say, and indeed it is!

[[Category:Unofficial APIs]] [[Category:Tutorials]]