Document object.id and retobjectbyid()

help/cbot/E/object.txt

@@ -16,6 +16,7 @@ Use this type for variables that contain the characteristics of an object, be it
 \c;\l;int\u cbot\int;    object.team         \n;The object's team (see \l;code battles\u battles;)
 \c;\l;point\u cbot\point;  object.velocity     \n;Velocity of the object
 \c;\l;bool\u cbot\bool;   object.dead         \n;Is the object dead?
+\c;\l;int\u cbot\int;    object.id           \n;The id of the object
 
 Also, some objects have additional methods (instructions). See them in \l;the main list\u cbot; in the \c;"Instructions specific for some objects" section.
 
@@ -67,6 +68,9 @@ Current velocity of the object. Should be treated as a three-dimensional vector.
 \s;\c;dead\n;
 True if the object was recently killed (while the death animation is playing). Note that accessing this property or any other property after the death animation finishes will cause an error that stops the program.
 
+\s;\c;id\n;
+The id of an object never changes. Two objects never have the same id. The ids of destroyed objects are not reused. See \c;\l;retobjectbyid\u cbot\retobjectbyid;
+
 \b;Examples
 The type \c;object\n; returns the special value \c;\l;null\u cbot\null;\n; when the object does not exist. For example:
 \c;

help/cbot/E/retobj.txt

@@ -2,10 +2,18 @@
 Syntax:
 \s;\c;retobject ( number );\n;
 
-Returns the object corresponding to the given number.
+Sometimes an object is hidden from the radar() and search() instructions (e.g. by proxyActivate=1). retobject() can be used to get any object - even the hidden ones. Here is how to get all objects:
+\c;
+\s; object result[];
+\s; for(int i = 0; retobject(i) != null; ++i)
+\s; {
+\s;     result[i] = retobject(i);
+\s; }
+\n;
 
 \t;number: \c;\l;int\u cbot\int;\n;
-Number of the object, between 0 and n. "n" represents the total number of objects in the scene. 
+Number of the object, between 0 and n. "n" represents the total number of objects in the scene.
+Note: two retobject() calls with the same number are only guaranteed to return the same object if no objects were created or destroyed between them.
 
 \t;Return value: \c;\l;object\u cbot\object;\n;
 Object corresponding to the number. The return value \c;\l;null\u cbot\null;\n; means that no object corresponds to this number, because the number was too high, and there are not so many objects in the scene. 

help/cbot/E/retobjectbyid.txt

@@ -0,0 +1,21 @@
+\b;Instruction \c;retobjectbyid\n;
+Syntax:
+\s;\c; retobjectbyid ( id );\n;
+
+If you know an id of an object, you can use retobjectbyid to get the object:
+\c;
+\s; object obj1 = ...;
+\s; int id = obj1.id;
+\s; object obj2 = retobjectbyid(id);  // Same as obj1
+\n;
+
+Unlike a variable of type \c;\l;object\u cbot\object;\n;, an id can be communicated via a \c;\l;file\u cbot\file;\n; or an \c;\l;ExchangePost\u object\exchange;.
+
+\t;id: \c;\l;int\u cbot\int;\n;
+The id of the object. The id of an object never changes. The ids of destroyed objects are not reused.
+
+\t;Return value: \c;\l;object\u cbot\object;\n;
+The object with the given id or \c;\l;null\u cbot\null;\n; if there is no such object.
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/generic/E/cbot.txt

@@ -41,7 +41,7 @@ Constants like \l;categories\u cbot\category; are displayed like that: \const;co
 \c;\l;motor\u cbot\motor;      \n;Direct motor control
 \c;\l;jet\u cbot\jet;        \n;Direct jet engine control
 \c;\l;message\u cbot\message;    \n;Displays a message
-\c;\l;retobject\u cbot\retobj;  \n;Returns an object from a function
+\c;\l;retobjectbyid\u cbot\retobjectbyid;  \n;Get an object by its id
 \c;\l;errmode\u cbot\errmode;    \n;Error treatement control
 \c;\l;abstime\u cbot\abstime;    \n;Returns the absolute time
 \c;\l;pendown\u cbot\pendown;    \n;Starts drawing

help/generic/E/cheats.txt

@@ -43,6 +43,7 @@ There are hidden commands in CBOT that are not even highlighted in the editor. T
 Numbers mean order of parameters.
 
 o \c;\l;produce\u cbot\produce;      \n;Immediately creates an object
+o \c;\l;retobject\u cbot\retobj;  \n;Can be used to get objects that are hidden from radar() and search()
 o \c;ipf          \n;Sets the number of instructions per frame, \c;1\n;: the number, default is \c;100\n;
 o \c;delete       \n;Damages the object, \c;1\n;: object's ID, \c;2\n;: magnifyDamage multiplier, without \c;2\n; the object explodes
 o \c;setbuild     \n;Sets buildings bitmask, \c;1\n;: new bitmask