


TclRobots(6)                 Tcl/Tk                  TclRobots(6)



NAME
                              TclRobots

                             Version 2.0
                  Copyright 1994,1996 Tom Poindexter
                           tpoindex@nyx.net

WHAT IS TCLROBOTS?
     TclRobots is a programming game, similar to 'Core  War'.  To
     play TclRobots, you must write a Tcl program that controls a
     robot.  The robot's mission is  to  survive  a  battle  with
     other  robots.   Two, three, or four 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 con-
     tinues  until  one robot is left running. Robots may compete
     individually, or combine in a team oriented battle.  A tour-
     nament  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 is strongly influenced by my 1985  game,  CROBOTS.
     CROBOTS is based on writing robot control programs in C, and
     the entire environment is tightly coupled into a single pro-
     gram  that  contains a small C compiler, virtual stack-based
     CPU, multi-tasking  scheduler,  and  execution  environment.
     TclRobots instead is loosely coupled, utilizing separate Tcl
     wish interpreters for each robot.  Communication  between  a
     robot  and  the  TclRobots program is accomplished with Tk's
     send command.

     TclRobots requirements:  a wish interpreter built  from  Tcl
     7.4 and Tk 4.0.

     TclRobots uses the Tk "send" command - if your X  server  is
     insecure (xhost access list not empty), you will need a wish
     compiled with the "-DNO_TK_SECURITY" flag.  Better yet,  use
     "xauth" instead of "xhost."

     Availability:
     TclRobots (and Tcl/Tk, if you don't  already  have  it)  are
     available at the following locations:

     ftp://ftp.aud.alcatel.com/tcl/code/tclrobots-2.0.tar.gz
     ftp://ftp.smli.com/pub/tcl/tcl7.4.tar.Z
     ftp://ftp.smli.com/pub/tcl/tk4.0.tar.Z



SunOS 5.4              Last change: 2/1/96                      1






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



INSTALLATION AND DEMO
     -    Edit the Makefile.  All that is needed it the  path  of
          your wish executable, and the directory where you would
          like TclRobots installed. See the comments at  the  top
          of the Makefile.  `make' to install.

     -    run `tclrobots' from the directory where  you  unpacked
          the distribution.

     -    In the Files listbox,  Double-Click  on  the  `samples'
          directory  for  sample individual robot programs or the
          `teams' directory for 2-on-2 team robot programs.

     -    Click on `Select All'

     -    Click on `Run Battle'

SYNOPSIS
     tclrobots [ [ -t timelimit ]  [ -o results-file ]  [  -nowin
     ]   files... ]

     Tclrobots without any command line arguments  starts  TclRo-
     bots  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.
     Options:

     -t  timelimit
          sets the number of minutes to run each match in a  one-
          on-one  tournament. Timelimit should be specified as an
          integer number of minutes.  If -t is not  specified,  a
          single  battle will run with the first four files until
          a single winner remains.

     -o  results-file
          specifies the file name in which to  record  tournament
          results.  If -o is omitted, the file name "results.out"
          is used.

     -nowin
          specifies that the tournament or battles  will  not  be
          displayed.   In  addition,  matches  are run five times
          faster (wall clock time).  The apparent clock  time  to
          robot  programs  will  still  be  determined  by the -t
          timelimit values.  -nowin can be specified without  -t,
          resulting  in  a  regular 2-4 way battle without a time
          limit and run without display.  Results will  be  saved
          in "results.out" or the file specified with -o.




SunOS 5.4              Last change: 2/1/96                      2






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



THE ROBOT
     All robots in TclRobots are constructed equally.  What  dif-
     ferentiates 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
     course change    Speed
     _______________________
      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 more        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



SunOS 5.4              Last change: 2/1/96                      3






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



     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 dis-
     tance to the opposing robot is reported. However, if a reso-
     lution  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 reso-
     lution (up to 100 meters in error for a +/- 10 degree  reso-
     lution scan.)  A high resolution scan (0 specified for reso-
     lution) will return accurate results, subject to cannon bar-
     rel 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 distin-
     guish various opposing robots, as the scanner has a rudimen-
     tary  digital  signal  processor, and each robot has a arbi-
     trary 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  head-
     ing 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



SunOS 5.4              Last change: 2/1/96                      4





TclRobots(6)                 Tcl/Tk                  TclRobots(6)



     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  scan-
     ning beam, however, still registers upon other robots in the
     path of the scan, triggering a scanned  robot's  alert  pro-
     cedure.  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 incur damage expressed as a percent value.  When 100%
     damage  is reached, the robot is "dead", and ceases to func-
     tion.  However, damage has no effect on operational ability.
     A robot with 99% damage operates as well as one with no dam-
     age.

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).   999,999  is  the
     extreme northeast (upper right).

     Upon start up, robots are placed in random quadrants.

