basic_robot_terminal/robot_doc.html

<h1>Robot Documentation</h1>
<a name='top'></a><ul>
	<li><a href="#robot_doc_1.md"> About Robots</a>
	<br> -  Guide to understand Robots usages and behaviors</li>
	<li><a href="#robot_doc_2.md"> About Robots - The short version</a>
	<br> -  Short Guide to Robots Usage</li>
	<li><a href="#robot_doc_3.md"> Robot API</a>
	<br> -  Robot functions and syntax usable inside robots</li>
	<li><a href="#robot_doc_4.md"> Lua Syntax</a>
	<br> -  Lua syntax allowed in basic_robot scripts</li>
	<li><a href="#robot_doc_5.md"> Robot API (admin)</a>
	<br> -  Robot functions and syntax usable inside robots with admin privilege</li>
</ul>

<hr>
<a name="robot_doc_1.md"></a><a href="#top">-- Return to Index --</a><br>
<!--
-- title : About Robots
-- author : 
-- description : Guide to understand Robots usages and behaviors
-- source : parts from https://wiki.minetest.net/Mods/basic_robot
-->

<p>This document present robots behaviors, limitations and usages
for detailled functions and syntax, see 'api<em>basic</em>robot'</p>

<h1>About Robots</h1>

<h2>Introduction</h2>

<p>The robot can move around, sense the blocks, dig, build, and much more.</p>

<p>Users can write programs for the bot in Lua. There is also a remote control.</p>

<p>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).</p>

<p>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. </p>

<p>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.</p>

<p>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. </p>

<h2>How to get it ?</h2>

<p>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</p>

<h2>Controlling Form</h2>

<p>Rightclicking the spawner opens a form with buttons and a textbox for writing a program.</p>

<ul>
<li><p>Button "Save" saves the program. This must be done before starting a program. </p>

<p>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. </p></li>
<li><p>Button "Start" creates a robot-worker (on top of the spawner) that starts executing the program. </p></li>
<li><p>Button "Stop" stops the program and removes the robot-worker. </p></li>
<li><p>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.</p></li>
<li><p>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)</p></li>
<li><p>Button "Library" opens a "bookshelf". The robot can read and write books here. 
This can be used for program code, input and output. </p></li>
<li><p>Button "Help" shows some helptext.</p></li>
</ul>

<p>Press ESC to exit the form. </p>

<h3>Notes</h3>

<p>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).</p>

<p>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. </p>

<p>The code of a program is executed repeatedly, about once every second.</p>

<p>After editing the program of a running robot won't affect it until it is stopped and restarted. </p>

<h2>Capabilities</h2>

<ul>
<li>Energy</li>
</ul>

<p>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 <code>machine.generate_power("default:coal_lump")</code> 
Energy level can be consulted using <code>machine.energy()</code>.
<!-- Note : Write about upgarde --></p>

<ul>
<li>Maxdig</li>
</ul>

<p>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).
<!-- Note : A complete list would be good !--></p>

<p>If this limit is reached, the code won't execute and the robot will return this error message : <code>robot out of available operations in one step.</code>
The limit is sometime called 'maxdig' or 'maxoperations' (as the name of the variable defining it).
<!-- Note : Mabe store maxoperations in self in order to consult it in-game-->
<!-- Note : Setting the limit to 3 might be a good thing too-->
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 :</p>

<blockquote>
  <p>machine.generate_power("default:jungletree")  -- limited operation 
dig.forward()                                 -- limited operation
move.forward()
dig.up()                                      -- limited operation</p>
</blockquote>

<p>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</p>

<p>The trick would be increment a number to divide the steps, like this :</p>

<blockquote>
  <p>if not i then i = 1 end   --initialize i
if i == 1 then        machine.generate_power("default:jungletree") <br />
elseif i == 2 then    dig.forward() <br />
                      move.forward()
elseif i == 3 then    dig.up() <br />
                      i = 0
end <br />
i = i + 1                                         </p>
</blockquote>

<p>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 <br />
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...</p>

<ul>
<li>Gravity</li>
</ul>

<p>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 !</p>

<p><check> If despite this beahior, the robot ends up above more than one block of air, it will simply stop and disapear.</p>

<ul>
<li>Sound of a falling tree</li>
</ul>

