TABLE OF CONTENTS

  1. WHAT IS TCLROBOTS?
  2. INSTALLATION AND DEMO
  3. SYNOPSIS
  4. THE ROBOT
  5. THE BATTLEFIELD
  6. THE ROBOT TCL LANGUAGE
  7. THE ROBOT HARDWARE INTERFACES
    7.1. Basic syscalls
      7.1.1 scanner
      7.1.2 dsp
      7.1.3 alert
      7.1.4 cannon
      7.1.5 health
      7.1.6 drive
      7.1.7 speed
      7.1.8 heat
      7.1.9 loc_x
      7.1.10 loc_y
      7.1.11 tick
    7.2. Team syscalls
      7.2.1 team_declare
      7.2.2 team_send
      7.2.3 team_get
    7.3. Convenience syscalls
      7.3.1 dputs
      7.3.2 rand
      7.3.2 callback


1. WHAT IS TCLROBOTS?

TclRobots is a programming game where you write a Tcl program to control
a robot. The robot's mission is to survive a battle with other robots.

At least two robots compete during a battle, each running different
programs (or possibly the same program in different robots). Each robot
is equipped with a scanner, cannon, drive mechanism. A single match
continues until one robot is left running. Robots may compete
individually, or combine in a team oriented battle. A tournament can be
run with any number of robot programs, each robot playing every other in
a round-robin fashion, one-on-one.

A battle simulator is available to help debug robot programs.

The TclRobots program provides a physical environment, imposing certain
game parameters to which all robots must adhere. TclRobots also provides
a view on a battle, and a controlling user interface.

TclRobots require Tcl 8.6 since it uses coroutines.

TclRobots is licensed under the Simplified BSD license. See LICENSE for
information.


2. INSTALLATION AND DEMO

Download the game and sample robots from tclrobots.org.

Run "tclrobots" (Linux/Mac) or "tclrobots.exe" (Windows) depending on operating system.

In the Files listbox, Double-Click on the "samples" directory
for sample robot programs.

Click on "Select All"

Click on "Run Battle"


3. SYNOPSIS

tclrobots

Tclrobots without any command line arguments starts TclRobots in
interactive mode. The user interface (described below) is used to
select files, start battles, tournaments, or the simulator.

If command line arguments are specified, tclrobots starts in
tournament or single battle mode using the specified files.

Command-line arguments (in any order):

--debug    : Enable debug messages and lowered health for quicker battles.
--gui      : Use GUI; useful in combination with robot files.
--help     : Show this help.
--msg      : Disable robot messages.
--n [N]    : Run N number of battles.
--o [FILE] : Set results output file.
--seed [S] : Start with random seed S to replay a specific battle.
--t*       : Run tournament in batch mode.
--version  : Show version and exit.
[robot.tr] : Add one ore more robot files.


4. THE ROBOT

All robots in TclRobots are constructed equally. What differentiates the
robots' behavior is the control program that you write. The robot has
the ability to move, look for, and shoot at, other robots.

Robots use a compass system based on 0 to 359 degrees, with 0 pointing
due east, 90 due north, 180 due west, and 270 due south.

The robot's drive mechanism can be controlled to move the robot in a
particular direction, at some speed. Direction is expressed as an
integer degree heading 0 - 359, and speed is 0 to 100 percent. The motor
is inefficient above 35% speed, and begins to overheat. When a
temperature heat index of 200 is reached, the motor cannot be operated
over 35% until cooling allows the heat index to drop back to 0. While
the robot is very agile and stable, safeguards are built into the
interface to prevent the robot from tipping over while trying to turn at
too fast a rate for any given speed.

The following table represents maximum speeds at which a delta course
change can be made:

   Degrees of     Maximum Speed
   course change
   ____________________________
   25 or less         100%
   25 - 50             50%
   50 - 75             30%
   75 or greater       20%

If a course change is attempted at a speed above the maximum for the
change, the drive is disengaged (speed set to 0) on the present
course. The drive mechanism also allows the robot to turn faster at
slower speeds.

   Speed         Rate of turn
   ____________________________
   25% or less       90
   25 - 50%          60
   50 - 75%          40
   75% or greater    30

At 100% speed, the robot travels at 20 meters per second. Robots are
also subject to acceleration and deaccelearation, a linear constant of
20% of the maximun speed per second.

Each robot is equipped with a scanning device, which can be pointed
independently of the current drive heading of the robot. A scan can be
initiated in any direction, 0-359 degrees. The scanner has a variable
resolution capability, detecting other robots within a maximum of +/- 10
degrees from the scan direction. If a scan finds a robot, the distance
to the opposing robot is reported. However, if a resolution greater than
0 is used, the scanner's result may be reported inaccurately. In this
case, the distance reported may be off by as much as 10 meters for each
degree of resolution (up to 100 meters in error for a +/- 10 degree
resolution scan.) A high resolution scan (0 specified for resolution)
will return accurate results, subject to cannon barrel heat distortion
(see below).

