Imperfect World Of Robots (IWOR) Manual

This is a complete reference to the IWOR project and how to use it. By reading this you should be able to write your own robots for IWOR.

IWOR simulate a virtual world which robots can live in it. Robots are physical objects in this world. All a gamer (programmer) should do is to design a brain for these little robots, and watch them moving around this imperfect world. In this article and other documents, the word robot will refer to this brain (programs that control physical robots) and not the physical robot itself.

1. Game Rules

This program will simulate a world which robots can live in it, work, defend their tribe against enemy, born new children, etc. Each robot belongs to a tribe. Robots should gather crystals for the tribe’s factory and defend it. In return factory will provide energy for them.

Each robot have a battery. By doing activities a certain amount of their battery will be consumed. They can charge their batteries by moving around the factory.

Each tribe have its own factory. Factory consume crystal in order to produce energy. The most important task of each robot is gathering crystal for the factory. Crystals can be found around the world. Robots can pick them up and drop them to the factory. By doing social activities, serving the tribe and helping each other, robots can survive longer in this imperfect and pitiless world.

1.1. Cloning

By serving the tribe, robots will gain honor. If a certain robot gain enough honor points, society will let her to have a new child.

Robots should send a valid key to the server in order to join the game. At the beginning of the game, there’s some zero keys in the game. The number of these keys can be set in the .config file, using ROBOTS_PER_TRIBE option. After consuming these keys, robots can gain new keys by sending CLONE command to the server (they must have enough honor point for doing this). Then they can pass these new keys to their kids (new processes), and those kids can use them to join the game.

In this way, only the robots who served the tribe can clone themselves and expand their generation.

1.2. Aging

Each robot have a certain life time. It can be set using ROBOT_LIFETIME in the .config file. By sending certain commands to the server (eg. MOVE, PICK, …) robot will lose life time.

One of the goals of these robots is to clone themselves before their time is over.

2. Using IWOR

IWOR use a client/server style for communication between robots and the server. Thus robots must run as separate programs. They can written in almost any language and/or different operating system. By using client/server style, robots can be run on different and separate machines on a local area or wide area network.

For using IWOR, first you need run server itself. Server will listen to the 7200 port (by default). So robots can connect to it using this port. The game will immediately start after first connection. Then clients can send commands to the server in order to control their robots. Also if you want to use a GUI, you must run it as a separate process too. GUIs can connect to the port 7250 (by default) and server will send world object to them each time something in world is changed.

If you download the package, there’s a bin directory which contain compiled files for running the game. If not, you have to compile it yourself. See README file for instruction of how to compile the IWOR.

By running iwor file, server will start and wait for the connection. After running the server, you can run a gui. There’s a default and simple one available, run gui file. Now everything is ready for connection of the robots.

If you want to test the commands without writing code, you can use telnet. Run telnet localhost 7200 and then type commands directly into it.

3. Commands

Commands are messages that clients send to the server in order to control their robots. These are simple string messages which tell server what they want their robots do. Commands are in a format like this:

command&arg1&arg2&...&argc&

Arguments of a command will be separated by &. Notice there’s a & at the end of the command. All of the commands must be in capital letters.

Commands are:

INIT&TribeNumber&Name&key&

Tell the server to add this robot to the TribeNumber tribe. This command should be send to the server right after the connection. Name can be any string, include empty space. for example INIT&1&sample&0& will add the robot to the first tribe and set its name to sample.

key is a code which server give to robot. Each robot need a legal key in order to join the game. At the beginning, there’s some zero keys. Number of these free keys can be set in the .config file. After consuming all of the free keys, robots have to gain honor points in order to obtain another key. By using these new keys, robot can clone herself in the world.

The robot will be put somewhere around the tribe factory. If there’s no empty space around it, robot will receive "190" (try again later) error code. In this case, robot should send her INIT command again.

MOVE&direction&

Move the robot to the direction. direction can be one of NORTH, SOUTH, EAST and WEST.

LOCATION&

Server will send the current location of the robot in the world, in response to this command. Location is in a format like i,j. i is the row, and j is the column of the location.

SENSE&

By this command, radar of the robot will activated and server will return objects around the robot in the world. Result is in the following format:

i1,j1,object1&i2,j2,object2& …

Where i1,j1 is the location of the first object, and object1 is the object in that location. Objects is separated with &.

Objects can be one of # (wall), C (crystal), R (robot), F (factory). R and F is follow by a number that show tribe number of that robot or factory.

For example, assume the following image:

Red circle is the robot itself, blue ones are other robots, and blacks are walls. Robot can sense green squares. By sending SENSE command, robot will receive: (current position of robot is 5,5)

PICK&direction&

