53 posts
Posted 27 May 2012 - 02:17 PM
Hi all. Originally, I found Liraal's MagicTurtle API and started improving on it, and then we started working together. Eventually, I suppose he lost interest, but he did give me permission to post this as my own API. I haven't worked on this in a while, so it is still in the beta stage for a few features, like unmapped pathfinding, although it does work for the most part. Anyway, full feature list below in spoilers, but here are some of the highlights:
> The turtle will record data through a mapping system as it travels; it remembers where it's been and what blocks were there.
> The turtle is able to explore portions of land fairly quickly.
> Turtles are now able to pathfind to given coordinates, so long as it has mapped the area for it.
> …if the area has not been mapped, it will do its best to get there.
> Ability to render a map of what's been explored, or a given coordinate.
> Tons of features that really should be in turtles, like place(cobblestone), forward(5), or select(wood).
> Tons of even more cool features that make it so you will never have to worry about turtle functions again!
-main() - runs at start of program as setup.
-load() - loads all saved data.
-save() - saves all data.
-saveSlots() - saves all slot data.
-loadSlots() - loads all slot data.
-updateSlots() - makes changes to slots if changes have occurred.
-version() - returns magicturtle version
-savePos() - saves position data
-getPosF() - loads position data
Setup functions:
-setPos(x,y,z[,face]) - sets the coordinates of the turtle to x,y,z, and optionally direction to face.
-setNorth() - run this if turtle is in fact facing north, and does not yet know its direction.
-setFacing(face) - sets the direction of the turtle to face, a number between 0 and 3. Find this by
hitting F3 and looking under coordinates, f:(number)
-setSlot(slotnumber,block) - sets the specified slot number to the specified block. ex: setSlot
(1,dirt)
Movement functions:
-faceSouth(),faceEast(),faceNorth(),faceWest() - faces the turtle in the direction.
-faceSet(direction) - turns turtle to face the direction, being a number 0-3
-turnLeft([times]) - turns left, and if specified, the number of times.
-turnRight([times]) - turns right, optionally the number of times.
-rotate(times) - rotates counterclockwise to the most efficient angle. Takes a number 0 or higher.
-up([times]) - makes the turtle move up, number of times.
-down([times]) - makes the turtle move down, number of times.
-forward([times]) - makes the turtle move forward, number of times.
-back([times]) - makes the turtle move back, number of times.
-left([times]) - makes the turtle MOVE (not turn) left, number of times.
-right([times]) - makes the turtle move right, number of times.
-goToPos(x,y,z,mode) - a quicker but less effective pathfinding algorithm; it works in open space
only, unless mode is set to true, in which it will break blocks to get to its destination.
-road() - turtle follows a road of redstone torches.
-wander() - wanders slowly about the landscape.
-wanderer(function) - executes the function while wandering about the landscape.
-path(direction) - simple pathfinding function for mazes, does not utilize mapping.
-goDirection(direction,spaces) - turtle goes in direction, for spaces. Direction is a number 0-5.
-pathfind(x,y,z) - using the A* pathfinding algorithm, pathfinds to the given coordinates.
Block manipulation functions:
-tunnel(width,height,length) - digs a tunnel of the specified dimensions.
-staircase(width,height,length) - digs a staircase of the specified dimensions.
-place(block) - places the block from the turtle's inventory, or slotnumber if a number is used.
-placeUp(block), placeDown(block) - same as place, up and down.
-dig([block]) - if block is specified, turtle will dig the specific block. Otherwise, turtle will dig.
-digUp([block]),digDown([block]) - up and down.
-build(blueprint) - builds a design from the specified blueprint, which are created with sketch().
-sketch() - allows the user to create a blueprint, to save and build later.
-patch(slot, length, width) - patches holes in the ground using the block in slot, of length and
width.
-architect(width, height, length) - destroys a building to make a blueprint of it.
-replace(block1,block2) - replaces block1 with block2, if block1 is in front of the turtle.
-replaceUp(b1,b2),replaceDown(b1,b2) - up and down.
Resource-gathering functions:
-jack(slot) - plants, watches and cuts down a single tree (slot is the slot with saplings)
-treefarm(slot) - preforms jack() in a continuous loop.
-mine(mode,length) - if mode is "diamond", creates diamond mine. If mode is "regular", then
creates a tunnel of length*length*length dimensions. If mode is "quarry", creates a quarry.
Inventory functions:
-getSelection() - returns the currently selected slot in turtle's inventory.
-getSlot(slotnumber) - returns the block ID of the slotnumber
-select(slotnumber) - selects the slotnumber in the turtle's inventory.
-isSpace() - returns true if there is space in turtle's inventory, false if not.
-getMatch(blocktype) - searches inventory for blocktype, returns slot number if in inventory or
false if not in inventory.
-drop(block) - drops the block specified, or slot number if a number is used as a parameter.
Position functions:
-getPos() - returns turtle x, y, and z coordinates.
-getFacing() - returns the direction the turtle is facing, 0-3.
Mapping functions:
-checkSides() - returns the front, right, back, left, top and bottom block states (true or false)
-checkSidesType() - returns the block IDs of front,right,back,left,top,bottom. Slower than
checkSides(), but more specific.
-detectLeft() - detects to the left of the turtle.
-detectRight() - detects to the right of the turtle.
-detectBack() - detects behind the turtle.
-detect(side) - takes side as a string, returns the value. ex: detect("left")
-detectDir(face) - takes a number 0-3, returns the value. ex: detectDir(3)
-mapSides() - checks the sides around the turtle, and records block data to mapping. mapSides
is faster than mapSidesType, because it does not need to use compare()
-mapSidesHorizontal(), mapSidesVert() - maps sides horizontally and vertically, faster but covers
less ground.
-mapSidesType() - checks sides around turtle, records block data. More specific block data, but
slower than mapSides. All type functions are slower.
-mapSidesTypeHorizontal(),mapSidesTypeVert() - horizontal and vertical, faster.
-getCoordCount(coord,value) - coord is "x","y", or "z". This function returns the amount of
coordinates on the x/y/z axis with the value. ex: getCoordCount("y",64) returns the number of
coordinates on the Y axis with the value of 64.
-dist(x1,y1,z1,x2,y2,z2) - returns the distance between two points.
-getClosest(x,y,z,radius,type) - returns a table containing the closest block of type within the
radius, with a maximum radius of 20. Usually the table contains one element, but sometimes,
two or more blocks are the same distance apart, hence returning a table.
-explore(radius[,goback[,mode]]) - turtle will explore blocks exposed to air within radius of itself.
If goback is set to true, the turtle will return to the coordinates it was at when it started the
search. If mode is set to true, then a percentage bar will appear, showing the progress of the
search.
-exploreType(radius[,goback[,mode]]) - explores block types exposed to air within the radius.
-exploreSel(x1,y1,z1,x2,y2,z2[,goback[,mode]]) - explores the selection in a cuboid from point1
to point2.
-exploreTypeSel(x1,y1,z1,x2,y2,z2[,gobackp,mode]]) - explores the block types within the
selection, from point1 to point2.
Block data functions:
-getBlock(x,y,z) - returns the block at x, y, and z. use getBlockName(getBlock(x,y,z)) if a name is
required, otherwise returns the block ID.
-setBlock(x,y,z,blocktype) - sets the block at x, y, z to the blocktype. Type can be a block name
or ID.
-getBlockName(id) - returns the name of the block ID. ex: getBlockName(20) >>glass
-getBlockID(name) - returns the ID of the block name ex: getBlockID(glass) >>20
-compare(slot),compareUp(slot),compareDown(slot) - uses turtle.compare() to a slot.
-compareAll(),compareAllUp(),compareAllDown() - compares all slots, returns 9 booleans.
-getSlotMatch(s1,s2,s3,s4,s5,s6,s7,s8,s9) - takes a set of nine boolean states after doing a
compareAll()/compareAllUp()/compareAllDown(), and returns the slot number of the first slot
that matches the compare. ex: getSlotMatch(compareAll()) if sand is in the fifth slot, and
the block in front is sand, then 5 will be returned.
getBlockName(getSlot(getSlotMatch(compareAll()))) would return "sand" in that case.
-getRow(blocktype,x1,y1,z1,x2,y2,z2) - returns how many blocks of blocktype, starting at
x1,y1,z1 as a source block, continue in a row towards x2,y2,z2. No diagonals, just cardinal
directions and up/down.
-getBorderingBlocks(x,y,z) - returns the north,east,south,west,up and down block IDs of x,y,z.
-getBlockTypeDirection(blocktype,block1,block2,b3,b4,b5,b6) - After doing a
getBorderingBlocks(), using this function will return what direction that blocktype is in.
ex: getBlockTypeDirection(air,getBorderingBlocks(5,64,-3)) will return what direction that air is
in from 5,64,-3. Useful for many things, such as pathfinding, exploring, etc.
-getFullRow(x1,y1,z1,x2,y2,z2) - returns a table containing all the blocks within x1,y1,z1,x2,y2,z2
Works in cardinal directions and up/down only.
-graph(x,y,z[,width[,height[,mode]]]) - graphs the surroundings around x,y,z. Optional: Width,
height, and mode: width/height set the size, mode sets 'fancy graphics'; blocks that are air and
have a block below them will be rendered as a '=' sign, but it takes twice as long to render
(although the render time is virtually zero.)
-getBlockInDir(x,y,z,direction) - gets the block ID that is one space in the direction.
-getCoordInDir(x,y,z,direction,spaces) - gets the coordinate that is spaces from x,y,z in direction.
-getCube(x,y,z,radius[,type]) - returns a table listing all the coordinates within a cubic radius of
x,y,z. If type is specified, only the coordinates that match type will be returned.
-getCubeSel(x1,y1,z1,x2,y2,z2[,type]) - returns a table listing all the coordinates in a cuboid
between point1 and point2. Again, if type is specified, only the coordinates matching type will
be returned.
Misc. functions:
-landmine(slot, net) - turtle buries itself in the ground and places TNT that is triggered when
something is placed on top of it. Can be armed/disarmed by rednet if net is set to true. (slot is
the slot containing TNT)
-guardArea(function,width,length) - patrols an area of width and length, and if it runs into an
obstacle/hole, triggers the function.
-mineGrid(slot) - makes a grid of TNT placed 1 block beneath surface
-setMineID(arming, disarming) - sets mine arming/disarming IDs (these are separate and can
differ from each other)
-setUpdateID(id) - sets the ID of remote control terminal
-getSeperated(string) - useful utility function, example use:
position = "56,52,-117"
w = getSeperated(position..",|")
x,y,z = w[1],w[2],w[3]
-blockToText(blockID) - returns " " if id = 0(air), "~" if id = 126(unmapped), "T" if block id is a
turtle id, "#" if block id is 3,12,13, or 18 (dirt,sand,gravel, or leaves), "i" if id = 50(torch), or "@" if
any other id. Used for graphing, or if you'd like to create custom graph functions.
-getDirection(x1,y1,z1,x2,y2,z2) - gets the cardinal or up/down direction from point1 to point2.
-goToCoordsPath(x,y,z) - Used only for pathfinding via waypoints – ONLY works if the
coordinate is one block away, not diagonally. This is useless unless you want to create a
pathfinding algorithm different from pathfind(x,y,z)
Prototypes:
The 'Vertex' prototype is currently outdated, I will update this when I finish 1.4
-Vertex:new() - creates a new Vertex.
-Prototype Vertex - used for pathfinding:
local x,y,z,ID,active = 0,0,0,0,true
getPos() - returns x,y,z
setID(number) - sets ID, required for path saving
getID() - returns ID
addPath(state) - adds a point to the path waypoint system, under the ID of the Vertex
getPath() - returns a table containing the path.
setActive(state) - sets the Vertex to active or inactive, boolean
isActive() - returns true if active, false if inactive
getPosString() - returns the position as a string
deletePath() - clears all path data
Feature list is to be updated in the near future.
Pastebin:
http://pastebin.com/Yt1u8zAu
If there is enough support for this, then I will go on to finish v1.4, and possibly more beyond that. v1.4 will streamline all code, and fix any bugs that may exist. I'm actually about 40% done with that so far. Post any questions, comments, or suggestions about the API in this thread.
Basic usage guide:
2.) Open the Lua interpreter and type "mt.setPos(x,y,z)" where mt can be whatever you saved the API as, and x, y and z are your current positions. Remember to subtract 2 from the Y value, because your turtle is 2 blocks below you!
3.) Face the direction the turtle is facing, and look for the f: value on your f3 screen (probably below the z axis value). Type "mt.setFacing(f)" where f is the f value. Of course, mt being your API name.
4.) So that your turtle can get a basic idea of its surroundings, do "mt.explore(2)". This will build a map of the turtle's surroundings, with a radius of 2.
5.) For each inventory slot that is not empty in your turtle, it would help to do "mt.setSlot(slot#,itemName)" for each. Slot #s are 1-3 for the top, 4-6 for middle, 7-9 for bottom. The itemName can be any conventional item name, like "cobble" or "cobblestone". You will only have to register slots once.
6.) Now you are set for pretty much anything. Your turtle can tell the difference between torches and stone if it has either in its inventory, for example, with exploreType(). You can pathfind to already mapped space fairly quickly, and if you want a 2d map of any layer, use "mt.graph(x,y,z)" where x, y, and z are coordinates. Experiment with the commands, and have fun!
If you would like an example code, here is something that O.S. wrote, as a manual remote control for turtles using a modified graph function:
Smarter turtles for a smarter future!
Enjoy!
> The turtle will record data through a mapping system as it travels; it remembers where it's been and what blocks were there.
> The turtle is able to explore portions of land fairly quickly.
> Turtles are now able to pathfind to given coordinates, so long as it has mapped the area for it.
> …if the area has not been mapped, it will do its best to get there.
> Ability to render a map of what's been explored, or a given coordinate.
> Tons of features that really should be in turtles, like place(cobblestone), forward(5), or select(wood).
> Tons of even more cool features that make it so you will never have to worry about turtle functions again!
Spoiler
Loading functions:Spoiler
-main() - runs at start of program as setup.
-load() - loads all saved data.
-save() - saves all data.
-saveSlots() - saves all slot data.
-loadSlots() - loads all slot data.
-updateSlots() - makes changes to slots if changes have occurred.
-version() - returns magicturtle version
-savePos() - saves position data
-getPosF() - loads position data
Setup functions:
Spoiler
-setPos(x,y,z[,face]) - sets the coordinates of the turtle to x,y,z, and optionally direction to face.
-setNorth() - run this if turtle is in fact facing north, and does not yet know its direction.
-setFacing(face) - sets the direction of the turtle to face, a number between 0 and 3. Find this by
hitting F3 and looking under coordinates, f:(number)
-setSlot(slotnumber,block) - sets the specified slot number to the specified block. ex: setSlot
(1,dirt)
Movement functions:
Spoiler
-faceSouth(),faceEast(),faceNorth(),faceWest() - faces the turtle in the direction.
-faceSet(direction) - turns turtle to face the direction, being a number 0-3
-turnLeft([times]) - turns left, and if specified, the number of times.
-turnRight([times]) - turns right, optionally the number of times.
-rotate(times) - rotates counterclockwise to the most efficient angle. Takes a number 0 or higher.
-up([times]) - makes the turtle move up, number of times.
-down([times]) - makes the turtle move down, number of times.
-forward([times]) - makes the turtle move forward, number of times.
-back([times]) - makes the turtle move back, number of times.
-left([times]) - makes the turtle MOVE (not turn) left, number of times.
-right([times]) - makes the turtle move right, number of times.
-goToPos(x,y,z,mode) - a quicker but less effective pathfinding algorithm; it works in open space
only, unless mode is set to true, in which it will break blocks to get to its destination.
-road() - turtle follows a road of redstone torches.
-wander() - wanders slowly about the landscape.
-wanderer(function) - executes the function while wandering about the landscape.
-path(direction) - simple pathfinding function for mazes, does not utilize mapping.
-goDirection(direction,spaces) - turtle goes in direction, for spaces. Direction is a number 0-5.
-pathfind(x,y,z) - using the A* pathfinding algorithm, pathfinds to the given coordinates.
Block manipulation functions:
Spoiler
-tunnel(width,height,length) - digs a tunnel of the specified dimensions.
-staircase(width,height,length) - digs a staircase of the specified dimensions.
-place(block) - places the block from the turtle's inventory, or slotnumber if a number is used.
-placeUp(block), placeDown(block) - same as place, up and down.
-dig([block]) - if block is specified, turtle will dig the specific block. Otherwise, turtle will dig.
-digUp([block]),digDown([block]) - up and down.
-build(blueprint) - builds a design from the specified blueprint, which are created with sketch().
-sketch() - allows the user to create a blueprint, to save and build later.
-patch(slot, length, width) - patches holes in the ground using the block in slot, of length and
width.
-architect(width, height, length) - destroys a building to make a blueprint of it.
-replace(block1,block2) - replaces block1 with block2, if block1 is in front of the turtle.
-replaceUp(b1,b2),replaceDown(b1,b2) - up and down.
Resource-gathering functions:
Spoiler
-jack(slot) - plants, watches and cuts down a single tree (slot is the slot with saplings)
-treefarm(slot) - preforms jack() in a continuous loop.
-mine(mode,length) - if mode is "diamond", creates diamond mine. If mode is "regular", then
creates a tunnel of length*length*length dimensions. If mode is "quarry", creates a quarry.
Inventory functions:
Spoiler
-getSelection() - returns the currently selected slot in turtle's inventory.
-getSlot(slotnumber) - returns the block ID of the slotnumber
-select(slotnumber) - selects the slotnumber in the turtle's inventory.
-isSpace() - returns true if there is space in turtle's inventory, false if not.
-getMatch(blocktype) - searches inventory for blocktype, returns slot number if in inventory or
false if not in inventory.
-drop(block) - drops the block specified, or slot number if a number is used as a parameter.
Position functions:
Spoiler
-getPos() - returns turtle x, y, and z coordinates.
-getFacing() - returns the direction the turtle is facing, 0-3.
Mapping functions:
Spoiler
-checkSides() - returns the front, right, back, left, top and bottom block states (true or false)
-checkSidesType() - returns the block IDs of front,right,back,left,top,bottom. Slower than
checkSides(), but more specific.
-detectLeft() - detects to the left of the turtle.
-detectRight() - detects to the right of the turtle.
-detectBack() - detects behind the turtle.
-detect(side) - takes side as a string, returns the value. ex: detect("left")
-detectDir(face) - takes a number 0-3, returns the value. ex: detectDir(3)
-mapSides() - checks the sides around the turtle, and records block data to mapping. mapSides
is faster than mapSidesType, because it does not need to use compare()
-mapSidesHorizontal(), mapSidesVert() - maps sides horizontally and vertically, faster but covers
less ground.
-mapSidesType() - checks sides around turtle, records block data. More specific block data, but
slower than mapSides. All type functions are slower.
-mapSidesTypeHorizontal(),mapSidesTypeVert() - horizontal and vertical, faster.
-getCoordCount(coord,value) - coord is "x","y", or "z". This function returns the amount of
coordinates on the x/y/z axis with the value. ex: getCoordCount("y",64) returns the number of
coordinates on the Y axis with the value of 64.
-dist(x1,y1,z1,x2,y2,z2) - returns the distance between two points.
-getClosest(x,y,z,radius,type) - returns a table containing the closest block of type within the
radius, with a maximum radius of 20. Usually the table contains one element, but sometimes,
two or more blocks are the same distance apart, hence returning a table.
-explore(radius[,goback[,mode]]) - turtle will explore blocks exposed to air within radius of itself.
If goback is set to true, the turtle will return to the coordinates it was at when it started the
search. If mode is set to true, then a percentage bar will appear, showing the progress of the
search.
-exploreType(radius[,goback[,mode]]) - explores block types exposed to air within the radius.
-exploreSel(x1,y1,z1,x2,y2,z2[,goback[,mode]]) - explores the selection in a cuboid from point1
to point2.
-exploreTypeSel(x1,y1,z1,x2,y2,z2[,gobackp,mode]]) - explores the block types within the
selection, from point1 to point2.
Block data functions:
Spoiler
-getBlock(x,y,z) - returns the block at x, y, and z. use getBlockName(getBlock(x,y,z)) if a name is
required, otherwise returns the block ID.
-setBlock(x,y,z,blocktype) - sets the block at x, y, z to the blocktype. Type can be a block name
or ID.
-getBlockName(id) - returns the name of the block ID. ex: getBlockName(20) >>glass
-getBlockID(name) - returns the ID of the block name ex: getBlockID(glass) >>20
-compare(slot),compareUp(slot),compareDown(slot) - uses turtle.compare() to a slot.
-compareAll(),compareAllUp(),compareAllDown() - compares all slots, returns 9 booleans.
-getSlotMatch(s1,s2,s3,s4,s5,s6,s7,s8,s9) - takes a set of nine boolean states after doing a
compareAll()/compareAllUp()/compareAllDown(), and returns the slot number of the first slot
that matches the compare. ex: getSlotMatch(compareAll()) if sand is in the fifth slot, and
the block in front is sand, then 5 will be returned.
getBlockName(getSlot(getSlotMatch(compareAll()))) would return "sand" in that case.
-getRow(blocktype,x1,y1,z1,x2,y2,z2) - returns how many blocks of blocktype, starting at
x1,y1,z1 as a source block, continue in a row towards x2,y2,z2. No diagonals, just cardinal
directions and up/down.
-getBorderingBlocks(x,y,z) - returns the north,east,south,west,up and down block IDs of x,y,z.
-getBlockTypeDirection(blocktype,block1,block2,b3,b4,b5,b6) - After doing a
getBorderingBlocks(), using this function will return what direction that blocktype is in.
ex: getBlockTypeDirection(air,getBorderingBlocks(5,64,-3)) will return what direction that air is
in from 5,64,-3. Useful for many things, such as pathfinding, exploring, etc.
-getFullRow(x1,y1,z1,x2,y2,z2) - returns a table containing all the blocks within x1,y1,z1,x2,y2,z2
Works in cardinal directions and up/down only.
-graph(x,y,z[,width[,height[,mode]]]) - graphs the surroundings around x,y,z. Optional: Width,
height, and mode: width/height set the size, mode sets 'fancy graphics'; blocks that are air and
have a block below them will be rendered as a '=' sign, but it takes twice as long to render
(although the render time is virtually zero.)
-getBlockInDir(x,y,z,direction) - gets the block ID that is one space in the direction.
-getCoordInDir(x,y,z,direction,spaces) - gets the coordinate that is spaces from x,y,z in direction.
-getCube(x,y,z,radius[,type]) - returns a table listing all the coordinates within a cubic radius of
x,y,z. If type is specified, only the coordinates that match type will be returned.
-getCubeSel(x1,y1,z1,x2,y2,z2[,type]) - returns a table listing all the coordinates in a cuboid
between point1 and point2. Again, if type is specified, only the coordinates matching type will
be returned.
Misc. functions:
Spoiler
-landmine(slot, net) - turtle buries itself in the ground and places TNT that is triggered when
something is placed on top of it. Can be armed/disarmed by rednet if net is set to true. (slot is
the slot containing TNT)
-guardArea(function,width,length) - patrols an area of width and length, and if it runs into an
obstacle/hole, triggers the function.
-mineGrid(slot) - makes a grid of TNT placed 1 block beneath surface
-setMineID(arming, disarming) - sets mine arming/disarming IDs (these are separate and can
differ from each other)
-setUpdateID(id) - sets the ID of remote control terminal
-getSeperated(string) - useful utility function, example use:
position = "56,52,-117"
w = getSeperated(position..",|")
x,y,z = w[1],w[2],w[3]
-blockToText(blockID) - returns " " if id = 0(air), "~" if id = 126(unmapped), "T" if block id is a
turtle id, "#" if block id is 3,12,13, or 18 (dirt,sand,gravel, or leaves), "i" if id = 50(torch), or "@" if
any other id. Used for graphing, or if you'd like to create custom graph functions.
-getDirection(x1,y1,z1,x2,y2,z2) - gets the cardinal or up/down direction from point1 to point2.
-goToCoordsPath(x,y,z) - Used only for pathfinding via waypoints – ONLY works if the
coordinate is one block away, not diagonally. This is useless unless you want to create a
pathfinding algorithm different from pathfind(x,y,z)
Prototypes:
Spoiler
The 'Vertex' prototype is currently outdated, I will update this when I finish 1.4
-Vertex:new() - creates a new Vertex.
-Prototype Vertex - used for pathfinding:
Spoiler
local x,y,z,ID,active = 0,0,0,0,true
getPos() - returns x,y,z
setID(number) - sets ID, required for path saving
getID() - returns ID
addPath(state) - adds a point to the path waypoint system, under the ID of the Vertex
getPath() - returns a table containing the path.
setActive(state) - sets the Vertex to active or inactive, boolean
isActive() - returns true if active, false if inactive
getPosString() - returns the position as a string
deletePath() - clears all path data
Feature list is to be updated in the near future.
Pastebin:
http://pastebin.com/Yt1u8zAu
If there is enough support for this, then I will go on to finish v1.4, and possibly more beyond that. v1.4 will streamline all code, and fix any bugs that may exist. I'm actually about 40% done with that so far. Post any questions, comments, or suggestions about the API in this thread.
Basic usage guide:
Spoiler
1.) First, when you have installed the API, stand on top of your turtle and press f3.2.) Open the Lua interpreter and type "mt.setPos(x,y,z)" where mt can be whatever you saved the API as, and x, y and z are your current positions. Remember to subtract 2 from the Y value, because your turtle is 2 blocks below you!
3.) Face the direction the turtle is facing, and look for the f: value on your f3 screen (probably below the z axis value). Type "mt.setFacing(f)" where f is the f value. Of course, mt being your API name.
4.) So that your turtle can get a basic idea of its surroundings, do "mt.explore(2)". This will build a map of the turtle's surroundings, with a radius of 2.
5.) For each inventory slot that is not empty in your turtle, it would help to do "mt.setSlot(slot#,itemName)" for each. Slot #s are 1-3 for the top, 4-6 for middle, 7-9 for bottom. The itemName can be any conventional item name, like "cobble" or "cobblestone". You will only have to register slots once.
6.) Now you are set for pretty much anything. Your turtle can tell the difference between torches and stone if it has either in its inventory, for example, with exploreType(). You can pathfind to already mapped space fairly quickly, and if you want a 2d map of any layer, use "mt.graph(x,y,z)" where x, y, and z are coordinates. Experiment with the commands, and have fun!
If you would like an example code, here is something that O.S. wrote, as a manual remote control for turtles using a modified graph function:
Spoiler
-- mCtrl - Manual Turtle Control
--
-- Instructions:
-- * Install MagicTurtle API (must be named 'mt')
-- * Set up Position and Facing
-- * Run mCtrl
-- * Use controls below to explore
--
-- Keys:
-- W,A,S,D = Movement (North, West, South, East)
-- R,F = Up, Down (Vertically)
-- E = Break front block
-- X = Maps blocks around Turtle
-- C = Refuel (if fuel is needed)
-- 1,2,3,4 = Place block from that slot number
-- Q = Quit
os.loadAPI("mt")
local run = true
function update()
local x,y,z = mt.getPos()
local d = mt.getFacing()
-- Draws the map first
graph(x,y,z)
-- Draws Coord at the top
term.setCursorPos(1,1)
term.write("("..x..","..y..","..z..")")
-- Draws Turtle at the center (with direction)
term.setCursorPos(20,6)
if(d == 0) then
term.write("v")
elseif(d == 1) then
term.write("<")
elseif(d == 2) then
term.write("^")
elseif(d == 3) then
term.write(">")
end
-- Draws Fuel (if fuel is needed)
if(turtle.getFuelLevel() ~= "unlimited") then
term.setCursorPos(1,13)
term.write("Fuel: "..turtle.getFuelLevel())
end
end
-- Copied and modified from MagicTurtle's code
-- Redone to remove term.clear(), makes the program look smoother. :-)
function graph(xs,ys,zs)
local curX,curZ = 1,1
local width,height = term.getSize()
width = width + 1
local xw,zw = math.floor(width/2),math.floor(height/2)
local fullRow = 0
local fullRowY = 0
local tmp = {}
local temp = {}
local tempp = 0
term.setCursorPos(1,1)
for i=1,height-1,1 do
fullRow = mt.getFullRow(xs-xw+curX,ys,zs-zw+curZ,xs+xw,ys,zs+zw)
for i=1,width-1,1 do
tmp = mt.getSeperated(fullRow)
tempp = mt.blockToText(tmp[i])
if mode then temp = mt.getSeperated(fullRowY)
if tempp == " " and mt.blockToText(temp[i]) ~= " " and mt.blockToText(temp[i]) ~= "~" then tempp = "=" end end
term.write(tempp)
end
if curZ <= height then
curZ = curZ + 1
term.setCursorPos(1,curZ)
else break end
end
end
update() -- Draw inital map
while run do
local event, p1, p2, p3, p4, p5 = os.pullEvent()-- Listen for key events
if(event == "char") then
if(p1 == "q") then -- Quits out of the program and cleans the screen
run = false
term.clear()
term.setCursorPos(1,1)
elseif(p1 == "w") then -- Move North
mt.faceNorth()
mt.forward()
update()
elseif(p1 == "a") then -- Move West
mt.faceWest()
mt.forward()
update()
elseif(p1 == "s") then -- Move South
mt.faceSouth()
mt.forward()
update()
elseif(p1 == "d") then -- Move East
mt.faceEast()
mt.forward()
update()
elseif(p1 == "r") then -- Move Up
mt.up()
update()
elseif(p1 == "f") then -- Move Down
mt.down()
update()
elseif(p1 == "e") then -- Break block
mt.dig()
update()
elseif(p1 == "x") then -- Map all sides (Does not compare types)
mt.mapSides()
update()
elseif(p1 == "c" and turtle.getFuelLevel() ~= "unlimited") then -- Refuel (if needed)
for slot = 1, 16 do
local cnt = turtle.getItemCount(slot)
if(cnt > 0) then
turtle.select(slot)
if turtle.refuel(1) then
update()
break
end
end
end
elseif(p1 == "1" or p1 == "2" or p1 == "3" or p1 == "4") then -- Place block
mt.place(tonumber(p1))
update()
end
end
end
Smarter turtles for a smarter future!
Enjoy!