THE ROBOT TCL LANGUAGE
     Robot control programs are written in the Tcl language.  The
     following Tcl commands are available:

     after      if         rename
     append     incr       return
     array      join       scan
     break      lappend    set
     case       lindex     source
     catch      linsert    split
     concat     list       string
     continue   llength    subst
     error      lrange     switch
     eval       lreplace   time
     exit       lsearch    trace
     expr       lsort      unset
     file       pid        update
     for        proc       uplevel
     foreach    rand       upvar
     format     regexp     while
     global     regsub





SunOS 5.4              Last change: 2/1/96                      5






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



     Note that the after and update commands from Tk  are  avail-
     able.  See the Tcl and Tk man pages for information on these
     commands.

THE ROBOT HARDWARE INTERFACES
     The following Tcl commands are the interface to the  robot's
     hardware (syscalls.)  Each interface command takes a minimum
     of 100 milliseconds to complete, except:  the  scanner  com-
     mand,  which  requires  200 milliseconds per execution; team
     communications  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.

     scanner degree resolution
          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 indi-
          cating  the  distance  to an opponent.  Resolution con-
          trols 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.

     dsp
          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  damage  the scanned robot has accumu-
          lated, 0-99 percent.  Each robot in a battle has a dis-
          tinct  signature.  If nothing was found during the last
          scan (scanner command returned 0), then the dsp command
          will return "0 0".

     alert proc-name
          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  pro-
          cedure  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.

     cannon degree range
          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.

     damage
          The damage command reports the current percent of  dam-
          age  suffered  by the robot, 0-99.  At 100% damage, the



SunOS 5.4              Last change: 2/1/96                      6






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



          robot is "dead", and as such, the control program is no
          longer running.

     drive degree speed
          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  out-
          side  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.

     speed
          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.

     heat
          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.

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

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

     tick
          The tick command returns the current robot clock  tick,
          which  has  a 500 millisecond resolution.  The clock is
          set to 0 upon robot startup.

     team_declare teamname
          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.

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



SunOS 5.4              Last change: 2/1/96                      7






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



     team_get
          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.

     Convenience commands

     The following Tcl commands are available to the  robot  con-
     trol program.  As such, they execute immediately without the
     100 millisecond interface time.

     dputs args
          The dputs command  prints  a  message  on  the  robot's
          status window.  Dputs accepts any number of arguments.

     rand max
          The rand command is a simple random  number  generator,
          based  on  Knuth's algorithm.  The rand command returns
          an integer between 0 and ( max - 1), where  max  is  in
          the  range 1 to 65535.  The seed value is randomly set;
          if a particular seed value is desired, the global vari-
          able _lastvalue should be set to some starting value.

