What you can ask.
Press Ctrl K on the deck and say what you want in your own words. The AI answers questions (it looks things up first: your storage, the fleet, the whole map) or makes a plan: one step or many, in order or side by side, with only the turtles you mean. You read the plan, what it breaks and places, and see it on the map; nothing runs until you press Run, and one Stop ends all of it.
Everything below is what the AI knows TurtleDeck can do, in the same words it reads. Say things like “one at a time”, “do not break blocks”, “except the crafty turtles”, “stay out of the village”, “never break farmland” or “return home once finished”, and every step keeps to it. Pick the model in the command bar; the bigger ones cost more credits.
Moving turtles.
Send turtles somewhere, home, or turn them.
Send a turtle somewhere
goMove one turtle to a spot. It plans a route over everything the fleet has seen and goes round what is in the way; it breaks blocks only when digging is allowed and there is no clear way.
Parameters (3)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| to* | point | Where to go. |
| knownOnly | booldefault false | Only through corridors known to be open (never digs). |
Verified:Send Miner 4 to the supply chestSend them over thereRefuel only the turtles under 30% fuel, then send Scout to the selected blockSend Miner 2 to the selected block and make that its home
Gather turtles at a spot
gatherSeveral turtles go to the free cells around one spot (turtles cannot share a cell), nearest first.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
| at* | point | Where to gather. |
Verified:Send Miner 1 and Miner 2 to the fuel chest, wait 30 seconds, and bring them homeBring every idle turtle to the selected block
Send turtles home
homeTurtles travel to their home spot and face the home direction. Busy turtles are left alone (stop their job to send them home now).
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
Verified:Wait 5 minutes, then send everyone homeSend Miner 1 and Miner 2 to the fuel chest, wait 30 seconds, and bring them homeQuarry the selection 4 deep; even if that fails, send everyone home afterwardsTurtles that carry coal burn it, then everyone goes home
Turn turtles to face a direction
faceTurns in place to face north, east, south or west.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
| facing* | facing | The direction. |
Verified:Turn Miner 2 to face northMake all turtles face east
Move a few blocks
moveMoves one turtle a number of blocks forward, back, up or down, stopping at the first block it may not pass. With digging allowed it digs its way (never chests, machines or computers).
Parameters (3)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| direction | enum (forward, back, up, down)default "forward" | Which way. |
| blocks | int 1-64default 1 | How far. |
Verified:Move Scout forward 5 blocksTake the selected turtle up 10
Turn left or right
turnTurns one turtle a quarter turn left or right, up to three times.
Parameters (3)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| side | sidedefault "right" | Which way to turn. |
| times | int 1-3default 1 | Quarter turns. |
Verified:Turn Scout around
Dig straight to a spot
dig_toDigs a straight path to a spot: up or down first, then along x, then along z. Chests, machines, computers and protected blocks stop it.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| to* | point | Where to dig to. |
Fuel.
Refuelling at the shared fuel chest, burning what they carry, fuel rescues.
Refuel at the fuel chest
refuelTurtles under the target go to the shared fuel chest, take what they need in as few pulls as they can, burn it and put the rest back. They take turns at the chest (one at a time by default) and wait in line a few blocks away, never digging near it.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
| minPercent | int 1-100default 50 | Fill up to this share of the tank; turtles already above it stay put. |
Verified:Refuel all turtles to 50%. Do not include crafty turtles.Refuel all turtles one at a time to 50%. Do not include crafty turtles. Do not break blocks. Return home once finished.Top up Miner 1 to 80% and bring it back hereRefuel every turtle under 20% to half a tank
Burn fuel they carry
burn_fuelBurns coal, charcoal and other fuel items already in the inventory up to a target, one refuel call per stack. No trip anywhere.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
| minPercent | int 1-100default 100 | Burn up to this share of the tank. |
Verified:Have every turtle burn the coal it carriesRefuel Miner 2 from its own inventory to 30%Turtles that carry coal burn it, then everyone goes home
Send fuel to a stranded turtle
send_fuelA fuel rescue: the best-placed turtle fetches fuel from the fuel chest, flies next to the stranded one without digging and hands it over; the stranded turtle then fills up at the chest and goes home.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | The turtle that is out of fuel. |
Cancel a fuel rescue
cancel_rescueCancels the running fuel rescue for a turtle; the helper goes home.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | The stranded turtle the rescue is for. |
Verified:Cancel the fuel rescue for Miner 1
Automatic fuel rescue on or off
auto_rescueTurns the automatic fuel rescue setting on or off (Settings, Fleet). When on, a turtle that runs out gets fuel without being asked.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| enabled* | bool | On or off. |
Verified:Turn off automatic fuel rescue
Inventory.
Unloading, junk, ender chests, equipment and slots.
Unload at the unload chest
unloadTurtles take turns at the shared unload chest and empty their inventory into it (the storage station drains it), keeping one stack of fuel if asked.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
| keepFuel | booldefault true | Keep one stack of fuel. |
Verified:Once the miners are idle, unload them allQuarry the selected area 5 deep, then have everyone unloadUnload everyone one at a time, then refuel them to 60%, then homeEveryone unload at the deposit chest
Drop junk
drop_junkDrops cobblestone, dirt, gravel, stone, deepslate, netherrack, tuff, granite, diorite, andesite and flint below each turtle.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
Unload through an ender chest
unload_enderEmpties the inventory through a carried ender chest whose other end is the deposit chest. The chest is placed above (or in front) and picked up again.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| keepFuel | booldefault true | Keep one stack of fuel. |
Set the ender chest item
set_ender_chestSets which item a turtle uses as its carried ender chest (sc-goodies:ender_storage by default).
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| item* | item | The ender chest's item id. |
Verified:Miner 2 uses enderstorage:ender_chest as its ender chest
Equip a tool or modem
equipEquips an item from the turtle's inventory on the left or right side (a pickaxe, modem, crafting table...). What was there goes into the inventory.
Parameters (3)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| item* | item | The item to equip (must be in the inventory). |
| side | sidedefault "left" | Which side. |
Select a slot
select_slotSelects an inventory slot (what place, drop and refuel use).
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| slot* | slot | 1 to 16. |
Verified:Select slot 3 on Miner 1
Move items between slots
move_itemsMoves items from one slot to another in the same turtle.
Parameters (4)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| from* | slot | From slot. |
| to* | slot | To slot. |
| count | int 1-64default 64 | How many. |
Verified:Move Miner 1's slot 1 into slot 5
Stack items together
stack_itemsMerges partial stacks of the same item so the inventory has as many free slots as possible.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
Verified:Tidy up every turtle's inventory
Drop or put items somewhere
drop_itemsDrops items forward, up or down: into a chest or turtle if there is one, else on the ground. Leave item out to drop the selected slot.
Parameters (4)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| item | item | Which item (all stacks of it); none: the selected slot. |
| count | int 1-1024 | How many (default: all). |
| direction | directiondefault "forward" | forward, up or down. |
Verified:Miner 1, put all your raw iron in the chest in front
Take items from a chest or the ground
pick_upTakes items from the chest in front, above or below, or picks up items lying there.
Parameters (3)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| direction | directiondefault "forward" | forward, up or down. |
| count | int 1-64default 64 | How many (one stack at most). |
Shared chests.
The fuel, unload and supply chests every turtle uses.
Mining and digging.
Quarries, holes, strip mines, ore mining, tunnels, stairs, clearing.
Quarry an area
quarryDigs the whole area out from the surface down, split into slices across the crew. Follows ore veins, unloads when full, keeps fuel to get back.
Parameters (5)
| Name | Type | What it does |
|---|---|---|
| area* | area | The area to dig. |
| depth* | int 1-64 | How many blocks down. |
| crew | int 1-16 | How many idle turtles help (default: the idle ones nearby, at most 8). |
| veins | booldefault true | Also mine ore next to the dug blocks. |
| dropJunk | booldefault false | Drop cobblestone, dirt and gravel instead of carrying it home. |
Verified:Quarry the selection 4 deep and say 'mining done' when they finishQuarry the selected area 5 deep, then have everyone unloadQuarry the selection 4 deep; even if that fails, send everyone home afterwardsQuarry the selected area 6 deep
Dig a box from a spot
holeDigs a box starting at a spot: length ahead, width to the right, depth down.
Parameters (7)
| Name | Type | What it does |
|---|---|---|
| from* | point | The near-left top corner. |
| facing | facingdefault "north" | Which way the job runs. |
| length | int 1-32default 5 | Blocks ahead. |
| width | int 1-32default 5 | Blocks to the right. |
| depth | int 1-64default 5 | Blocks down. |
| veins | booldefault true | Also mine ore next to the dug blocks. |
| dropJunk | booldefault false | Drop cobblestone, dirt and gravel instead of carrying it home. |
Verified:Dig a holeDig a 5x5 hole 8 deep at the selected block
Strip mine
stripParallel strip mines with side branches across an area, one turtle per mine, heading one way. With depth, the mines run that many blocks below the area's ground.
Parameters (6)
| Name | Type | What it does |
|---|---|---|
| area* | area | The area to cover. |
| facing | facingdefault "north" | Which way the job runs. |
| depth | int 0-120 | Blocks below the ground (none: at the turtles' level). |
| crew | int 1-16 | How many idle turtles help (default: the idle ones nearby, at most 8). |
| veins | booldefault true | Also mine ore next to the dug blocks. |
| dropJunk | booldefault true | Drop cobblestone, dirt and gravel instead of carrying it home. |
Verified:Strip mine the selected area heading northStrip mine 40 below the surface across the selection with 3 turtles
Mine for an ore
mine_oreGoes down (or up) to the best level for an ore and strip mines there; several turtles share one entrance shaft. Levels: coal 96, copper 48, iron 16, gold -16, lapis 0, redstone -59, diamond -59, emerald 236, ancient debris 15, quartz 15.
Parameters (6)
| Name | Type | What it does |
|---|---|---|
| ore* | enum (coal, copper, iron, gold, lapis, redstone, diamond, emerald, ancient_debris, quartz) | Which ore. |
| area* | area | Where to dig the entrance and the mines. |
| facing | facingdefault "north" | Which way the job runs. |
| length | int 8-256default 48 | How long each mine runs. |
| crew | int 1-16 | How many idle turtles help (default: the idle ones nearby, at most 8). |
| dropJunk | booldefault true | Drop cobblestone, dirt and gravel instead of carrying it home. |
Verified:MineMine for iron under the selection, and when storage has 400 iron ingots craft 16 iron pickaxesMine for diamonds under the selected area with 4 turtlesSend two turtles to mine iron heading east under the selection
Dig a tunnel
tunnelA corridor straight ahead from a spot, one lane per block of width, 1 to 3 high, with torches and lava/water plugged if asked.
Parameters (7)
| Name | Type | What it does |
|---|---|---|
| from* | point | Where it starts (the block before the first dug one). |
| facing | facingdefault "north" | Which way the job runs. |
| length | int 1-256default 32 | How long. |
| width | int 1-8default 1 | How wide. |
| height | int 1-3default 2 | How high. |
| torches | int 0-64default 0 | Place a torch every N blocks (0: none). |
| veins | booldefault true | Also mine ore next to the dug blocks. |
Verified:Dig a 2x2 tunnel 30 long west from the selected block, then stairs 10 down facing west from 375 69 -160Dig a 2x2 tunnel 50 long heading west from the selected blockTunnel 100 blocks north from 400 40 -150 with torches every 8
Dig a staircase
stairsA walkable staircase down (or up) with headroom, one step per block.
Parameters (7)
| Name | Type | What it does |
|---|---|---|
| from* | point | Where it starts. |
| facing | facingdefault "north" | Which way the job runs. |
| steps | int 1-128default 16 | How many steps. |
| width | int 1-4default 1 | How wide. |
| direction | enum (down, up)default "down" | down or up. |
| headroom | int 2-3default 3 | Blocks of headroom. |
| torches | int 0-64default 0 | Place a torch every N blocks (0: none). |
Verified:Dig a 2x2 tunnel 30 long west from the selected block, then stairs 10 down facing west from 375 69 -160Dig stairs down 30 steps from the selected block heading southMake a staircase 20 steps up facing east from 405 60 -160
Clear everything above the ground
clear_aboveRemoves trees, leaves and anything else above the ground line in an area, up to a height.
Parameters (4)
| Name | Type | What it does |
|---|---|---|
| area* | area | The area to clear. |
| height | int 1-64default 6 | How high above the ground. |
| crew | int 1-16 | How many idle turtles help (default: the idle ones nearby, at most 8). |
| dropJunk | booldefault true | Drop cobblestone, dirt and gravel instead of carrying it home. |
Verified:Clear the trees in the selected areaFlatten everything above the ground in the selection, 10 high
Break one block
digBreaks the block in front of, above or below one turtle (never chests, machines or computers).
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| direction | directiondefault "forward" | forward, up or down. |
Verified:Miner 2, break the block above you
Attack
attackSwings at whatever mob is in front of, above or below the turtle.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| direction | directiondefault "forward" | forward, up or down. |
Verified:Scout, attack whatever is in front
Clear falling gravel or sand
clear_fallingDigs on one side until nothing falls back in.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| direction | directiondefault "forward" | forward, up or down. |
Verified:Miner 3, clear the gravel above it
Forget mining progress
forget_progressForgets how far earlier mines and holes got, so the next job from the same spot starts from the beginning.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
Verified:Forget where the mines stopped
Mapping.
Surveys, scans and teaching the route planner.
Survey an area
surveyTurtles fly over an area just above the ground and record every block they see. Never digs, places or attacks.
Parameters (3)
| Name | Type | What it does |
|---|---|---|
| area* | area | The area to map. |
| passes | int 1-3default 2 | 1 to 3 passes (more passes see walls face on). |
| crew | int 1-16 | How many idle turtles help (default: the idle ones nearby, at most 8). |
Verified:Refuel everyone to 50%, then survey the selected areaSurvey the selected area and at the same time deliver 64 torches, then say doneSurvey the selection now, and again in 10 minutesSurvey a 100x100 area centred on 400 70 -150
Look around
scanTurns once around and looks up and down, recording the blocks next to each turtle on the map.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
Verified:Have every turtle look around
Scan with a geo scanner
geoscanUses an Advanced Peripherals geo scanner attached to the turtle to record every block within a radius.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| radius | int 1-16default 8 | Blocks around (at most 16). |
Verified:Geo scan 16 blocks around Scout
Teach the route planner a corridor
teach_routeTells a turtle that an area (from its ground level up the given height) is open, so routes may use it (corridors somebody else dug).
Parameters (3)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| area* | area | The open space. |
| height | int 1-16default 2 | How high the space is. |
Verified:Teach Miner 2 that the selected area is an open tunnel 3 high
Forget what a turtle has seen
forget_turtle_mapClears a turtle's own memory of blocks (its local route planner); the website's map is kept.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
Verified:Miner 4, forget what you have seen
Building.
Blueprints, the storage tower and barrel upgrades.
Build a blueprint
buildBuilds a blueprint layer by layer from the bottom up; each layer is shared across the crew and must finish before the next. Missing materials are fetched from the supply chest.
Parameters (5)
| Name | Type | What it does |
|---|---|---|
| blueprint* | blueprint | A blueprint saved in Blueprints, or "tower". |
| at* | point | Where its near-left corner goes (on the ground). |
| facing | facingdefault "north" | Which way the job runs. |
| crew | int 1-16 | How many idle turtles help (default: the idle ones nearby, at most 8). |
| pause | booldefault false | Wait after each layer until you continue (or the storage sees the new inventories). |
Verified:Build my house blueprint at the selected block facing eastBuild the watchtower at the selected block with 2 turtles, pausing after each layerBuild something at the selected block
Build the storage tower
build_towerBuilds the barrel storage tower (barrels, modems and cable, with a walkway) sized to an area, layer by layer.
Parameters (5)
| Name | Type | What it does |
|---|---|---|
| area* | area | The tower's footprint. |
| layers | int 1-32default 2 | How many barrel layers. |
| crew | int 1-16 | How many idle turtles help (default: the idle ones nearby, at most 8). |
| walkway | booldefault true | Leave a walkway. |
| pause | booldefault true | Wait after each layer for the storage to see it. |
Continue a paused build
continue_buildLets a build that waits after a layer carry on with the next one.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| job | jobdefault "latest" | Which build (default: the latest). |
Upgrade barrels
upgrade_barrelsWalks a layer of barrels one block above them and replaces every barrel of one kind with another (empties each through a carried ender chest first).
Parameters (4)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| area* | area | The barrel layer. |
| from | itemdefault "sc-goodies:iron_barrel" | Barrels to replace. |
| to | itemdefault "sc-goodies:diamond_barrel" | Replacement. |
Verified:Upgrade the iron barrels in the selected area to diamond barrels with Miner 2
Place a block
place_blockPlaces a block from the inventory in front of, above or below one turtle.
Parameters (3)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| item | item | Which block (none: the selected slot). |
| direction | directiondefault "forward" | forward, up or down. |
Verified:Miner 1, place a torch below you
Storage and crafting.
Deliveries, crafting, smelting, recipes and storage stations.
Deliver items from storage
deliverTakes items from the storage and delivers them to the output chest, to you (a manipulator) or to a turtle through the supply chest. What is missing is made from other forms (blocks, raw ore, nuggets) or crafted and smelted when a recipe allows.
Parameters (4)
| Name | Type | What it does |
|---|---|---|
| item* | item | The item id. |
| count* | int 1-10000 | How many. |
| to | enum (output, turtle, player)default "output" | Where to. |
| turtle | turtle | The turtle (to: turtle). |
Verified:Survey the selected area and at the same time deliver 64 torches, then say doneDeliver 64 torches to the output chestGive Miner 2 32 coalSend me 17 iron ingots
Craft items
craftMakes items with the storage's crafty turtles and furnaces: takes what is stored, crafts and smelts what is missing, then delivers.
Parameters (4)
| Name | Type | What it does |
|---|---|---|
| item* | item | What to make. |
| count* | int 1-4096 | How many. |
| to | enum (output, turtle, player, storage)default "output" | Where the result goes (storage: keep it stored). |
| turtle | turtle | The turtle (to: turtle). |
Verified:When storage has 300 iron ingots, craft 10 hoppersMine for iron under the selection, and when storage has 400 iron ingots craft 16 iron pickaxesCraft 16 chestsMake 4 iron pickaxes and send them to me
Smelt items
smeltSmelts raw items in the storage's furnaces (fuel taken from storage) and keeps or delivers the result. Name the result: minecraft:iron_ingot smelts raw iron.
Parameters (3)
| Name | Type | What it does |
|---|---|---|
| item* | item | The smelted result. |
| count* | int 1-4096 | How many. |
| to | enum (output, player, storage)default "storage" | Where it goes. |
Verified:Smelt 32 iron ingots and keep them in storageSmelt 64 glass and send it to me
Re-index the storage
reindex_storageHas the storage station read every chest again (after chests were added or changed by hand).
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| station | int | Which station (default: the online one). |
Verified:Re-index the storage
Update the storage station
update_stationThe storage station downloads the latest station program and restarts.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| station | int | Which station (default: the online one). |
Verified:Update the storage station
Set the station's chests
setup_stationTells the storage station which peripherals are the deposit chest, the output chest and the supply chest (peripheral names like minecraft:chest_3).
Parameters (4)
| Name | Type | What it does |
|---|---|---|
| station | int | Which station. |
| deposit* | string | Deposit chest peripheral. |
| output* | string | Output chest peripheral. |
| supply | string | Supply chest peripheral. |
Verified:Use minecraft:chest_2 as the deposit chest and minecraft:chest_5 as the output chest
Learn a recipe from a crafty turtle
learn_recipeReads the crafting grid a player laid out in a crafty turtle, crafts it once and saves the recipe.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | The crafty turtle with the grid laid out. |
Verified:Learn the recipe in Crafty's grid
Save a recipe
save_recipeSaves a crafting recipe (a 3x3 grid) or a smelting recipe (one input) so crafting and deliveries can use it.
Parameters (5)
| Name | Type | What it does |
|---|---|---|
| output* | item | What it makes. |
| count | int 1-64default 1 | How many one craft makes. |
| kind | enum (craft, smelt)default "craft" | craft or smelt. |
| grid | grid | Craft: nine cells, row by row. |
| input | item | Smelt: the input item. |
Verified:Save a recipe: 4 oak planks in a square make a crafting table
Delete a recipe
delete_recipeDeletes a saved recipe of yours for an item.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| output* | item | The recipe's output. |
Verified:Delete my recipe for sticks
Cancel a crafting job
cancel_craftCancels a running or queued crafting or delivery job.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| job | jobdefault "latest" | Which job (default: the latest). |
Verified:Cancel the crafting job
Craft with a crafty turtle's own grid
craft_hereA crafty turtle crafts whatever is laid out in its grid, a number of times.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | The crafty turtle. |
| times | int 1-64default 1 | How many crafts. |
Monitors.
Mirrored screens on the map.
Show a screen on a monitor in the map
show_screenPins a mirrored screen (a station's or a program's monitor) onto the monitor array containing a block in the 3D map.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| source* | string | Which screen: computer id and peripheral name. |
| at* | point | A block of the monitor array. |
Verified:Show 12:monitor_0 on the monitor at the selected block
Unpin a mirrored screen
hide_screenThe screen goes back to its automatic place (next to the computer that draws it).
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| source* | string | Which screen. |
Verified:Unpin screen 12:monitor_0
Fleet management.
Names, homes, positions, worlds, updates and settings.
Rename a turtle
renameSets a turtle's label (its name everywhere).
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| label* | string | The new name. |
Verified:Rename Miner 3 to Digger 2
Set home here
set_homeEach turtle remembers where it stands and which way it faces as home.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
Verified:Set home for every turtle where they areSend Miner 2 to the selected block and make that its home
Forget home
clear_homeThe turtle forgets its home.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
Verified:Scout, forget your home
Tell a turtle where it is
set_positionSets a turtle's position and facing by hand (no GPS). Its home moves with it; what it had seen is forgotten.
Parameters (3)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| at* | point | Its real position. |
| facing* | facing | Which way it faces. |
Locate with GPS
locate_gpsTurtles find their real position with GPS (a wireless modem and a GPS constellation in range).
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
Verified:Relocate every turtle with GPS
Set a turtle's world
set_worldTells a turtle which world (server or dimension) it is in; maps are kept per world.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| world* | string | The world name. |
Verified:Scout is in the nether now
Update the turtle program
update_turtlesTurtles download the latest TurtleDeck program and restart (running programs end first).
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
Refresh a turtle's report
refreshThe turtle looks around, reads its home chest and reports its full state again.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtles | turtlesdefault "all" | Which turtles. |
Verified:Refresh all turtles
Save a file on a turtle
write_fileWrites a text file on the turtle's disk (overwrites a file of that name).
Parameters (3)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
| path* | string | The file path. |
| content* | text | What goes in the file. |
Programs.
Saved programs, verified code and new programs from the AI.
Run a saved program
run_programRuns one of your saved programs on turtles, or split over an area (each turtle gets `area` and its own `lane` as Lua globals).
Parameters (4)
| Name | Type | What it does |
|---|---|---|
| program* | program | Its name in Programs. |
| turtles | turtles | Which turtles (default: the selected one). |
| area | area | Split this area across the turtles. |
| crew | int 1-16 | How many idle turtles help (default: the idle ones nearby, at most 8). |
Verified:Run tree-farm on Miner 5Run my sort program on all idle turtlesSplit the selected area across 3 turtles running wheat
Run checked code
run_codeRuns a Lua program (usually a verified example, whole or changed a little) on turtles. The AI service dry-runs it on the real turtle program in a mock world first; code that fails the check is never run.
Parameters (4)
| Name | Type | What it does |
|---|---|---|
| code* | code | The Lua program. |
| name | stringdefault "program" | A name for the Console. |
| turtles | turtles | Which turtles (default: the selected one). |
| area | area | Split this area across the turtles (area and lane globals). |
Verified:Dig a 1 wide 2 high tunnel 10 blocks ahead of Miner 2 and come backClear a 3x3x3 room in front of Miner 2 and come backBuild a 5x5 cobblestone platform next to Miner 2Walk back from Miner 3 and set a torch every 4 blocks, 5 torches
Write a new program
write_programHands the request to the AI program generator (Programs), which writes, checks and repairs a program you then run yourself.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| prompt* | text | What the program should do, with sizes and coordinates. |
Verified:Write a program that farms sugar cane foreverI need a program that sorts items by mod into different chests
Jobs and control.
Pause, resume, stop, wait and messages inside a plan.
Pause a job
pause_jobPauses a plan, swarm job, crafting job or program: turtles finish the move they are making and wait.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| job | jobdefault "latest" | Which job. |
Verified:Pause the quarry
Resume a job
resume_jobResumes a paused job.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| job | jobdefault "latest" | Which job. |
Verified:Resume the latest job
Stop a job
stop_jobStops a job: every turtle in it stops at once, then goes home or stays where it is.
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| job | jobdefault "latest" | Which job. |
| home | booldefault true | Go home afterwards. |
Verified:Stop the quarry and bring them homeStop the build, leave them where they are
Stop turtles
stop_turtlesStops whatever the named turtles run (their command queue is cleared); they stay where they are.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtles* | turtles | Which turtles. |
Verified:Stop Miner 3
Stop everything
stop_allEvery job, plan and program of the account stops at once; turtles stay where they are or go home.
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| home | booldefault false | Then every turtle goes home (never digging). |
Verified:Stop everythingEmergency stop and send them all home
Wait
waitWaits inside a plan: a number of seconds, until the storage holds enough of an item, until turtles are idle, or until they have enough fuel. Steps after it start when it ends.
Parameters (7)
| Name | Type | What it does |
|---|---|---|
| until | enum (seconds, storage, idle, fuel)default "seconds" | What to wait for. |
| seconds | seconds -21600 | until seconds: how long. |
| item | item | until storage: which item. |
| count | int 1-100000 | until storage: how many. |
| turtles | turtles | until idle / fuel: which turtles. |
| percent | int 1-100 | until fuel: the share of the tank. |
| timeoutMinutes | int 1-1440default 60 | Give up after this long (the step fails). |
Verified:Wait 5 minutes, then send everyone homeWhen storage has 300 iron ingots, craft 10 hoppersOnce the miners are idle, unload them allMine for iron under the selection, and when storage has 400 iron ingots craft 16 iron pickaxes
Write a line in the Console
sayWrites a message in the Console when the plan reaches this step (a milestone to look for).
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| text* | text | The message. |
Verified:Quarry the selection 4 deep and say 'mining done' when they finishSurvey the selected area and at the same time deliver 64 torches, then say done
Questions.
Read-only lookups: fleet, fuel, storage, recipes, the map and jobs.
Fleet summary
fleet_summaryquestion, read onlyHow many turtles are online, idle, busy, offline and crafters, and their average fuel.
returns counts and average fuel
Verified:How many turtles do I have?How many turtles are online?
List turtles
list_turtlesquestion, read onlyTurtles with their status, position and fuel, filtered and sorted.
returns a list of turtles
Parameters (4)
| Name | Type | What it does |
|---|---|---|
| status | enum (all, idle, busy, offline, crafter, online)default "all" | Which ones. |
| sort | enum (name, fuel, distance)default "name" | Order. |
| near | point | For sort distance: from here. |
| limit | int 1-96default 20 | At most this many results. |
Verified:Which turtles are idle?
One turtle
turtle_infoquestion, read onlyEverything about one turtle: position, facing, fuel, status, running program, home, equipment and inventory.
returns the turtle's state
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
Where is a turtle
where_isquestion, read onlyA turtle's position and facing, and how far it is from home and from the fuel chest.
returns position and distances
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
Verified:Where is Scout?
Turtles low on fuel
low_fuelquestion, read onlyTurtles under a share of their tank, lowest first.
returns turtles and their fuel
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| percent | int 1-100default 25 | Under this share. |
Verified:Which turtles are low on fuel?
A turtle's inventory
turtle_inventoryquestion, read onlyWhat a turtle carries, slot by slot, and what it has equipped.
returns slots and items
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| turtle* | turtle | Which turtle. |
Verified:What is Miner 1 carrying?
Which turtles carry an item
who_carriesquestion, read onlyTurtles carrying an item, and how many.
returns turtles and counts
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| item* | block | The item id or part of it. |
Verified:How many diamonds do I have?Which turtle has diamonds on it?
Turtles near a spot
turtles_nearquestion, read onlyTurtles within a distance of a spot, nearest first.
returns turtles and distances
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| at* | point | The spot. |
| radius | int 1-5000default 64 | Blocks. |
Distance between two spots
distancequestion, read onlyBlocks between two spots (or a turtle and a spot): straight line and walking (x + y + z), and the fuel a trip takes.
returns distances and fuel
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| from* | point | From (a point, or a turtle as "$t<id>"). |
| to* | point | To. |
How many of an item
storage_countquestion, read onlyHow many of an item the storage holds, counting other forms (ingots include blocks, raw ore and nuggets that can be turned into them).
returns count, in which forms
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| item* | block | The item id or part of it ("diamond"). |
Verified:How many diamonds do I have?How much iron is in storage?
Search the storage
storage_searchquestion, read onlyStored items whose id or name contains some text, with counts.
returns items and counts
Parameters (2)
| Name | Type | What it does |
|---|---|---|
| text* | string | What to look for. |
| limit | int 1-50default 20 | At most this many results. |
Verified:What kinds of wood do I have?
Biggest stacks in storage
storage_topquestion, read onlyThe items the storage holds most of.
returns items and counts
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| limit | int 1-50default 15 | At most this many results. |
Verified:What is filling up my storage?
How many can be made
can_makequestion, read onlyHow many of an item the storage could deliver right now: stored, plus what recipes, smelting and other forms can make from what is stored.
returns the most that can be made, and what runs short
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| item* | item | The item id. |
Recipe for an item
recipe_forquestion, read onlyThe recipes that make an item (yours first, then built-in ones) and what they need.
returns recipes
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| item* | item | The item id. |
Verified:What is the recipe for a hopper?
Storage stations
stationsquestion, read onlyThe storage stations: online or not, furnaces, crafty turtles, supply chest, when the index was last read.
returns stations
Verified:Is the storage station online?
Blocks in an area
map_areaquestion, read onlyWhat the map knows about an area: block counts by type (between two heights), mapped and unknown columns.
returns block counts
Parameters (4)
| Name | Type | What it does |
|---|---|---|
| area* | area | The area. |
| yMin | int -64-320 | From this height. |
| yMax | int -64-320 | Up to this height. |
| limit | int 1-50default 20 | At most this many results. |
Verified:What blocks are in this area?
Nearest blocks of a kind
map_findquestion, read onlyThe nearest blocks on the map whose id contains some text ("iron_ore", "chest", "diamond"), from a spot or a turtle.
returns blocks with positions and distances
Parameters (4)
| Name | Type | What it does |
|---|---|---|
| block* | block | The block id or part of it. |
| from | point | From here (default: the selected turtle or block). |
| radius | int 1-512default 128 | Search this far. |
| limit | int 1-50default 5 | At most this many results. |
Verified:Where is the nearest iron ore on the map?Find diamonds near Miner 2
Block at a spot
map_blockquestion, read onlyThe block at a spot as the map knows it (with its state), or that it is air or unknown.
returns block name and state
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| at* | point | The spot. |
Verified:What block is at 415 70 -158?
Ground height
map_surfacequestion, read onlyThe highest solid mapped block in a column (the ground under a spot).
returns ground height
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| at* | point | The spot (its y is ignored). |
Verified:How high is the ground at 405 -160?
Map summary
map_summaryquestion, read onlyHow much of this world is mapped: bounds, block count and the most common blocks.
returns bounds and counts
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| limit | int 1-50default 10 | At most this many results. |
Running jobs
jobsquestion, read onlyRunning plans, swarm jobs, crafting jobs and fuel rescues, with progress and who works on them.
returns jobs
Verified:What is running right now?
Who is at a shared chest
chest_queuequestion, read onlyThe turtles using a shared chest right now and the ones waiting in line.
returns holders and waiting turtles
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| kind | chestKinddefault "fuel" | fuel, unload or supply. |
Verified:Who is waiting at the fuel chest?
What can I ask
what_can_i_askquestion, read onlySearches the list of everything TurtleDeck can do (this catalog) and the verified examples.
returns matching actions and examples
Parameters (1)
| Name | Type | What it does |
|---|---|---|
| topic* | string | A word or two. |
Verified:Can the turtles build things?
The td library.
Functions every TurtleDeck program can call (td.*).
td.pos()
td.posCurrent position: returns { x, y, z, facing }.
returns { x, y, z, facing }
Full referencetd.home()
td.homeThe saved home { x, y, z, facing }, or nil if none is set.
returns { x, y, z, facing }|nil
Full referencetd.face(f)
td.faceTurn to face 0 north, 1 east, 2 south, 3 west. Returns true when facing that way.
returns boolean
Full referencetd.digMove(dir?)
td.digMoveMove one block, digging or attacking whatever is in the way. Falling gravel is handled by retrying; chests, machines, other turtles and protected blocks are never dug.
returns ok: boolean, err: string|nil
Full referencetd.digTo(x, y, z)
td.digToStraight-line travel that digs its way: y first, then x, then z.
returns ok: boolean, err: string|nil
Full referencetd.goTo(x, y, z, opts?)
td.goToSmart travel: plans a route over every block the turtle has seen and replans when blocked.
returns ok: boolean, err: string|nil
Full referencetd.learn(boxes)
td.learnTeach the route planner corridors somebody else dug. Returns how many cells were taught (at most 6000 per call).
returns integer
Full referencetd.setHome()
td.setHomeRemember the current spot and facing as home. Home is a parking spot: jobs do not unload there.
returns true
Full referencetd.goHome(opts?)
td.goHomeTravel home with td.goTo and face the home direction. Fails with "No home set" when there is no home.
returns ok: boolean, err: string|nil
Full referencetd.dropJunk()
td.dropJunkDrop cobblestone, dirt, gravel, stone, deepslate, netherrack, tuff, granite, diorite, andesite and flint below the turtle.
Full referencetd.refuel(target)
td.refuelBurn fuel items from the inventory until the fuel level reaches target: one refuel call per stack with the count it needs (1.19.3). Returns whether it got there.
returns boolean
Full referencetd.unload(keepFuel?)
td.unloadEmpty the inventory into a chest / barrel touching the turtle. Keeps one stack of fuel if asked.
returns ok: boolean, err: string|nil
Full referencetd.takeFuel(target, opts?)
td.takeFuelTake fuel from the chest touching the turtle and burn it up to target, in as few pulls as it can (a stack a pull) and one refuel call per stack. What it does not burn goes back into the chest (opts.keep items stay on board).
returns ok: boolean, err: string|nil
Full referencetd.refuelAtDepot(target, opts?)
td.refuelAtDepotFill up at the shared fuel chest through its queue (td.useDepot), never digging, and come back.
returns ok: boolean, err: string|nil
Full referencetd.useDepot(kind, action, opts?)
td.useDepotUse a shared chest without crowding it (1.19.3): the relay gives the turtle its turn when a spot next to the chest is free and a queue spot a few blocks away until then. The trips there and away never dig; a turtle that finds no way waits, says so and tries again.
returns ok: boolean, err: string|nil
Full referencetd.setEnderId(id)
td.setEnderIdSet the item id of the ender chest used by td.dumpViaEnder.
Full referencetd.dumpViaEnder(keep?)
td.dumpViaEnderEmpty the inventory through a carried ender chest (its other end is the deposit chest, which the storage station drains). Placed above, or in front if there is no room above. Returns true, or false and why.
returns ok: boolean, err: string|nil
Full referencetd.clear(dir)
td.clearDig on one side until nothing falls back in (gravel, sand). Protected blocks are left alone.
Full referencetd.run(name, opts, body)
td.runRun custom work as a job: same start/finish logging and return home as the built-in jobs. body receives check(), to call before each block: it keeps the fuel reserve and empties a full inventory (ender chest or shared unload chest).
returns ok: boolean, reason: string|nil
Full referencetd.mine
td.mineBuilt-in mining jobs. Each follows ore veins, keeps enough fuel to get back and unloads when full.
td.mine.strip(opts?)
td.mine.stripMain tunnel with side branches. Resumes where an earlier strip mine from the same spot stopped.
returns ok: boolean, reason: string|nil
Full referencetd.mine.tunnel(opts?)
td.mine.tunnelA plain tunnel without side branches.
returns ok: boolean, reason: string|nil
Full referencetd.mine.ore(opts?)
td.mine.oreGo down (or up) to the best level for an ore (td.ORE_LEVELS), then strip mine there. Needs real coordinates (GPS or setpos).
returns ok: boolean, reason: string|nil
Full referencetd.mine.stairs(opts?)
td.mine.stairsDig a walkable staircase down or up.
returns ok: boolean, reason: string|nil
Full referencetd.mine.hole(opts?)
td.mine.holeDig a box downwards. The turtle sits on the near-left corner: width runs to its right, length ahead, depth below. Resumes below layers dug on an earlier run.
returns ok: boolean, reason: string|nil
Full referencetd.build(bp, opts?)
td.buildBuild a layered blueprint from the bottom up, standing above each layer. Rows run away from the turtle, characters to its right; "." or " " leaves a cell alone. Missing materials are fetched from the supply chest.
returns ok: boolean, reason: string|nil
Full referencetd.upgradeBarrels(opts?)
td.upgradeBarrelsWalk a width x length area one block above a barrel layer, replacing every from barrel below with to. Needs a carried ender chest linked to the deposit chest.
returns ok: boolean, reason: string|nil
Full referencetd.mirrorMonitor(mon)
td.mirrorMonitorDraw on the returned window instead of the monitor, and the website shows the screen on that monitor in the 3D map (about once a second, only rows that changed). Placed by itself when the monitor is on one of the turtle's sides; otherwise click the monitor in the map and pick the screen.
returns window: table
td.depots()
td.depotsThe shared chests this turtle knows, as set on the website and sent by the relay: { fuel = { x, y, z, facing }, unload = ..., supply = ... } (a copy; missing kinds are nil).
returns depots: table
td.fuelRescue(opts)
td.fuelRescueFetch fuel from the shared fuel chest and hand it to the turtle at x, y, z: flies next to it without digging and drops the fuel into it. Used by the website's fuel rescue; returns false and why when it cannot.
returns ok: boolean, count: integer|string, item: string|nil
Full referencetd.survey(opts)
td.surveyFly over an area and record everything it sees (the ground, what is ahead and above, with block state). Never digs, places or attacks: climbs over obstacles, moves only into air and skips what it cannot reach. Returns true, { cells, of, blocks, skipped }.
returns ok: boolean, result: table|string
Full referencetd.ORE_LEVELS
td.ORE_LEVELSBest Y level per ore for Minecraft 1.18+, used by td.mine.ore: coal 96, copper 48, iron 16, gold -16, lapis 0, redstone -59, diamond -59, emerald 236, ancient_debris 15, quartz 15.
returns table
Full referencetd.FUEL_VALUES
td.FUEL_VALUESFuel per item as td.refuel and td.takeFuel count it: coal and charcoal 80, coal block 800, lava bucket 1000, blaze rod 120, dried kelp block 200 (others are measured by burning one).
returns table
td.fence(opts?)
td.fenceturtle 1.20.0+A plan's area rules for this program (1.20.0): every move, dig and place stays inside opts.within and out of every opts.avoid box; routes go round them. A turtle already inside a fenced cell may move out. Cleared when the program ends.
returns true
td.protect(list?)
td.protectturtle 1.20.0+Blocks this program never breaks, beyond chests, machines and computers (1.20.0). Digging one fails with "protected block" and jobs treat it as a wall. Cleared when the program ends.
returns integer
CC:Tweaked turtle API.
Low-level turtle functions, for generated programs.
turtle.forward()
turtle.forwardMove the turtle forward one block
returns success: boolean, errorMessage: string|nil
Full referenceturtle.back()
turtle.backMove the turtle back one block
returns success: boolean, errorMessage: string|nil
Full referenceturtle.up()
turtle.upMove the turtle up one block
returns success: boolean, errorMessage: string|nil
Full referenceturtle.down()
turtle.downMove the turtle down one block
returns success: boolean, errorMessage: string|nil
Full referenceturtle.turnLeft()
turtle.turnLeftRotate the turtle 90 degrees to the left
returns success: boolean, errorMessage: string|nil
Full referenceturtle.turnRight()
turtle.turnRightRotate the turtle 90 degrees to the right
returns success: boolean, errorMessage: string|nil
Full referenceturtle.dig(side?)
turtle.digAttempt to break the block in front of the turtle
returns success: boolean, errorMessage: string|nil
Full referenceturtle.digUp(side?)
turtle.digUpAttempt to break the block above the turtle
returns success: boolean, errorMessage: string|nil
Full referenceturtle.digDown(side?)
turtle.digDownAttempt to break the block below the turtle
returns success: boolean, errorMessage: string|nil
Full referenceturtle.place(text?)
turtle.placePlace a block or item in front of the turtle
returns success: boolean, errorMessage: string|nil
Full referenceturtle.placeUp(text?)
turtle.placeUpPlace a block or item above the turtle
returns success: boolean, errorMessage: string|nil
Full referenceturtle.placeDown(text?)
turtle.placeDownPlace a block or item below the turtle
returns success: boolean, errorMessage: string|nil
Full referenceturtle.drop(count?)
turtle.dropDrop the contents of the currently selected slot into the inventory in front of the turtle or into the world if there is no inventory
returns success: boolean, errorMessage: string
Full referenceturtle.dropUp(count?)
turtle.dropUpDrop the contents of the currently selected slot into the inventory above the turtle or into the world if there is no inventory
returns success: boolean, errorMessage: string
Full referenceturtle.dropDown(count?)
turtle.dropDownDrop the contents of the currently selected slot into the inventory below the turtle or into the world if there is no inventory
returns success: boolean, errorMessage: string
Full referenceturtle.select(slot)
turtle.selectChange the currently selected inventory slot
returns success: boolean
Full referenceturtle.getItemCount(slot?)
turtle.getItemCountGet the number of items in the given slot
returns count: integer
Full referenceturtle.getItemSpace(slot?)
turtle.getItemSpaceGet the remaining space in a stack in a slot
returns count: integer
Full referenceturtle.detect()
turtle.detectCheck if there is a solid (non-air, non-liquid) block in front of the turtle
returns detected: boolean
Full referenceturtle.detectUp()
turtle.detectUpCheck if there is a solid (non-air, non-liquid) block above the turtle
returns detected: boolean
Full referenceturtle.detectDown()
turtle.detectDownCheck if there is a solid (non-air, non-liquid) block below the turtle
returns detected: boolean
Full referenceturtle.compare()
turtle.compareCheck if the block in front of the turtle is the same as the item in the currently selected slot
returns areSame: boolean
Full referenceturtle.compareUp()
turtle.compareUpCheck if the block above the turtle is the same as the item in the currently selected slot
returns areSame: boolean
Full referenceturtle.compareDown()
turtle.compareDownCheck if the block below the turtle is the same as the item in the currently selected slot
returns areSame: boolean
Full referenceturtle.attack(side?)
turtle.attackAttack the entity in front of the turtle
returns attacked: boolean, errorMessage: string|nil
Full referenceturtle.attackUp(side?)
turtle.attackUpAttack the entity above the turtle
returns attacked: boolean, errorMessage: string|nil
Full referenceturtle.attackDown(side?)
turtle.attackDownAttack the entity below the turtle
returns attacked: boolean, errorMessage: string|nil
Full referenceturtle.suck(count?)
turtle.suckSuck an item from the inventory in front of the turtle or from the world if there is no inventory
returns success: boolean, errorMessage: string|nil
Full referenceturtle.suckUp(count?)
turtle.suckUpSuck an item from the inventory above the turtle or from the world if there is no inventory
returns success: boolean, errorMessage: string|nil
Full referenceturtle.suckDown(count?)
turtle.suckDownSuck an item from the inventory below the turtle or from the world if there is no inventory
returns success: boolean, errorMessage: string|nil
Full referenceturtle.getFuelLevel()
turtle.getFuelLevelGet the amount of fuel this turtle has
returns amount: number|"unlimited"
Full referenceturtle.refuel(count?)
turtle.refuelRefuel this turtle using the item in the currently selected slot
returns success: boolean, errorMessage: string|nil
Full referenceturtle.compareTo(slot)
turtle.compareToCompare the item in the currently selected slot to an item in another slot
returns areSame: boolean
Full referenceturtle.transferTo(slot, count?)
turtle.transferToMove an item from the selected slot to another one
returns success: boolean
Full referenceturtle.getSelectedSlot()
turtle.getSelectedSlotGet the currently selected slot
returns slot: integer
Full referenceturtle.getFuelLimit()
turtle.getFuelLimitGet the maximum amount of fuel that this turtle can hold
returns limit: integer|"unlimited"
Full referenceturtle.equipLeft()
turtle.equipLeftEquip/Unequip an item on the left side of this turtle
returns success: boolean, errorMessage: string|nil
Full referenceturtle.equipRight()
turtle.equipRightEquip/Unequip an item on the right side of this turtle
returns success: boolean, errorMessage: string|nil
Full referenceturtle.inspect()
turtle.inspectGet information about the block in front of the turtle
returns blockPresent: boolean, info: inspectInfo|string
Full referenceturtle.inspectUp()
turtle.inspectUpGet information about the block above the turtle
returns blockPresent: boolean, info: inspectInfo|string
Full referenceturtle.inspectDown()
turtle.inspectDownGet information about the block below the turtle
returns blockPresent: boolean, info: inspectInfo|string
Full referenceturtle.getItemDetail(slot?, detailed?)
turtle.getItemDetailGet information about the items in the given slot
returns info: nil|turtleDetails|turtleDetailsDetailed
Full referenceturtle.craft(limit?)
turtle.craftCraft a recipe based on the turtle's inventory
returns success: boolean, errorMessage: string|nil
Full referenceOther CC:Tweaked APIs.
GPS, redstone, peripherals, rednet, os, files and text, for generated programs.
gps.locate(timeout, debug)
gps.locateAttempt to retrieve the location of this computer
returns x: number?, y: number?, z: number?
Full referencevector.new(x, y, z)
vector.newCreate a new `Vector` object with the given coordinates
returns vector: Vector
Full referenceredstone.getSides()
redstone.getSidesGet the valid sides of this computer
returns sides: computerSidesTable
Full referenceredstone.setOutput(side, state)
redstone.setOutputSet the binary state of a redstone signal on a specific side of this computer
Full referenceredstone.getOutput(side)
redstone.getOutputGet the current redstone output state at the side of a computer
returns state: boolean
Full referenceredstone.getInput(side)
redstone.getInputGet the current redstone input of a given side
returns state: boolean
Full referenceredstone.setAnalogOutput(side, strength)
redstone.setAnalogOutputSet the redstone signal strength for a given side
Full referenceredstone.getAnalogOutput(side)
redstone.getAnalogOutputGet the redstone analog output signal strength for a given side
returns strength: signalStrength
Full referenceredstone.getAnalogInput(side)
redstone.getAnalogInputGet the current analog input strength for a given side
returns strength: signalStrength
Full referenceredstone.setBundledOutput(side, colorSet)
redstone.setBundledOutputSet the bundled cable output for a given side
Full referenceredstone.getBundledOutput(side)
redstone.getBundledOutputGet the bundled cable output for a given side
returns number: number
Full referenceredstone.getBundledInput(side)
redstone.getBundledInputGet the bundled cable input for a given side
returns number: number
Full referenceredstone.testBundledInput(side, colorSet)
redstone.testBundledInputTest whether a bundled input is as expected
returns success: boolean
Full referenceperipheral.getNames()
peripheral.getNamesGet a list of all available peripherals
returns peripherals: string[]
Full referenceperipheral.isPresent(name)
peripheral.isPresentDetermines if a peripheral is present
returns isPresent: boolean
Full referenceperipheral.getType(peripheral)
peripheral.getTypeGet the type(s) of a peripheral
returns string
Full referenceperipheral.hasType(peripheral, peripheralType)
peripheral.hasTypeCheck that a peripheral has a given type
returns hasType: boolean|nil
Full referenceperipheral.getMethods(name)
peripheral.getMethodsGet the methods for the peripheral with a given name
returns methods: string[]|nil
Full referenceperipheral.getName(peripheral)
peripheral.getNameGet the name of a wrapped peripheral
returns name: string
Full referenceperipheral.call(name, method, ...)
peripheral.callCall a method on the peripheral with the provided name
returns any
Full referenceperipheral.wrap(name)
peripheral.wrapGet a table containing all methods available on a peripheral
returns wrappedPeripheral: wrappedPeripheral|nil
Full referenceperipheral.find(peripheralType, filter?)
peripheral.findFind all peripherals of a given type and return them wrapped
returns wrappedPeripherals: wrappedPeripheral[]
Full referencerednet.close(modem?)
rednet.closeClose a modem, preventing it from sending or receiving on rednet
Full referencerednet.isOpen(modem)
rednet.isOpenGet whether a modem is currently open on rednet
returns isOpen: boolean
Full referencerednet.send(recipient, message, protocol?)
rednet.sendSend a message to a target computer
returns success: boolean
Full referencerednet.broadcast(message, protocol)
rednet.broadcastBroadcast a message over the channel defined by `rednet.CHANNEL_BROADCAST`
Full referencerednet.receive(protocol?, timeout?)
rednet.receiveReceive a message over rednet
returns sender: number|nil, message: nil|number|boolean|string|table, protocol: nil
Full referencerednet.host(protocol, hostname)
rednet.hostRegister this computer as hosting a specific protocol under the provided hostname. This allows other computers to find this one by using `rednet.lookup()`
Full referencerednet.unhost(protocol)
rednet.unhostStop hosting a certain protocol, preventing this computer from responding to `rednet.lookup()` requests
Full referencerednet.lookup(protocol, hostname?)
rednet.lookupSearch the network for computers hosting a specific protocol
returns number|nil
Full referenceos.pullEvent(event?)
os.pullEventPause execution of the current thread and wait for an event to fire
returns event: event|string, any
Full referenceos.pullEventRaw(event?)
os.pullEventRawPause execution of the current thread and wait for an event to fire, including the terminate event
returns event: event|string, any
Full referenceos.sleep(time)
os.sleepPauses execution for the specified number of seconds. An alias for `_G.sleep()`
Full referenceos.startTimer(seconds)
os.startTimerStart a timer that will fire a `timer` event when it reaches the specified number of seconds.
returns ID: integer
Full referenceos.cancelTimer(ID)
os.cancelTimerCancels a timer that was started with `os.startTimer()`
Full referenceos.queueEvent(name, ...)
os.queueEventAdds an event to the event queue that can later be listened to with `os.pullEvent()`
Full referenceos.getComputerLabel()
os.getComputerLabelGet the label of this computer
returns label: string|nil
Full referenceos.clock()
os.clockGet the number of seconds that this computer has been running for
returns uptime: number
Full referenceos.time(locale?)
os.timeGet the current time in one of the below formats
returns time: number
Full referenceos.day(locale?)
os.dayGet the amount of days since UNIX epoch in one of the below formats
returns days: number
Full referenceos.epoch(locale)
os.epochGet the number of milliseconds since an epoch
returns milliseconds: number
Full referencetextutils.serialize(tbl, options?)
textutils.serializeGet a textual representation of a Lua object, suitable for saving to a file or printing
returns serialized: string
Full referencetextutils.unserialize(str)
textutils.unserializeConvert a serialized string back into a Lua object
returns tbl: serializable
Full referencetextutils.serializeJSON(tbl, NBTstyle?)
textutils.serializeJSONGet a JSON representation of the given value
returns JSON: string
Full referencetextutils.unserializeJSON(str, options?)
textutils.unserializeJSONConvert a serialized JSON string back into a Lua table
returns unserialized: serializable|nil, errorMessage: string|nil
Full referencetextutils.formatTime(time, twentyFourHr)
textutils.formatTimeFormats a time value into a readable string
returns formattedTime: string
Full referenceparallel.waitForAny(...)
parallel.waitForAnySwitches between the execution of the functions until any one of them finishes
Full referenceparallel.waitForAll(...)
parallel.waitForAllSwitches between the execution of the functions until they all finish
Full referencefs.open(path, mode)
fs.openOpens a file for reading/writing
returns handler: ReadHandle|BinaryReadHandle|WriteHandle|BinaryWriteHandle|nil, errorMessage: nil|string
Full referencefs.combine(path, ...)
fs.combineCombine multiple components of a path into a single path
returns string: string
Full referencefs.getFreeSpace(path)
fs.getFreeSpaceGet the amount of free space on the mount that the specified path is located on
returns free: number|"unlimited"
Full referenceterm.clear()
term.clearClears the terminal, filling it with the current background color
Full referenceterm.write(text)
term.writeWrite `text` at the current cursor position, moving the cursor to the end of the text
Full referenceterm.getSize()
term.getSizeGet the size of the terminal
returns width: integer, height: integer
Full referencehttp.get(url, headers?, binary?)
http.getMake a GET request
returns response: Response|BinaryResponse|nil, message: string, failedResponse: nil|Response
Full referencehttp.post(url, body, headers?, binary?)
http.postMake a POST request
returns response: Response|BinaryResponse|nil, message: string, failedResponse: nil|Response
Full referencedisk.isPresent(name)
disk.isPresentChecks that an item is in a disk drive
returns present: boolean
Full referencedisk.eject(name)
disk.ejectEjects any item that is in the drive, dropping it into the world
Full referenceVerified examples.
Requests whose plan passed every check against a test fleet, and whose code (where there is any) ran on the real turtle program in a mock world and loads in CC:Tweaked's own Lua. The AI is shown the ones closest to what you ask and may reuse their plan or code; it says when it does. Copy any of them, or open them in the command bar.
Building
“Build my house blueprint at the selected block facing east”build / reference plan / 2026-09-25
“Build the watchtower at the selected block with 2 turtles, pausing after each layer”build / reference plan / 2026-09-25
“Build a 3-layer storage tower on the selected area”build_tower / reference plan / 2026-09-25
“The layer is connected, continue the build”continue_build / reference plan / 2026-09-25
“Upgrade the iron barrels in the selected area to diamond barrels with Miner 2”upgrade_barrels / reference plan / 2026-09-25
Shared chests
“Use the chest Miner 2 is facing as the fuel chest”set_shared_chest / reference plan / 2026-09-25
“Set the supply chest where the selected turtle stands”set_shared_chest / reference plan / 2026-09-25
“Forget the unload chest”clear_shared_chest / reference plan / 2026-09-25
clarify
“Dig a hole”hole / reference plan / 2026-09-25
“Mine”mine_ore / reference plan / 2026-09-25
“Build something at the selected block”build / reference plan / 2026-09-25
Jobs and control
“Pause the quarry”pause_job / reference plan / 2026-09-25
“Resume the latest job”resume_job / reference plan / 2026-09-25
“Stop the quarry and bring them home”stop_job / reference plan / 2026-09-25
“Stop the build, leave them where they are”stop_job / reference plan / 2026-09-25
“Stop everything”stop_all / reference plan / 2026-09-26
“Emergency stop and send them all home”stop_all / reference plan / 2026-09-26
“Wait 5 minutes, then send everyone home”wait + home / reference plan / 2026-09-25
“When storage has 300 iron ingots, craft 10 hoppers”wait + craft / reference plan / 2026-09-25
“Once the miners are idle, unload them all”wait + unload / reference plan / 2026-09-25
“Quarry the selection 4 deep and say 'mining done' when they finish”quarry + say / reference plan / 2026-09-25
Fuel
“Refuel all turtles to 50%. Do not include crafty turtles.”refuel / reference plan / 2026-09-25
“Refuel all turtles one at a time to 50%. Do not include crafty turtles. Do not break blocks. Return home once finished.”refuel / reference plan / 2026-09-26
“Top up Miner 1 to 80% and bring it back here”refuel / reference plan / 2026-09-26
“Refuel every turtle under 20% to half a tank”refuel / reference plan / 2026-09-25
“Have every turtle burn the coal it carries”burn_fuel / reference plan / 2026-09-25
“Refuel Miner 2 from its own inventory to 30%”burn_fuel / reference plan / 2026-09-25
“Miner 1 ran out of fuel, send it some”send_fuel / reference plan / 2026-09-25
“Cancel the fuel rescue for Miner 1”cancel_rescue / reference plan / 2026-09-25
“Turn off automatic fuel rescue”auto_rescue / reference plan / 2026-09-25
“Refuel all turtles to 50%, they can all crowd the chest at once”refuel / reference plan / 2026-09-26
“Refuel everyone to 60% and let them dig through if they get stuck”refuel / reference plan / 2026-09-26
Fleet management
“Rename Miner 3 to Digger 2”rename / reference plan / 2026-09-25
“Set home for every turtle where they are”set_home / reference plan / 2026-09-25
“Scout, forget your home”clear_home / reference plan / 2026-09-25
“Miner 5 is really at 100 64 -20 facing north”set_position / reference plan / 2026-09-25
“Relocate every turtle with GPS”locate_gps / reference plan / 2026-09-25
“Scout is in the nether now”set_world / reference plan / 2026-09-25
“Update all turtles except the crafters”update_turtles / reference plan / 2026-09-25
“Refresh all turtles”refresh / reference plan / 2026-09-25
graphs
“Refuel everyone to 50%, then survey the selected area”refuel + survey / reference plan / 2026-09-25
- 01Refuel 6 turtles under 50% at the fuel chest (411 71 -158), one at a time, without breaking blocks, then home. The other 3 have enough. Crafty is left out.
- 02Survey x 402..417, z -170..-155 (16 x 16) in 2 passes with 8 turtles, never digging or placing. (after step 1)
“Quarry the selected area 5 deep, then have everyone unload”quarry + unload / reference plan / 2026-09-25
“Survey the selected area and at the same time deliver 64 torches, then say done”survey + deliver + say / reference plan / 2026-09-25
“Refuel only the turtles under 30% fuel, then send Scout to the selected block”refuel + go / reference plan / 2026-09-25
- 01Refuel 6 turtles under 50% at the fuel chest (411 71 -158), one at a time, without breaking blocks, then home. The other 3 have enough. Crafty is left out. Only turtles under 30% fuel then.
- 02Send Scout to 405 69 -160 without breaking blocks. (after step 1)
“Mine for iron under the selection, and when storage has 400 iron ingots craft 16 iron pickaxes”mine_ore + wait + craft / reference plan / 2026-09-25
“Unload everyone one at a time, then refuel them to 60%, then home”unload + refuel / reference plan / 2026-09-25
- 01Unload 9 turtles at the unload chest, one at a time, keeping a stack of fuel, then home. Crafty is left out.
- 02Refuel 6 turtles under 60% at the fuel chest (411 71 -158), one at a time, without breaking blocks, then home. The other 3 have enough. Crafty is left out. (after step 1)
“Dig a 2x2 tunnel 30 long west from the selected block, then stairs 10 down facing west from 375 69 -160”tunnel + stairs / reference plan / 2026-09-25
“Send Miner 2 to the selected block and make that its home”go + set_home / reference plan / 2026-09-25
“Send Miner 1 and Miner 2 to the fuel chest, wait 30 seconds, and bring them home”gather + wait + home / reference plan / 2026-09-25
“Survey the selection now, and again in 10 minutes”survey + wait + survey / reference plan / 2026-09-25
“Quarry the selection 4 deep; even if that fails, send everyone home afterwards”quarry + home / reference plan / 2026-09-25
“Turtles that carry coal burn it, then everyone goes home”burn_fuel + home / reference plan / 2026-09-25
Inventory
“Everyone unload at the deposit chest”unload / reference plan / 2026-09-26
“Empty Miner 3's inventory into storage and come back”unload / reference plan / 2026-09-25
“Have all turtles drop their cobblestone”drop_junk / reference plan / 2026-09-25
“Scout, dump everything through the ender chest”unload_ender / reference plan / 2026-09-25
“Equip the diamond pickaxe on Miner 5's left”equip / reference plan / 2026-09-25
“Select slot 3 on Miner 1”select_slot / reference plan / 2026-09-25
“Move Miner 1's slot 1 into slot 5”move_items / reference plan / 2026-09-25
“Tidy up every turtle's inventory”stack_items / reference plan / 2026-09-25
“Miner 1, put all your raw iron in the chest in front”drop_items / reference plan / 2026-09-25
“Scout, take a stack from the chest below”pick_up / reference plan / 2026-09-25
Moving turtles
“Send Miner 2 to 420 70 -140”go / reference plan / 2026-09-25
“Move turtle 12 to the selected block”go / reference plan / 2026-09-25
“Take Miner 1 to the fuel chest without breaking anything”go / reference plan / 2026-09-25
“Go to 430 70 -140 using only known tunnels”go / reference plan / 2026-09-25
“Send everyone home”home / reference plan / 2026-09-26
“Miner 3 and Miner 4 go home without digging”home / reference plan / 2026-09-26
“Return all turtles home except the crafty ones”home / reference plan / 2026-09-26
“Turn Miner 2 to face north”face / reference plan / 2026-09-25
“Make all turtles face east”face / reference plan / 2026-09-25
“Move Scout forward 5 blocks”move / reference plan / 2026-09-25
“Take the selected turtle up 10”move / reference plan / 2026-09-25
“Turn Scout around”turn / reference plan / 2026-09-25
“Bring every idle turtle to the selected block”gather / reference plan / 2026-09-25
Monitors
“Show 12:monitor_0 on the monitor at the selected block”show_screen / reference plan / 2026-09-25
Mapping
“Survey a 100x100 area centred on 400 70 -150”survey / reference plan / 2026-09-25
“Map the selected area with 3 turtles”survey / reference plan / 2026-09-25
“Discover the terrain in the selected area without digging”survey / reference plan / 2026-09-25
“Have every turtle look around”scan / reference plan / 2026-09-25
“Geo scan 16 blocks around Scout”geoscan / reference plan / 2026-09-25
“Teach Miner 2 that the selected area is an open tunnel 3 high”teach_route / reference plan / 2026-09-25
“Miner 4, forget what you have seen”forget_turtle_map / reference plan / 2026-09-25
“Survey the selected area in one pass, but keep out of the village from 395 -175 to 400 -171”survey / reference plan / 2026-09-25
Programs
“Run tree-farm on Miner 5”run_program / reference plan / 2026-09-25
“Run my sort program on all idle turtles”run_program / reference plan / 2026-09-25
“Split the selected area across 3 turtles running wheat”run_program / reference plan / 2026-09-25
“Write a program that farms sugar cane forever”write_program / reference plan / 2026-09-25
“I need a program that sorts items by mod into different chests”write_program / reference plan / 2026-09-25
“Dig a 1 wide 2 high tunnel 10 blocks ahead of Miner 2 and come back”run_code / with verified code / reference plan / 2026-09-25
“Clear a 3x3x3 room in front of Miner 2 and come back”run_code / with verified code / reference plan / 2026-09-25
“Build a 5x5 cobblestone platform next to Miner 2”run_code / with verified code / reference plan / 2026-09-25
“Walk back from Miner 3 and set a torch every 4 blocks, 5 torches”run_code / with verified code / reference plan / 2026-09-25
“Have Scout build a 6 high cobblestone pillar and come back down”run_code / with verified code / reference plan / 2026-09-25
“Build a wall of oak planks 5 long and 3 high next to Miner 4”run_code / with verified code / reference plan / 2026-09-25
“Build a 10 block plank bridge 3 blocks up with Miner 2”run_code / with verified code / reference plan / 2026-09-25
“Have Scout patrol a 6x6 square once without digging and come home”run_code / with verified code / reference plan / 2026-09-25
“Miner 1, empty everything except fuel into the chest under your home”run_code / with verified code / reference plan / 2026-09-25
“Miner 1, take coal from the chest under your home and refuel to 2000”run_code / with verified code / reference plan / 2026-09-25
“Dig a staircase 5 steps down in front of Miner 2 and come back up”run_code / with verified code / reference plan / 2026-09-25
“Tunnel 12 blocks ahead with Miner 2 and mine every ore vein it touches, then come back”run_code / with verified code / reference plan / 2026-09-25
“Chop the tree in front of Miner 5”run_code / with verified code / reference plan / 2026-09-25
“Harvest the row of 8 sugar cane to the right of Miner 6”run_code / with verified code / reference plan / 2026-09-25
“Bore a 1x1 shaft 12 blocks down next to Miner 2 and come back up”run_code / with verified code / reference plan / 2026-09-25
“Print what Miner 1 carries, slot by slot”run_code / with verified code / reference plan / 2026-09-25
“Have Scout look in every direction and say what is there”run_code / with verified code / reference plan / 2026-09-25
“Merge the partial stacks in Miner 1 with a small program”run_code / with verified code / reference plan / 2026-09-25
“Send three 2 second redstone pulses out of the back of Scout”run_code / with verified code / reference plan / 2026-09-25
- 01Run "redstone pulses" on Scout, checked in a dry run (it dug 0, placed 0, used 2 fuel).
- 02Run "redstone pulses" on Scout.
Dry run on the real turtle program: finished, dug 0, placed 0, fuel used 2. Loads in CC:Tweaked's Lua.