<p>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.</p>

<p>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</p>

<hr>
<a name="robot_doc_2.md"></a><a href="#top">-- Return to Index --</a><br>
<!--
-- title : About Robots - The short version
-- author : 
-- description : Short Guide to Robots Usage
-- source : parts from https://wiki.minetest.net/Mods/basic_robot
-->

<h1>Things to know about Robots</h1>

<p>A few things to know about robots, summarized in a short lists</p>

<ul>
<li>The robot can do a lot of things, They execute programs written in Lua.</li>
<li><p>There is also a remote control.</p></li>
<li><p>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.</p></li>
<li><p>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. </p></li>
<li><p>Standard users are allowed to control 2 robots. Each spawner can only run one bot at a time.</p></li>
<li><p>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)</p></li>
<li><p>The robot can read and write books contained in their 'library'.  This can be used for program code, input and output. </p></li>
<li><p>To pick up the spawner, its inventory and library must be empty (like a chest).</p></li>
<li><p>The code of a program is executed repeatedly, about once every second.</p></li>
<li><p>The robot require energy to perform some actions like digging, smelting, grinding or compressing.</p></li>
<li><p>Some operations can only be performed a limited number of time per run otherwise the robot will return this error message : <code>robot out of available operations in one step.</code></p></li>
</ul>

<p>(The trick would be increment a number to divide the steps, like this )</p>

<ul>
<li><p>The robot cannot hover over more than one block of air (and will skip the instruction to do so).</p></li>
<li><p>If you wander off leaving your robot to its work, it will stop and restart its program AT THE BEGINNING when you come back.</p></li>
</ul>

<hr>
<a name="robot_doc_3.md"></a><a href="#top">-- Return to Index --</a><br>
<!--
-- title : Robot API
-- author : 
-- description : Robot functions and syntax usable inside robots
-- source : In-Game Help from basic_robot mod
--  converted to mod syntax but still importable into a text area
-- (...still waiting for in-game markdown parser)               
-->

<h1>Robot API</h1>

<p>This document present most of functions and syntax usable inside robots
For details about behaviors, limitations and usages, see 'api<em>basic</em>robot'</p>

<h3>BASIC LUA SYNTAX</h3>

<p>most of basic lua syntax allowed</p>

<blockquote>
  <p>if x==1 then A else B end
  for i = 1, 5 do something end
  while i&lt;6 do A; i=i+1; end</p>
</blockquote>

<p>arrays:</p>