WRITING ROBOT CONTROL PROGRAMS
     Several internal variables and procedures are loaded into  a
     robot  before  loading  the robot control program.  Reserved
     variables and commands begin with and underscore "_" or  dot
     ".".   Do  not  use variables or procedures in robot control
     program that begin with either symbol.

     Robot control programs may  set  variables  or  define  pro-
     cedures  as  required.   Robot control programs should never
     exit, as they will not be restarted by TclRobots.  Thus, the
     main  processing should be enclosed in an endless loop, e.g.
     "while 1 { ... }"

     Most standard Tcl commands are available  to  robot  control
     programs.   Notable  Tcl commands that are missing: all file
     I/O ( gets, puts, open, close, etc.), exec,  info,  standard
     Tcl library procs ( auto_load, unknown, tkerror etc.)

     In addition, most standard Tk commands are also missing.  Tk
     commands  that are available are after and update. Each sys-
     call implicitly performs the update command, or the program-
     mer  can  execute  it  any  time  to  ensure  that  commands
     scheduled with after are run.



SunOS 5.4              Last change: 2/1/96                      8






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



     Any "unknown" procedure, or "tkerror" situation is  reported
     in the robot's status window, and the robot program may ter-
     minate.

     Robot control programs may also examine (but  not  set)  the
     global  variable  _debug  to cause debugging code to be exe-
     cuted during battle simulation. _debug is set to 1  if  run-
     ning  in  the  simulator, 0 otherwise.  (see "The Simulator"
     below.)

     If the alert command is used,  the  procedure  it  specifies
     should exist, and take one argument, e.g.

          proc I_Was_Scanned {who} {
            dputs $who scanned me!
          }
          alert I_Was_Scanned

     Any valid filename can be used for a robot control  program;
     a suffix of .tr is recommended to indicate a TclRobots file.

     Teams  of  robots  may  compete   by   using   team_declare,
     team_send,  and  team_get commands.  Each robot control pro-
     gram that is part of a team should declare its team alliance
     by using the team_declare command near the start of its pro-
     gram.  The teams may then communicate by using team_send and
     team_get.   The robot control programs for team members need
     not be the same.

     Team communication uses a passive model.  A member of a team
     may  post  a data item at any time.  When other team members
     execute a team_get command, the other team member's  digital
     signature  and  last  posted  data  item are returned.  Data
     exchanged and protocol between team members  are  completely
     arbritrary,  allowing each team to interpret data.  Possible
     examples might the  signature  and  location  of  an  enemy,
     current location, pleas for help, etc.

     Nothing prevents fratricide among team members.   Since  the
     digital  signature  of a scanned target is available, robots
     should check their list of team members to  avoid  "friendly
     fire."

THE TCLROBOTS USER INTERFACE
     TclRobots has a user interface to  start  battles,  run  the
     simulator,  commence  a tournament, and view battles in pro-
     gress.  Upon startup, TclRobots displays a bar of five  but-
     tons, and two listboxes.  The buttons are:

     -    Run Battle - runs a battle with selected robots

     -    Simulator.. - starts the simulator dialog



SunOS 5.4              Last change: 2/1/96                      9






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



     -    Tournament.. - starts the tournament controller

     -    About.. - a small  about  box  with  TclRobots  version
          number

     -    Quit - immediately exits TclRobots

     The two listboxes are a file section box (left side), and  a
     list of selected robot files (right side).

     The file section box presents  a  list  of  directories  and
     files in the current directory.  Double-clicking on a direc-
     tory changes to that directory. Double-clicking  on  a  file
     chooses that file to be run in a battle, simulator, or tour-
     nament.  A file filter entry is presented at the top of  the
     file  selection  box and may be used to filter the selection
     by entering a pattern and pressing "Filter".  At the  bottom
     of  the file selection list is a file selection.  Entering a
     file and pressing "Select"  will  enter  that  file  in  the
     "Robot  Files  Selected"  list.   The button labeled "Select
     All" will select all files in the file selection box to  the
     Robot Files Selected list.

     Robot files should be selected before pressing "Run Battle",
     "Simulator..",  or  "Tournament..".  To run a single battle,
     select two to four robot files from the file selection list.
     A  single  file  may  be  selected  more than once; separate
     robots will be loaded with the same file.  If  the  "Simula-
     tor.."  button is pressed, the first file in the Robot Files
     Selected list will be used for the Simulator.  If the "Tour-
     nament.."  button  is  pressed, all files in the Robot Files
     Selected list will be run in  a  tournament  fashion.  In  a
     tournament, duplicate files will be removed from the list.

     The Robot Files Selected listbox has two buttons,  "Remove",
     and  "Remove  All".  Selecting a file by single clicking and
     pressing the Remove button will remove that  file  from  the
     list.   The Remove All button will remove all files from the
     Robot Files Selected list.

     Robot files selected are not verified;  if a file other than
     a  TclRobots  robot control program is selected, results are
     unpredictable.

     When "Run Battle" is pressed, TclRobots  will  spawn  a  new
     wish  interpreter, position it to the right of the main win-
     dow, and load it with  a  selected  robot  control  program.
     After  all  robot  wish  interpreters  are spawned, the file
     selection frame is replaced with a view on  the  battlefield
     and  the  battle  will  commence.   Each robot is assigned a
     specific color, and is represented on the battlefield  by  a
     unique  arrow  shape of that color.  When a robot issues the