If two or more robots are in the scan's resolution, the closest opponent
is reported. It's also possible to distinguish various opposing robots,
as the scanner has a rudimentary digital signal processor, and each
robot has a arbitrary signature. A robot program can also be alerted
when it is the subject of a scan by another robot. The signature of the
scanning robot can be determined, but not it's heading or distance.

A cannon is the robot's offensive weapon, firing a shell at opposing
robots. The cannon has a maximum range of 700 meters, and can be aimed
independently of the robot heading. Damage to all surrounding robots
from an exploding shell is assessed as follows:

   Meters from   % Damage
    explosion    incurred
   ______________________
        6          25%
       10          12%
       20           7%
       40           3%

While the robot has an large (unlimited) cache of shells available, it
can only reload fast enough to have one shell in the air at maximum
range at any one time (approximately 4 seconds). Cannon shells are
grouped four to a clip; after a clip is exhausted, it is ejected and a
new clip loaded in place. The effect is that on every fourth shell, the
reload time is tripled (12 seconds.) The cannon fires its shells in a
high arc; a shell will not impact into another robot that might be in
the line of flight. Shells travel at 200 meters per second toward the
target.

Each shell fired causes the cannon barrel to heat up. The heat rising
off the barrel distorts the view of the scanner. If the temperature of
the barrel becomes too great, the scanner is rendered useless. At lesser
temperatures, the heat distortion will cause the scanner to return
inaccurate results, a random plus or minus meters equal to the total
heat of the barrel (one unit of barrel heat = one meter error.) Firing a
shell causes the barrel temperature to increase by 20 heat units. The
normal cooling rate is 2 units per second. The scanner always reports 0
for range while the barrel temperature is above 35 units. The scanning
beam, however, still registers upon other robots in the path of the
scan, triggering a scanned robot's alert procedure. The cannon barrel
does not have temperature sensor.

Various feedback registers in the robot can be accessed by the control
program, reporting the current amount of damage, x and y axis
battlefield location, current speed, and an internal clock tick.

Robots have health expressed as a percent value. Health starts at 100%
and decreases with damage. When 0% health is reached, the robot is
"dead", and ceases to function. However, damage has no effect on
operational ability. A robot with 1% health operates as well as one with
no damage.


5. THE BATTLEFIELD

The battlefield in TclRobots is a 1,000 by 1,000 meter square area.
Walls surround the battlefield, and robots running into a wall will
suffer 5% damage. The coordinate system is based on increasing x and y
axis values from the southwest corner: bottom left is (0,0) and
(999,999) is the northeast (upper right).

Upon start up, robots are placed in random quadrants.


6. THE ROBOT TCL LANGUAGE

Robot control programs are written in the Tcl language. The robot
programs are run in separate safe interpreters.

The following Tcl commands are available:

   after    append    apply    array
   binary   break     catch    chan
   clock    close     concat   continue
   dict     eof       error    eval
   expr     fblocked  fcopy    fileevent
   flush    for       foreach  format
   gets     global    if       incr
   info     interp    join     lappend
   lassign  lindex    linsert  list
   llength  lrange    lrepeat  lreplace
   lsearch  lset      lsort    namespace
   package  pid       proc     puts
   read     regexp    regsub   rename
   return   scan      seek     set
   split    string    subst    switch
   tell     time      trace    unset
   update   uplevel   upvar    variable
   vwait    while

The following Tcl commands are not available:

   cd          encoding  exec    exit
   fconfigure  file      glob    load
   open        pwd       socket  source
   unload



7. THE ROBOT HARDWARE INTERFACES

The following Tcl commands are the interface to the robot's hardware;
the syscalls. Each interface command takes 1 clock tick to complete,
except the scanner command, which requires 2 clock ticks per execution,
and team communication commands team_get and team_send execute without
delay. Commands that take arguments will return -1 if any argument is
out of valid ranges. For degrees, valid values are 0-359; for speed,
0-100, for resolution, 0-10, for cannon range, 0-700.


7.1 Basic syscalls

7.1.1 scanner

NAME

scanner - Find other robots by scanning the battlefield

SYNOPSIS

scanner degree resolution

DESCRIPTION

The scanner command invokes the robot's scanner. Degree must be in the
range 0-359. Scanner returns 0 if nothing found, or an integer greater
than zero indicating the distance to an opponent. Resolution controls
how wide in degrees the scan can detect opponents from the absolute
scanning direction, and must be in the range 0-10. A robot that has been
destroyed is not reported by the scanner.

Cost: 2 ticks.


7.1.2 dsp

NAME

dsp - Get information on last scanned robot

SYNOPSIS

dsp

DESCRIPTION

The dsp command returns a list of two integers, the first element is the
digital signature of the last robot found using the scanner. The second
element is the percent of health the scanned robot has remaining, 1-100
percent. Each robot in a battle has a distinct signature. If nothing was
found during the last scan (scanner command returned 0), then the dsp
command will return "0 0".