By sending this command, robot will try to pick an object next to her. For example by sending PICK&WEST&, robot will try to pick an object on her left. If picking up was successful, server will return "255", if not, "130".

DROP&direction&

This command usually used to drop a crystal into a factory. Same as PICK, server will return "255" if drop was a success, and "140" if not. If robot haven’t anything to drop, if will receive "140".

ISHELD&

In response to this command, Server will send 250(Yes) if the robot held something in her hands, and 251(No) if not.

INFO&i&j

Robot can use this command for getting information of an object in (i,j) location. Server answer is in the following format:

object&id&tribe&

‘object’ can be WALL, ROBOT, and FACTORY. Obviously, there’s no ID or tribe number for WALL object. If there’s no object in specified location, server will return 211.

WORLDSIZE&

Server will return size of the world in i,j format by receiving this command.

HONOR&

In response to this command, server will send amount of honor the robot have.

LIFETIME&

By receiving this command, server will send amount of time the robot have before her death.

SEND&id&message&

By using this command, robots can send messages to each other. id is the ID of the robot that message should sent to. And obviously, message is the message to be send.

SHIELD&

TODO: Document this.

SHOOT&direction&

Fire a projectile towards the given direction. Projectiles have limited range.

CLONE&

TODO: Document this.

4. Server Messages

Server send various messages in response of robots requests. All of them are integer numbers. Here are a list of the server messages:

Code	Description
255	OK Last command is executed successfully.
250	Yes Will send in response to the yes/no commands. For example ISHELD.
251	No Will send in response to the yes/no commands. For example ISHELD.
210	There’s no object around the robot. This message will send in response of SENSE command. If there’s no object around the robot (robot sense nothing), server will send 210 to that robot.
211	There’s no object in that specific location. Usually will send in response to the INFO command.
220	Hit an enemy Robot just hit an enemy by his weapon. This will receive in response of `SHOOT` command.
221	Hit a friend Robot hit one of her team mates. This will receive in response of `SHOOT` command.
222	Hit factory A factory is hit by the robot. This will receive in response of `SHOOT` command.
223	Hit wall Robot hit a wall. This will receive in response of `SHOOT` command.
224	Hit a crystal A crystal has been hit by the robot. This will receive in response of ‘SHOOT’ command.
229	Hit nothing Nothing was in the way of the bullet that shoot by the robot. This will receive in response of ‘SHOOT’ command.
100	Robot is dead. Receiving this message means the robot is dead. Right after this message, connection of the robot will be closed.
110	Invalid Command The command was in invalid format.
112	Illegal clone key. Robot sent an illegal clone key.
120	Can’t move in that direction. It will happen either if the destination is not empty, or robot can’t move for some reason.
130	Can’t pick up object. Robot can’t pick up that object. This will send if there’s no object around the robot, or that object can’t picked up (for example a wall).
140	Can’t drop object Usually will send if the robot try to drop object into a wall, or something like that.
150	Not enough honor point Robot dosen’t gain enough honor point for cloning. This usually send in response to the ‘CLONE’ command.
160	There’s no such robot. The specified ID dosen’t exist. Usually this will send in response of the ‘SEND’ command.
190	Try again later. This message mostly send in response to the INIT command. Sometime there’s no empty space around the tribe factory to put this robot into. Robot should send the INIT message again.
199	unknown error If any unhandable error occurred, server will send 199. Usually it happen when a robot wants to move but she died before. Or situations like that.

5. Configuration

Server will read settings and options of the game from a .config file. Its an ordinary text file, which contain values of game’s options. By default, server search for iwor.config in the current directory. You can specify another config file by passing its name using -c option to the server. Things like battery consumption of robots, amount of energy a factory generate per crystal, and so on, can be customized.

Some important options are described below.

ROBOTS_PER_TRIBE: At the beginning of the game there are some zero keys which allow limited number of robots join the game. This option define the number of these zero keys.
HONOR_FOR_CLONING: The amount of honor a specific robot needs to gain before clone herself.
ROBOT_LIFETIME: Each robot can do a certain number of actions before she dies, which is termed life time. By using this option, life time can be set.

6. World Construction

Worlds are describe as a text file, server can read these files and construct the simulated world. You can build your own world for IWOR. This section describe format of these world files. Assume the following little world:

9
15
###############
#000000000000##
#010000000c000#
#000000#000000#
#00000###00000#
#0000000000000#
#000c000000020#
#0000000##0000#
###############

The first two lines are the size of the world. Other lines show objects in the world. Zeroes are empty spaces, numbers are location of factories (1 for the first tribe’s factory, 2 for the second one, and so on), # is a wall, and c is a crystal. Easy, isn’t it?

7. Copyright

You are free to redistribute and/or modify this document under the terms of the GNU Free Documentation License. A copy of this license can be found on the FDL file along with this document.