SunOS 5.4              Last change: 2/1/96                     10






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



     scanner command, the scan is represented by an arc emanating
     from  the  robot.  The arc represents the scan direction and
     resolution  width.   The  end  of  the  arc  represents  the
     cannon's maximum range (the scanner's range is not limited.)

     Shells fired by a robot are represented  by  a  small  black
     dot.   The  robot's  current  damage  status is shown in the
     robot's status window, just to the right of the  robot  pro-
     gram file name.

     During a battle, the "Run Battle"  button  is  replaced,  by
     "Halt".   If  pressed, the current battle is halted, and the
     spawned robot interpreters exit.  The "Halt" button is  then
     replaced  with  "Reset",  which removes the battlefield, and
     presents the file selection frame.

     Individual wish interpreters for the robots contain a  list-
     box  and  scrollbars, which displays output from the "dputs"
     command.  The robot's title bar title is set to the  program
     file  name,  appended  with  the assigned digital signature.
     The robot's cummulative amount of damage is shown as a  per-
     centage, just to the right of the robot's filename.

THE SIMULATOR
     The "Simulator.." button starts  the  simulator,  using  the
     first  entry  in the Robot Files Selected list.  A simulator
     control window appears, and a target robot is placed in  the
     middle of the battlefield (500,500).

     The Simulator allows a robot program to be  examined  during
     robot  execution,  revealing important information about the
     robot.  A robot control program can be set to stop  on  each
     "syscall"  (any  of  the robot hardware interface commands.)
     While the robot program is paused, the simulator  can  query
     or set global variables in the robot control program.

     The Simulator has its control buttons  at  the  top  of  the
     Simulator window.  A checkbutton "Step syscalls" toggles the
     single step action of the robot control program.  The button
     "Single  Step"  will also set the Step Syscalls checkbutton,
     or allow the robot control program to run to the  next  sys-
     call if already in Step Syscalls.  The button "5% Hit" simu-
     lates the robot incurring damage. The  button  "Scan"  simu-
     lates  the  robot being scanned by the target.  The target's
     dsp signature is "1".  The button "Close"  will  remove  the
     simulator and the spawned robot wish interpreter, and return
     to the file selection listbox frame.

     When the "Step Syscalls" button is in the "off"  state,  the
     robot executes its code in real time.  During "Single Step",
     execution is paused at the next syscall and one motion  time
     cycle is executed. Thus, time is not accurately represented.



SunOS 5.4              Last change: 2/1/96                     11






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



     The behavior of a robot that is single stepped may be  exag-
     gerated, especially while the robot is in motion.

     As the battle is simulated, the robot's X  and  Y  location,
     current  heat index, speed, heading, and damage are updated.
     If the simulator is in the Step Syscalls state, these attri-
     butes  may  also  be set by entering a new value.  Parameter
     fields only accept numeric entries  in  the  range  that  is
     acceptable  for  any particular parameter.  The "Heat" entry
     turns red (inverse on monochrome displays) when the  robot's
     motor is the in overheated state.

     The last syscall executed by the robot is shown, along  with
     the  arguments  to the call (if any).  The return value from
     the syscall is shown in parentheses.  The current clock tick
     and  barrel  temperature  is  also  displayed, but cannot be
     altered.  If the robot program use the  "after"  command  to
     schedule  syscalls  (or  procs  that contain syscalls), then
     those commands may continue to  run,  running  two  syscalls
     while in single step mode.

     At the bottom of the  simulator,  global  variables  in  the
     robot  may  be examined or set.  Entering a variable name in
     the "Variable" entry and pressing  enter  or  the  "Examine"
     button  will  display  the variable's value.  Entering a new
     value in the "Value" entry and pressing enter or  the  "Set"
     button will set the variable.