Cost: 1 tick.


7.1.3 alert

NAME

alert - React on being scanned

SYNOPSIS

alert proc-name

DESCRIPTION

The alert command names a procedure to be called when the robot is being
scanned by another robot. When the robot detects it has been scanned,
the proc-name procedure is called with one argument, the dsp signature
of the robot that performed the scan. If proc-name is null (""), then
the alert feature is disabled.

Cost: 1 tick.


7.1.4 cannon

NAME

cannon - Fire the offensive weapon

SYNOPSIS

cannon degree range

DESCRIPTION

The cannon commands fires a shell in the direction specified by degree,
for the distance range. Cannon returns 1 if a shell was fired; if the
cannon is reloading, 0 is returned.

Cost: 1 tick.


7.1.5 health

NAME

health - Get information on current health

SYNOPSIS

health

DESCRIPTION

The health command returns the current health, 1-100 percent.

Cost: 1 tick.


7.1.6 drive

NAME

drive - Move the robot on the battlefield

SYNOPSIS


drive degree speed

DESCRIPTION

The drive command starts the robot's drive mechanism. Degree must be in
the range 0-359. Speed must be in the range 0-100. Any change in course
that falls outside the "Degrees of course change" table (see "The
Robot", above) will cause the robot's speed to be set to 0 along the
current course. A speed of 0 causes the robot to coast to a stop. The
drive command returns the speed set. If the drive is currently
overheated, the maximum speed during overheating (35%) will be set.

Cost: 1 tick.


7.1.7 speed

NAME

speed - Get information the the current speed

SYNOPSIS

speed

DESCRIPTION

The speed command reports the current speed of the robot, 0-100. Speed
may return more or less than what was last set with the drive command
because of acceleration/deaccelearation, drive overheating, or collision
into a wall.

Cost: 1 tick.


7.1.8 heat

NAME

heat - Get information on current motor heat

SYNOPSIS

heat

DESCRIPTION

The heat command returns a list of two integers, the first element is
the overheating flag, 1 if the maximum motor heat value was attained,
otherwise 0. The second element is the current motor heat index,
0-200.

Cost: 1 tick.


7.1.9 loc_x

NAME

loc_x - Get information on current position on X axis

SYNOPSIS

loc_x

DESCRIPTION

The loc_x command returns the current x axis location of the robot,
0-999 meters.

Cost: 1 tick.


7.1.10 loc_y

NAME

loc_y - Get information on current position on Y axis

SYNOPSIS

loc_y

DESCRIPTION

The loc_y command returns the current y axis location of the robot,
0-999 meters.

Cost: 1 tick.


7.1.11 tick

NAME

tick - Get information on the current clock tick

SYNOPSIS

tick

DESCRIPTION

The tick command returns the current clock tick of the battle. The clock
tick is set to 0 at game startup.

Cost: 1 tick.


7.2 Team syscalls

7.2.1 team_declare

NAME

team_declare - Join a team of robots

SYNOPSIS

team_declare teamname

DESCRIPTION

The team_declare command sets the team alliance to the teamname
argument. team_declare is only effective the first time it is executed
in a robot control program. team_declare returns the teamname value.

Cost: 1 tick.


7.2.2 team_send

NAME

team_send - Send a message to all team mates

SYNOPSIS

team_send data

DESCRIPTION

The team_send command makes the argument available to all other robots
with the same teamname. Data is a single string argument, and can be any
value or list. If a team has not been declared with the team_declare
command, the team_send command has no effect.

Cost: 0 ticks.


7.2.3 team_get

NAME

team_get - Get messages from all team mates

SYNOPSIS


team_get

DESCRIPTION

The team_get command returns a list of team members and their current
data values. Each element of the list returned is a list of the digital
signature of a team member and that robot's last team_send data
value. If a team has not been declared with team_declare or all of the
other members of the team have not declared a team or are dead, the
return value is an null list. The robot executing the team_get command
is also excluded from the return list.

Cost: 0 ticks.


7.3 Convenience syscalls

7.3.1 dputs

NAME


dputs - Print a message

SYNOPSIS


dputs args

DESCRIPTION

The dputs command prints a message in the GUI message window. Dputs
accepts any number of arguments.

Cost: 0 ticks.


7.3.2 rand

NAME

rand - Generate a random number

SYNOPSIS

rand max

DESCRIPTION

The rand command uses the Tcl mathfunc rand to generate a random integer
between 0 and (max - 1). The seed value is randomly set at game
startup. The seed value is reported at battle end to enable the
possibility to re-run battles.

Note that since Tcl mathfunc rand is not cryptographically secure you
better not let your TclRobot select your passwords.

Cost: 0 ticks.


7.3.3 callback

NAME

callback - Schedule actions for later ticks

SYNOPSIS

callback time script

DESCRIPTION


Cost: 0 ticks.