<blockquote>
  <p>myTable1 = {1,2,3},  myTable2 = {[\"entry1\"]=5, [\"entry2\"]=1}</p>
</blockquote>

<p>access table entries with myTable1[1] or myTable2.entry1 or myTable2[\"entry1\"]</p>

<p>( See lua syntax for more detailled informations )</p>

<h2>ROBOT COMMANDS</h2>

<h3>MOVEMENT,DIGGING, PLACING, INVENTORY TAKE/INSERT</h3>

<p><code>move.direction()</code> where direction is forward, backward, left,right, up, down), forward<em>down direction only works with dig, place and read</em>node
<code>turn.left()</code>, <code>turn.right()</code>, <code>turn.angle(45)</code>
<code>dig.direction()</code>
<code>place.direction(\"default:dirt\", optional orientation param)</code>
<code>read_node.direction()</code> tells you names of nodes
<code>insert.direction(item, inventory)</code> inserts item from robot inventory to target inventory
<code>check_inventory.direction(itemname, inventory, index)</code> looks at node and returns false/true, direction can be self,
 if index>0 it returns itemname. if itemname == \"\" it checks if inventory empty
<code>activate.direction(mode)</code> activates target block
<code>pickup(r)</code> picks up all items around robot in radius r&lt;8 and returns list or nil
<code>craft(item,mode)</code> crafts item if required materials are present in inventory. mode = 1 returns recipe
<code>take.direction(item, inventory)</code> takes item from target inventory into robot inventory
<code>read_text.direction(stringname,mode)</code> reads text of signs, chests and other blocks, optional stringname for other meta, mode 1 read number
<code>write_text.direction(text,mode)</code> writes text to target block as infotext</p>

<h3>BOOKS/CODE</h3>

<p><code>title,text=book.read(i)</code> returns title,contents of book at i-th position in library
<code>book.write(i,title,text)</code> writes book at i-th position at spawner library
<code>code.run(text)</code> compiles and runs the code in sandbox
<code>code.set(text)</code> replaces current bytecode of robot
<code>find_nodes(\"default:dirt\",3)</code> returns distance to node in radius 3 around robot, or false if none</p>

<h3>PLAYERS</h3>

<p><code>find_player(3)</code> finds players in radius 3 around robot and returns list, if none returns nil
<code>attack(target)</code> attempts to attack target player if nearby
<code>grab(target)</code> attempt to grab target player if nearby and returns true if succesful
<code>player.getpos(name)</code> return position of player, player.connected() returns list of players</p>

<h3>ROBOT</h3>

<p><code>say(\"hello\")</code> will speak
<code>self.listen(0/1)</code> (de)attaches chat listener to robot
<code>speaker, msg = self.listen_msg()</code> retrieves last chat message if robot listens
<code>self.send_mail(target,mail)</code> sends mail to target robot
<code>sender,mail = self.read_mail()</code> reads mail, if any
<code>self.pos()</code> returns table {x=pos.x,y=pos.y,z=pos.z}
<code>self.name()</code> returns robot name
<code>self.set_properties({textures=.., visual=..,visual_size=.., , )</code> sets visual appearance
<code>set_animation(anim_start,anim_end,anim_speed,anim_stand_start)</code> set mesh animation
<code>self.spam(0/1)</code> (dis)enable message repeat to all
<code>self.remove()</code> stops program and removes robot object
<code>self.reset()</code> resets robot position
<code>self.spawnpos()</code> returns position of spawner block
<code>self.viewdir()</code> returns vector of view for robot
<code>self.fire(speed, pitch,gravity)</code> fires a projectile from robot
<code>self.fire_pos()</code> returns last hit position
<code>self.label(text)</code> changes robot label
<code>self.display_text(text,linesize,size)</code> displays text instead of robot face, if no size return text
<code>self.sound(sample,volume)</code> plays sound named 'sample' at robot location
rom is aditional table that can store persistent data, like <code>rom.x=1</code>
.</p>

<h3>KEYBOARD</h3>

<p>place spawner at coordinates (20i,40j+1,20k) to monitor events</p>

<p><code>keyboard.get()</code> returns table {x=..,y=..,z=..,puncher = .. , type = .. } for keyboard event
<code>keyboard.set(pos,type)</code> set key at pos of type 0=air, 1..6, limited to range 10 around
<code>keyboard.read(pos)</code> return node name at pos</p>

<h3>TECHNIC FUNCTIONALITY</h3>

<p>namespace 'machine'. most functions return true or nil, error</p>

<p><code>machine.energy()</code> displays available energy
<code>machine.generate_power(fuel, amount)</code> = 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
<code>machine.smelt(input,amount)</code> = 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)
<code>machine.grind(input)</code>  grinds input material, requires upgrades for harder material
<code>machine.compress(input)</code> requires upgrades - energy intensive process
<code>machine.transfer_power(amount,target_robot_name)</code></p>

<h2>CRYPTOGRAPHY</h2>

<p>namespace 'crypto'</p>

<p><code>crypto.encrypt(input,password)</code> returns encrypted text, password is any string
<code>crypto.decrypt(input,password)</code> attempts to decrypt encrypted text
<code>crypto.scramble(input,randomseed,sgn)</code>  (de)permutes text randomly according to sgn = -1,1
<code>crypto.basic_hash(input,n)</code> returns simple mod hash from string input within range 0...n-1</p>

<hr>
<a name="robot_doc_4.md"></a><a href="#top">-- Return to Index --</a><br>
<!--
-- title : Lua Syntax
-- author : 
-- description : Lua syntax allowed in basic_robot scripts
-- source : 
-->

<h3>Lua Syntax</h3>

<p>... TODO</p>

<hr>
<a name="robot_doc_5.md"></a><a href="#top">-- Return to Index --</a><br>
<!--
-- title : Robot API (admin)
-- author : 
-- description : Robot functions and syntax usable inside robots with admin privilege
-- source :         
-->

<h3>Robot API (Admin)</h3>

<p>... TODO</p>