Difference between revisions of "Gps (API)"

From ComputerCraft Wiki
Jump to: navigation, search
(Add return column to table, shift types over into return and method name columns, and reduce description by removing that information)
Line 7: Line 7:
  
 
<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
 
<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
<tr><td colspan="2" style="font-weight: bold; font-size: large; padding-bottom: .3em; border-bottom: solid #C9C9C9 1px; background: #D3FFC2; line-height:28px;">
+
<tr><td colspan="3" style="font-weight: bold; font-size: large; padding-bottom: .3em; border-bottom: solid #C9C9C9 1px; background: #D3FFC2; line-height:28px;">
 
[[File:Grid_disk.png|24px]]&nbsp;&nbsp;
 
[[File:Grid_disk.png|24px]]&nbsp;&nbsp;
 
Gps (API)
 
Gps (API)
 
</td></tr>
 
</td></tr>
  
<tr><td style="width: 350px; background: #E0E0E0; padding: .4em; font-weight:bold;">Method Name</td><td style="background: #E0E0E0; padding: .4em; font-weight:bold;">Description</td></tr>
+
<tr><td style="width: 100px; background: #E0E0E0; padding: .4em; font-weight:bold;">Return</td><td style="width: 350px; background: #E0E0E0; padding: .4em; font-weight:bold;">Method Name</td><td style="background: #E0E0E0; padding: .4em; font-weight:bold;">Description</td></tr>
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">gps.locate(timeout, debug)</td>
+
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">({{Type|int}} x, {{Type|int}} y, {{Type|int}} z), or [[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Tries to retrieve the computer or turtles own location.<br />
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">gps.locate(<nowiki>[</nowiki>{{Type|float}} timeout, <nowiki>[</nowiki>{{Type|boolean}} debug]])</td>
''@param'' '''timeout''' the amount of time, in seconds, to wait for a rednet response<br />
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Tries to retrieve the computer or turtles own location. On success, returns the location of the turtle’s modem. On failure (if no responses are received for <var>timeout</var> seconds, by default 2), returns [[nil]]. If <var>debug</var> is <code>true</code>, debug messages are printed.</table>
''@param'' '''debug''' if true, outputs debug messages<br />
+
''@return'' the location (x, y, z) of the modem attached to the computer or turtle or nil if it could not be determined</td></tr>
+
 
+
</table>
+
  
 
== Example ==
 
== Example ==
Line 42: Line 38:
  
 
[[Category:APIs]]
 
[[Category:APIs]]
 +
code>true

Revision as of 19:37, 23 April 2013

The GPS API provides a method for turtles and computers to retrieve their own locations.

It broadcasts a PING message over rednet and wait for responses. In order for this system to work, there must be at least 4 computers used as gps hosts which will respond and allow trilateration. Three of these hosts should be in a plane, and the fourth should be either above or below the other three. You can set up hosts using the gps program.

Note: When entering in the coordinates for the host you need to put in the x,y,z of the computer, not the modem, as all rednet distances are measured from the block the computer is in.

Grid disk.png   Gps (API)

ReturnMethod NameDescription
(int x, int y, int z), or nil gps.locate([float timeout, [boolean debug]]) Tries to retrieve the computer or turtles own location. On success, returns the location of the turtle’s modem. On failure (if no responses are received for timeout seconds, by default 2), returns nil. If debug is true, debug messages are printed.

Example

 print("Man I am so lost right now!")
 local x, y, z = gps.locate(5)
 if x == nil then
   print("Nope, still lost :(")
 else
   print("I am at ",x," ",y," ",z)
 end

Vector Example

GPS position and navigation can be handled more easily using a vector.

 local home = vector.new(45, 85, 20)
 local position = vector.new(gps.locate(5))
 local displacement = position - home
 
 print("I am ", displacement.tostring(), " away from home!!!")

code>true