TOURNAMENT CONTROLLER
     The "Tournament.." button starts the  Tournament  Controller
     window.   When  the  "Start  Tournament"  button is pressed,
     files in the Robot Files Selected window are  first  scanned
     for uniqueness, ignoring any duplicate filenames.  A tourna-
     ment is run on the remaining files in a round-robin fashion,
     each robot battling every other, one-on-one.

     A time limit is imposed on each battle.  The default  is  10
     minutes  per  battle, and may be set in the "Maximum minutes
     per match" entry.  Optionally,  tournament  results  may  be
     saved  into  a  file  by specifying a valid file name in the
     "Optional results file" entry.

     Results of  each  individual  match  are  displayed  in  the
     "Results" listbox.

     Each battle is scored.  A robot  winning  a  match  receives
     three  points.  A tie match (both robots still running after
     the time limit expires) results in one point each.   At  the
     end  of the tournament, robots are ranked according to total
     points.





SunOS 5.4              Last change: 2/1/96                     12






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



     During each match, the main window operates as in "Run  Bat-
     tle"  mode;  "Halt  may be used to stop a tournament in pro-
     gress.  The Tournament Controller's window will display  the
     time remaining in the current match.

INTERNALS
     TclRobots  implements  a  small  "physics"   package   (proc
     update_robots)  to control robot and missile (cannon shells)
     movement.  The proc is  scheduled  to  run  every  500  mil-
     liseconds during a battle.

     Each robot in a battle executes in a  separate  wish  inter-
     preter.   When a new robot is started, a series of setup and
     interface code is first  sent  (using  "send")  to  the  new
     intepreter.   A  "source"  command  is  also sent to load an
     individual robot control program.  The interface  code  that
     is  sent causes each robot to relay its interface calls back
     to TclRobots using the "send" command.

     Most commands set parameters  in  an  array  that  TclRobots
     maintains.    The   "update_robots"  proc  carries  out  the
     requests.  "Scanner" is an exception, in that  the  scan  is
     computed  and  values returned.  Commands that return status
     information merely return relevant  portions  of  the  robot
     array.

     Cheating?
     Since each robot communicates to TclRobots via the send com-
     mand,  it  exposes  TclRobots  to unauthorized access to its
     internals.  Thus, a crafty robot programmer may  be  tempted
     to  use  send  to  look at or set the state of other robots.
     The setup code is modified for each robot, renaming the send
     command  to a randomly generated name.  The Tcl info command
     is deleted, so that the new send command name is not readily
     apparent.  However, this method is not totally foolproof.

     Just consider it to be "unsportsman-like"  to  attempt  such
     usage of send.

ACKNOWLEDGMENTS
     I've used a few pieces of code in TclRobots  that  I  didn't
     write, and I acknowledge those people:

            Mark Eichin - rand, from a comp.lang.tcl posting
            Bill Burdick - every, from a comp.lang.tcl posting
            John Ousterhout - tk_dialog2, modified to  use  image
          bitmaps

            I also used the file  selection  box  procs  from  my
          "wisql" and "wosql"
            programs distributed with Sybtcl and Oratcl.




SunOS 5.4              Last change: 2/1/96                     13






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



     I'd also like to recognize  John  Ousterhout,  for  creating
     Tcl/Tk and making it available to the world.  Tcl/Tk is such
     a flexible language - I was able to graft in  the  simulator
     and  tournament controller as after thoughts, without chang-
     ing much existing code.

