This document present robots behaviors, limitations and usages for detailled functions and syntax, see 'apibasicrobot'
The robot can move around, sense the blocks, dig, build, and much more.
Users can write programs for the bot in Lua. There is also a remote control.
The system uses a spawner ('cpu-box') that the player has to place on the ground. This spawner presents a form for controlling, programming and running the robot ("worker"). Only this worker moves around, and it has a limited range (about 23 nodes from player and spawner).
A keypad from the mod basic_machines can be set up to start a robot with a button-push by other players, and for keyboard-entry. This is useful for robots that perform a task for other players, e.g. as a shop, mailbox, chatbot, game, etc.
Mainly, robots are constituted of the two part mentionned above : you can write code in the spawner ('cpu-box') and run it with the sart button. The 'worker' will appear above the spawns block and execute the code from there.
It is someting easier to call 'robot' the worker part of the robot, saying think like : The spwaner looks like a ... cpu-box while the robot looks like a simple box, with a face on its frontside, and an arrow on top.
You can craft a robot using 6 mese crystals atop a stone, a steel ingot, and another stone. You can craft a remote control using mese crystal under a stick
Rightclicking the spawner opens a form with buttons and a textbox for writing a program.
Button "Save" saves the program. This must be done before starting a program.
Note: Saving is not permanent - there is no file to save to, just a quick syntax-check. Also, picking up the spawner clears the textarea with the code. So, use cut and paste to save your code to a texteditor, such as notepad.
Button "Start" creates a robot-worker (on top of the spawner) that starts executing the program.
Button "Stop" stops the program and removes the robot-worker.
Entryfield id for controlling several robots. Players without the priv 'robot' are only allowed to run 2 robots at the same time. This means they can only use the ids 1 and 2.
Button "Inventory" opens the inventory of the bot. The inventory has 8*4 slots, same size as a chest. Robot can store thing to its inventory (e.g. materials gathered while digging), they can also take thing from it (e.g. to produce energy)
Button "Library" opens a "bookshelf". The robot can read and write books here. This can be used for program code, input and output.
Button "Help" shows some helptext.
Press ESC to exit the form.
Each spawner can only run one bot at a time. To pick up the spawner, its inventory and library must be empty (like a chest).
While the robots is running, rightclicking it will also open the form (without the Start-button), so you can stop it, and access its inventory.
The code of a program is executed repeatedly, about once every second.
After editing the program of a running robot won't affect it until it is stopped and restarted.
The robot require energy to perform some actions like digging, smelting, grinding or compressing.
If the robot as the required fuel in its inventory (e.g. a coal lump ), it can be programmed to produce energy using machine.generate_power("default:coal_lump")
Energy level can be consulted using machine.energy().
As said above, the robot program runs in a loop. This means that unless specificly asking it to stop, the robot will execute the code again and again and again... as long as it can. Because of this, some operations can only be performed a limited number of time per run. These actions includes the ones mentionned above along with some other (including generating energy).
If this limit is reached, the code won't execute and the robot will return this error message : robot out of available operations in one step.
The limit is sometime called 'maxdig' or 'maxoperations' (as the name of the variable defining it).
The default for this limit is 2. This means that when the robot is starting, there must be less than 2 operations in one loop.
For exemple, I cannot run this programm :
machine.generate_power("default:jungletree") -- limited operation dig.forward() -- limited operation move.forward() dig.up() -- limited operation
According to this code, the robot should, generate some power from some jungle tree, dig forward, move foward, dig upwards and ... repeat itself. But it won't do any of that because that 3 limited operations would be performed in one execution
The trick would be increment a number to divide the steps, like this :
if not i then i = 1 end --initialize i if i == 1 then machine.generate_power("default:jungletree")
elseif i == 2 then dig.forward()
move.forward() elseif i == 3 then dig.up()
i = 0 end
i = i + 1
In this exemple 'i' is set to 1 initially, and its value will be upped each time code is executed (because of the last line).
The first time the code is executed, 'i' is set to one, power will be generated
The second time the code is executed, 'i' will be egal 2, the robot will dig forward and move forward,
The third time the code is executed, 'i' will be egal 3, the robot will dig up and reset the value of i to 0 so that after last line, it will be egal 1.
So the fourth time is like the first, the fifth is like the second, the sixth is like the third, and so on...
Altough it doesn't see to be subject to gravity, the robot cannot hover over more than one block of air. If asked to move toward a cliff, the robot will simply ignore the operation that would put him in a situation with too much void under... ... but it will continue executing its program regardless of the - sometme catastophic - consequences of this skipped step !
Quite unlike the eternal question 'Does a falling tree make sound if there is no one to hear it ?', we can answer this one : 'Does a robot worker works when there is no one around to see it ?'. And the answer is NO.
In minetest, areas that are not populated (with players), are unloaded. So if you wander off leaving your robot to its work, it will soon stop working. But there is worse ! When you come back, you robot will be loaded again and will restart its program AT THE BEGINNING, regardless to were it stopped. Resulting (again) in a giant mess due to a few steps skipped. So, ... Be warned
A few things to know about robots, summarized in a short lists
There is also a remote control.
You can write code in the spawner ('cpu-box') and run it with the 'start' button. The 'worker' will appear above the spawns block and execute the code from there.
The spwaner looks like a ... cpu-box while the robot looks like a simple box, with a face on its frontside, and an arrow on top.
Standard users are allowed to control 2 robots. Each spawner can only run one bot at a time.
Robot can store things to its inventory (e.g. materials gathered while digging), they can also take thing from it (e.g. to produce energy)
The robot can read and write books contained in their 'library'. This can be used for program code, input and output.
To pick up the spawner, its inventory and library must be empty (like a chest).
The code of a program is executed repeatedly, about once every second.
The robot require energy to perform some actions like digging, smelting, grinding or compressing.
Some operations can only be performed a limited number of time per run otherwise the robot will return this error message : robot out of available operations in one step.
(The trick would be increment a number to divide the steps, like this )
The robot cannot hover over more than one block of air (and will skip the instruction to do so).
If you wander off leaving your robot to its work, it will stop and restart its program AT THE BEGINNING when you come back.
This document present most of functions and syntax usable inside robots For details about behaviors, limitations and usages, see 'apibasicrobot'
most of basic lua syntax allowed
if x==1 then A else B end for i = 1, 5 do something end while i<6 do A; i=i+1; end
arrays:
myTable1 = {1,2,3}, myTable2 = {[\"entry1\"]=5, [\"entry2\"]=1}
access table entries with myTable1[1] or myTable2.entry1 or myTable2[\"entry1\"]
( See lua syntax for more detailled informations )
move.direction() where direction is forward, backward, left,right, up, down), forwarddown direction only works with dig, place and readnode
turn.left(), turn.right(), turn.angle(45)
dig.direction()
place.direction(\"default:dirt\", optional orientation param)
read_node.direction() tells you names of nodes
insert.direction(item, inventory) inserts item from robot inventory to target inventory
check_inventory.direction(itemname, inventory, index) looks at node and returns false/true, direction can be self,
if index>0 it returns itemname. if itemname == \"\" it checks if inventory empty
activate.direction(mode) activates target block
pickup(r) picks up all items around robot in radius r<8 and returns list or nil
craft(item,mode) crafts item if required materials are present in inventory. mode = 1 returns recipe
take.direction(item, inventory) takes item from target inventory into robot inventory
read_text.direction(stringname,mode) reads text of signs, chests and other blocks, optional stringname for other meta, mode 1 read number
write_text.direction(text,mode) writes text to target block as infotext
title,text=book.read(i) returns title,contents of book at i-th position in library
book.write(i,title,text) writes book at i-th position at spawner library
code.run(text) compiles and runs the code in sandbox
code.set(text) replaces current bytecode of robot
find_nodes(\"default:dirt\",3) returns distance to node in radius 3 around robot, or false if none
find_player(3) finds players in radius 3 around robot and returns list, if none returns nil
attack(target) attempts to attack target player if nearby
grab(target) attempt to grab target player if nearby and returns true if succesful
player.getpos(name) return position of player, player.connected() returns list of players
say(\"hello\") will speak
self.listen(0/1) (de)attaches chat listener to robot
speaker, msg = self.listen_msg() retrieves last chat message if robot listens
self.send_mail(target,mail) sends mail to target robot
sender,mail = self.read_mail() reads mail, if any
self.pos() returns table {x=pos.x,y=pos.y,z=pos.z}
self.name() returns robot name
self.set_properties({textures=.., visual=..,visual_size=.., , ) sets visual appearance
set_animation(anim_start,anim_end,anim_speed,anim_stand_start) set mesh animation
self.spam(0/1) (dis)enable message repeat to all
self.remove() stops program and removes robot object
self.reset() resets robot position
self.spawnpos() returns position of spawner block
self.viewdir() returns vector of view for robot
self.fire(speed, pitch,gravity) fires a projectile from robot
self.fire_pos() returns last hit position
self.label(text) changes robot label
self.display_text(text,linesize,size) displays text instead of robot face, if no size return text
self.sound(sample,volume) plays sound named 'sample' at robot location
rom is aditional table that can store persistent data, like rom.x=1
.
place spawner at coordinates (20i,40j+1,20k) to monitor events
keyboard.get() returns table {x=..,y=..,z=..,puncher = .. , type = .. } for keyboard event
keyboard.set(pos,type) set key at pos of type 0=air, 1..6, limited to range 10 around
keyboard.read(pos) return node name at pos
namespace 'machine'. most functions return true or nil, error
machine.energy() displays available energy
machine.generate_power(fuel, amount) = energy, attempt to generate power from fuel material
if amount>0 try generate amount of power using builtin generator - this requires 40 gold/mese/diamonblock upgrades for each 1 amount
machine.smelt(input,amount) = progress/true. works as a furnace
if amount>0 try to use power to smelt - requires 10 upgrades for each 1 amount, energy cost is 1/40*(1+amount)
machine.grind(input) grinds input material, requires upgrades for harder material
machine.compress(input) requires upgrades - energy intensive process
machine.transfer_power(amount,target_robot_name)
namespace 'crypto'
crypto.encrypt(input,password) returns encrypted text, password is any string
crypto.decrypt(input,password) attempts to decrypt encrypted text
crypto.scramble(input,randomseed,sgn) (de)permutes text randomly according to sgn = -1,1
crypto.basic_hash(input,n) returns simple mod hash from string input within range 0...n-1
... TODO
... TODO