Welcome to GNU Robots

Introduction

To make the program easier to design and implement, I have decided to let the robot program be written in a text file, so that advanced programmers don't have to limit themselves to a visual programming interface. The language will be Scheme, which provides for flexibility in writing your programs. For non-programmers, there will also be a visual programming interface, which will generate Scheme code.

GNU Robots will use GNU Guile as the language back-end (Scheme handler). This will make the GNU Robots game engine more consistent with other GNU projects, as it will use the same extension language.

The GNU Robots playing field will be one large matrix of spaces, which can be filled with a food item (increases energy), prizes (to increase your score), walls (which you can bump into), and baddies (which can inflict damage.)

Release plans

The following are the features that are planned for future releases of GNU Robots:

Version 1.0

1. use GNU Autoconf, so your Makefile(s) will be created for you, just like other GNU programs.
2. Add error checking when reading map file
3. Check that the Scheme file exists before passing to Guile
4. Will include any maps or robot programs that are submitted to me. These will be used as examples for others to learn from.
5. Add some way for the user to check on the shields level and energy level, so the robot can somehow respond to these conditions.

Version 2.0

1. Network game support, so that more than one player's robot can navigate the same map at the same time. This will probably be accomplished by setting up a map server, which all instances of GNU Robots will query when moving the robot.

Building GNU Robots

To build GNU Robots, you first need to have already compiled/installed the GNU Guile libraries. GNU Robots was built using Guile 1.2.

Then, just make sure the root Makefile is okay for your system (check that CC is correct for your system, and that the Makefile matches where you have installed the Guile libraries), and type:

  make

In future, I will use GNU Autoconf, so your Makefile(s) will be created for you, just like other GNU programs.

This will create these programs in the src/ directory:

Program	What it does
robots	a curses-based version of the game
xrobots	an X Windows version of the game
robots_logfile	a version that generates a log file

The robots program is a curses-based version of the game, using an ASCII approximation of the game elements. Your robot will appear as a v when it points South, ^ when it points North, and < and > for West and East. Empty spaces are shown as ., walls as #, baddies as @, and food and prizes as + and $.

The sample map that is provided as mapfile.map is just a single room, with prizes all along the four walls. The sample robot program test.scm knows how to pick up all these prizes and then quit. Other map files can be found in the src/maps directory, and other robot programs will be distributed in the scheme directory.

Running GNU Robots

The usage for robots, xrobots, robots_logfile is as follows:

  Usage: robots [OPTION]... [FILE]
  GNU Robots - game/diversion where you construct a program for a
  little robot, then watch him explore a world.
  
    -f, --map-file=FILE    load this map file
    -V, --version          output version information and exit
    -h, --help             display this help and exit

Program Code Summary

This section is intended for anyone making changes to GNU Robots

This is a summary of how the GNU Robots program is using GNU Guile. This is meant to be an overview of the Robots program, to provide a framework for understanding the program. Not that GNU Robots is a terribly difficult program to understand. But if you haven't used GNU Guile in a program before, you may have trouble figuring GNU Robots out. Here's what's happening:

1. GNU Robots starts the Guile back-end with a call to gh_enter(), like so:

     gh_enter(argc, argv, main_prog);
   

2. The main_prog() is a function that takes over control of the GNU Robots program after Guile has been started. Note that gh_enter() does not exit.

3. Defines some new Scheme primitives, using gh_new_procedure(), so that the new primitive actually calls a compiled C function. For example:

     gh_new_procedure1_0("robot-feel", robot_feel);
     gh_new_procedure1_0("robot-look", robot_look);
     gh_new_procedure0_0("robot-grab", robot_grab);
     gh_new_procedure0_0("robot-zap", robot_zap);
   

   
   In the above, robot_feel() is a compiled C function, and robot-feel is the new Scheme procedure that calls it.

4. Loads the game map, and initializes the game elements. The robot is placed at 1,1 facing East.

5. Initializes the user interface (for example, UNIX Curses) and then draws the map.

6. Tells Guile to execute a Scheme program, using a call to gh_eval_file().

7. When the Scheme program exits, the robot is assumed to be dead, or the program may have called exit or quit. Either way, we end the game.

8. Closes down the user interface.

9. Frees memory associated with the game map.

10. Prints the statistics (shields, energy, score) and exits.

Robot Actions

Actions

The language will allow the following robot actions. You can also look at some robot examples to see how to use the robot actions. Note that every robot action will drain your robot of some energy.

Since the robot will be implemented using Guile, you write the rest of your program in Scheme, which allows you to create a really intricate robot program.

robot-look thing
The robot will look ahead across empty spaces for a specific thing. If the thing was found, the true/false flag is True.

robot-feel thing
The robot will feel ahead exactly 1 space for a thing. If the thing was found, the true/false flag is True.

robot-smell thing
The robot will smell the surrounding 8 spaces for a thing. If the thing is found, the true/false flag is True.

robot-move n
The robot will move n spaces forwards (positive n) or backwards (negative n). If the robot was able to move without bumping into something, then the true/false flag is True.

robot-turn n
The robot turns n increments of 90-degrees to the right (positive n) or to the left (negative n). Always True.

robot-zap
The robot shoots its little gun, to zap whatever is exactly one space ahead of it. Always True. This action consumes a lot of energy.

robot-grab
The robot grabs (and consumes, if food) whatever is exactly one space ahead of it. Always True, even if there was nothing to take.

Things

The following are things that can be tested for in the above actions:

wall
A piece of a wall. You can't zap these.

prize
An item that increases your score. Be careful not to zap these!

food
An item that adds to your robot energy. You can zap these if you aren't careful.

baddie
A creature that can harm your robot. You can zap these to get them out of your way.

space
An empty space.

Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also other ways to contact the FSF.

Please send comments on these web pages to jhall1@isd.net, send other questions to gnu@gnu.org.

Copyright (C) 1998 Jim Hall

Verbatim copying and distribution is permitted in any medium, provided this notice is preserved.

Updated: 16 Aug 1998 jhall