NOTES
     If you are unfamiliar with 'Core war', it is  a  programming
     game  based on two assembly language programs running in one
     address space of a virtual computer.  Programs try to  cause
     the  other  to terminate, leaving the winning program as the
     only one left running.

     From  the  rec.games.corewar  Frequently   Asked   Questions
     (Stefan Strack):

          Core War was first described in the  "Core  War  Guide-
          lines"  of March, 1984 by D. G. Jones and A. K. Dewdney
          of the Department of Computer Science at The University
          of  Western  Ontario  (Canada).   Dewdney wrote several
          "Computer Recreations" articles in  "Scientific  Ameri-
          can"  which  discussed  Core War, starting with the May
          1984 article.

     My  CROBOTS  game  was  released  in  1985   as   PC   MSDOS
     "Shareware".    It  is  still  available  from  various  FTP
     archives, including:

     ftp://oak.oakland.edu/pub/msdos/c/crobots.zip

     CROBOTS was released in  binary  form  only,  and  a  source
     license  was  available  for  payment  of the shareware fee.
     Working on TclRobots has again sparked my interest  in  such
     games,  and  I'm tempted to update CROBOTS. Any such release
     (no promises when that might be) will include source.

     If TclRobots complains that  you  are  using  "xhost"  style
     security,  you  should either use "xauth" style security, or
     recompile  your  wish  interpreter,  uncommenting   the   Tk
     Makefile line:

     #SECURITY_FLAGS = -DTK_NO_SECURITY

     Information on setting up "xauth" is available at:

     ftp://ftp.aud.alcatel.com/tcl/docs/Xauthority.gz

BUGS
     TclRobots is inherently simplistic in its treatment of  phy-
     sics.   Part  of the goal is to run a challenging game while
     still executing and updating the battlefield in a reasonable
     time  period.   I  developed  TclRobots  on  a  486-50mhz pc



SunOS 5.4              Last change: 2/1/96                     14






TclRobots(6)                 Tcl/Tk                  TclRobots(6)



     running Linux, and can easily run a four robot battle  (five
     wish interpreters running.)

     I've fixed the size of the main window, largely for ease  of
     plotting  the  robots and missiles in the canvas.  Currently
     the canvas is 500x500 pixels, so  reducing  the  battlefield
     arena  to  canvas  locations  is a simple divide by two.  My
     intent was to save as  much  processing  during  the  update
     cycle.

     The time limit in interactive tournament mode is not  actual
     wall  clock  time, but rather a calculation that assumes the
     500 millisecond tick rate of the physics  package  is  accu-
     rate.   The  time  that "update_robots" takes to run on each
     tick is cumulative in distorting tournament time.

     When running a tournament or single battle with the "-nowin"
     option,  it's  possible  that results may vary from the same
     tournament or battle run in interactive  mode.   Battlefield
     time  is  "warped"  five  times  faster, but alas, TclRobots
     can't make your CPU run  any  faster.   Robot  programs  may
     experience less actual Tcl instructions executed per battle-
     field clock tick.  Robot programs that depend on the  'tick'
     syscall may be affected more than robot programs that don't.

     The user interface was not designed.   Instead,  it  evolved
     from functionality.  It could probably stand improvement.

     No doubt that some programmers will  carefully  examine  the
     "physics"  package  and exploit its weaknesses.  At least it
     available for all to see.  Some of the ideas I put in TclRo-
     bots  that  was missing from CROBOTS is the "motor heating",
     which should eliminate robots running a full  speed  for  an
     extended period of time.  Also, the cannon is limited on its
     ability for rapid  fire  by  introducing  the  notion  of  a
     "clip",  with longer reloading times, and firing too rapidly
     can cause temporary "blindness".

AUTHOR
     Tom Poindexter,  Denver,  Colorado.   Version  2.0  released
     February, 1996.

     Any suggestions for improvement can be sent  to  me  at  the
     address listed at the top of this document.








SunOS 5.4              Last change: 2/1/96                     15






