(C) Copyright 1985, All rights reserved.

        CROBOTS is copyrighted by:

                Tom Poindexter

                2903 Winchester Drive

                Bloomington, Illinois 61701 USA

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        Table of Contents

        1.  License agreement and disclaimer of warranty...........2

        2.  Introduction

          2-1.  Description........................................3

          2-2.  Intended audience..................................3

          2-3.  Machine requirements...............................3

          2-4.  User interface.....................................3

        3.  Types of play

                Single Play........................................4

                Match Play.........................................4

        4.  Running CROBOTS

          4-1.  Command line options...............................4

          4-2.  Examples...........................................5

        5.  Game Parameters

          5-1.  Battlefield........................................5

          5-2.  Robot offense......................................5

          5-3.  Robot defense......................................6

          5-4.  Disabling robots...................................6

          5-5.  Sample display.....................................7

        6.  CROBOTS CPU............................................8

        7.  CROBOTS C Compiler

          7-1.  Description........................................8

          7-2.  Features missing from standard C...................8

          7-3.  CROBOTS language...................................9

          7-4.  Compiler limits...................................11

          7-5.  Error and warning messages........................11

        8.  CROBOTS C Intrinsic Function Library

                scan()............................................12

                cannon()..........................................13

                drive()...........................................13

                damage()..........................................13

                speed()...........................................13

                loc_x(), loc_y()..................................14

                rand()............................................14

                sqrt()............................................14

                sin(), cos(), tan(), atan().......................14

        9.  CROBOTS C Program Structure

          9-1.  Structure.........................................15

          9-2.  Sample: "sniper.r"................................15

        10. CROBOTS CPU Architecture

          10-1. Stack.............................................20

          10-2. Link list.........................................21

          10-3. Instruction set...................................22

          10-4. Machine level debugging...........................23

        11. Implementation Notes..................................24

        12. Order Form............................................25

                                Page 1

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        1.  License agreement:

        You may make copies of this program, manual, and other files and

        give it to your friends, upload it to bulletin boards, or include

        it in the library of a non-profit computer club.

        I expressly forbid any for-profit venture from selling this

        software and manual, either separately or as part of a "library"

        diskette.

        SUPPORT SHAREWARE!                       

        If you find this software has any value for you, please send a

        contribution.  For contributions of $20 or more, you will receive

        the full source code to CROBOTS on diskette.  Use the order form

        at the end of the documentation.  Your contribution will

        encourage me to enhance the program, by expanding the CROBOTS C

        compiler, adding graphics, sound, etc.

        Whether or not you contribute, please share this software with

        others.

        DISCLAIMER OF WARRANTY

        THIS SOFTWARE AND MANUAL ARE PROVIDED "AS IS" WITHOUT WARRANTY OF

        AND KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED

        TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS OF

        PURPOSE.  THE USER OF THIS SOFTWARE AND MANUAL ASSUME ALL RISKS.

                                Page 2

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        2.  Introduction

        2-1.  Description

        CROBOTS ("see-robots") is a game based on computer programming.

        Unlike arcade type games which require human inputs controlling

        some object, all strategy in CROBOTS must be complete before the

        actual game begins.  Game strategy is condensed into a C language

        program that you design and write.  Your program controls a robot

        whose mission is to seek out, track, and destroy other robots,

        each running different programs.  Each robot is equally equipped,

        and up to four robots may compete at once.  CROBOTS is best

        played among several people, each refining their own robot

        program, then matching program against program.

        CROBOTS consists of a C compiler, a virtual computer, and

        battlefield display (text graphics only, monochrome or color).

        The CROBOTS compiler accecpts a limited (but useful) subset of

        the C language.  The C robot programs are aided by hardware

        functions to scan for opponents, start and stop drive mechanisms,

        fire cannons, etc.  After the programs are compiled and loaded

        into separate robots, the battle is observed.  Robots moving,

        missiles flying and exploding, and certain status information are

        displayed on the screen, in real-time.

        2-2.  Intended audience

        CROBOTS will most likely appeal to programmers (especially those

        who think they can write the "best" programs), computer game

        enthusiasts, people wishing to learn the C language, and those

        who are interested in compiler design and virtual computer

        interpreters.

        2-3.  Machine and software requirements

        - IBM-PC, or other close MS-DOS computers that use INT 10H video

          calls

        - 192k ram

        - DOS 2.0 or higher

        - One disk drive

        - Monochrome or Color/Graphics display

        - Text editor (PC-DOS Edlin, or your own favorite)

        2-4.  User interface

        CROBOTS does not use menus, windows, pop-ups, or any other

        user-friendly interface.  Since the emphasis is on designing and

        writing robot control programs, CROBOTS is started as a compiler

        might be started, from the DOS command line.

                                Page 3

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        3. Types of play

        CROBOTS can either run one match (single play), in which the full

        screen, realtime battlefield display is used, or several matches

        (match play), in which only the name of the winner is

        printed after each match.  Single play is the default.  Match

        play is intended to see how robot programs perform on the

        average.   Match play can consume several hours of computer

        time depending on the number of matches and cpu cycle limit, and

        can be run overnight.

        4.  Running CROBOTS

        4-1.  Command line options

        CROBOTS is started from the DOS prompt:

        A>crobots [options] robot-program-1 [robot-program-n] [>file]

        Valid options and parameters are:

        -c    (opt)     Compile only, and produce virtual machine

                        assembler code and symbol tables.

        -d    (opt)     Compile one program, and invoke machine level

                        single step tracing.

        -mxxx (opt)     Run a series of matches, were "xxx" is the number

                        of matches.  There should be no spaces between

                        "-m" and the number.  If "-m" is not specified,

                        then the default is to run one match and display

                        the realtime battlefield.

        -lxxx  (opt)    Limit the number of machine cpu cycles per match

                        when "-m" is specified.  There should be no

                        spaces between "-l" and the number.  The default

                        cycle limit is 500,000 when -m is specified

        robot-programs  (required)

                        The file name of the CROBOTS source program(s).

                        Up to four files may be specified.  If

                        only one file is specified, it will be "cloned"

                        into another, so that two robots (running the

                        same program) will compete.

                        Any file name may be used, but for consistency

                        use '.r' as an extension.

        >file  (opt)    Use DOS 2.0+ redirection to get a compile

                        listing ("-c" option) or to record matches ("-m"

                        option).

                                Page 4

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        4-2.  Examples:

                1) Watch three robots compete with full display:

                        A>crobots robot1.r robot2.r robot3.r

                2) Compile one robot, and save the listing:

                        A>crobots -c robot1.r >robot1.lst

                3) Debug a robot (first get an assembler code listing,

                   as in example 2:

                        A>crobots -d robot1.r

                4) Run 50 matches, limiting total cpu cycles to 200,000,

                   and save results:

                        A>crobots -m50 -l200000 robot1.r robot2.r >save

        5.  Game parameters

        5-1.  Battlefield

        The battlefield is a 1,000 by 1,000 meter square.  A wall

        surrounds the perimeter, so that a robot running into the wall

        will incur damage.

        The lower left corner has the coordinates x = 0, y = 0; the upper

        right corner has the coordinated x = 999, y = 999.

        The compass system is oriented so that due east (right) is 0

        degrees, 90 is north, 180 is west, 270 is south.  One degree

        below due east is 359.

                         135    90   45

                                \  |  /

                                 \ | /

                        180 --- x --- 0

                                 / | \

                                /  |  \

                         225   270   315

        5-2.  Robot offense

        The main offensive weapons are the cannon and scanner.  The

        cannon has a range of 700 meters.  There are an unlimited number

        of missiles that can be fired, but a reloading factor limits the

        number of missiles in the air at any one time to two.  The cannon

        is mounted on an independent turret, and therefore can fire any

        direction, 0-359, regardless of robot heading.

                                Page 5

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        The scanner is an optical device that can instantly scan any

        chosen heading, 0-359.  The scanner has a maximum resolution of 

        +/- 10 degrees.  This enables the robot to quickly scan the field

        at a low resolution, then use maximum resolution to pinpoint an

        opponent.

        5-3.  Robot defense

        The only defense available are the motor drive and status

        registers.  The motor can be engaged on any heading, 0-359, in

        speeds from 0-100 percent of power.  There are acceleration and

        deacceleration factors.  A speed of 0 stops the motor.  Turns can

        be negotiated at speeds of 50% and less, in any direction.  Of

        course, the motor drive can be engaged any time, and is necessary

        on offense when a target is beyond the 700 meter range of the

        cannon.

        Certain status registers provide feedback to the robot. The

        primary registers indicate the percent of damage, and current x

        and y locations on the battlefield.  Another register provides

        current drive speed.

        5-4.  Disabling opponents

        A robot is considered dead when the damage reaches 100%.  Percent

        of damage is inflicted as follows:

                2% - collision into another robot (both robots in a   

                     collision receive damage) or into a wall.  A

                     collision also causes the motor drive to disengage,

                     and speed is reduced to 0.

                3% - a missile exploding within a 40 meter radius.

                5% - a missile exploding within a 20 meter radius.

               10% - a missile exploding within a 5 meter radius.

        Damage is cumulative, and cannot be repaired.  However, a robot

        does not loose any mobility, fire potential, etc. at high damage

        levels.  In other words, a robot at 99% damage performs equally

        as a robot with no damage.

                                Page 6

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        5-5.  Sample display                               

                                                          (Status

                                        (x=999,y=999)        blocks)

           +------------------------------------+ 1 fubar.r

           |                                               |  D% 015   Sc 218

           |                          \|/ 1              |  Sp 000   Hd 090

           |     (missile exploding)  -#-        | ------------------

           |                          /|\                 | 2 snafu.r

        (y |                                              |  D% 050   Sc 275

           |              +        (missiles          |  Sp 100   Hd 180

        a  |                     +   flying)           | ------------------

        x  |   2                                          | 3 bimbo.r

        i  |                                                |  D% 000   Sc 045

        s) |                 3                            |  Sp 000   Hd 000

           |                /                              | ------------------

           |          (robots) ----\                  | 4 kumquat.r

           |                         4                    |  D% 100   Sc 050

           |                                               |  Sp 000   Hd 335

           |                                               |

           |                                               |

           +------------------------------------+ CPU Cycle: 4500

        (x=0,y=0)         (x axis)

        Each status block shows the file name of the robot, the damage

        incurred, the current scan degrees, and the speed and heading.

        Robots are represented on the field by '1', '2', etc., according

        to the status block position.  The number of elapsed robot cpu

        cycles is shown at the bottom of the status blocks.

        The CROBOTS program can be stopped at any time, by using

        Ctrl-Break.

                                Page 7

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        6.  CROBOTS CPU

        The robot cpu is a simple stack-oriented computer.  It operates

        at very slow speeds (on a 4.77MHz 8088 PC with two robots

        running, the average speed is 270 instructions per second, .00027

        mips!!).  The word size is 32 bits, allowing integer values from

        -2,147,483,648 to 2,147,483,647.  There are internal pointer

        registers that manage stack usage, but are not accessable from a

        robot program.  The same is true for an implicit accumulator.

        The maximum code space is 1,000 instructions.  All instructions

        are equal in length.  The maximum stack size is 500 words, which

        is used for data and function call/returns.  The stack grows

        upward for data usage, and downward (from the end) for function

        call/returns.  Three words are used for each function call, and

        are release upon the function return.  The data portion and

        call/return portion are managed by separate internal stack

        pointers.

        If the data stack pointer and call/return stack pointer collide,

        a stack overflow occurs.  In this case, the robot is restarted

        at the 'main' function, with the stack reset to all zeroes.

        For more information, see the section on machine instructions and

        theory.

        7.  CROBOTS C compiler

        7-1.  Description

        The CROBOTS compiler accepts a limited subset of the C language.

        There is no provision for separate compilation, i.e., all modules

        of a program must be in one file.  No preprocessor is provided

        for "#define", "#include", etc.  Identifiers are significant to 7

        characters, although any length may be used.  The compiled

        machine code is loaded into the robot cpu, and cannot be saved.

        7-2.  Features missing from standard C

        Major language features missing from K&R are:  floating point

        variables, structures, unions, pointers, initializers, arrays,

        character data, typedefs, for statment, do..while statement,

        switch..case statement, break, continue, gotos and labels,

        ternary and comma operators, octal and hexadecimal constants, no

        parameters to main(), and all preprocessor directives.

        My apologies to "The C Programming Language" by Brian W.

        Kernighan and Dennis M. Ritchie, Prenctice-Hall, 1978.

                                Page 8

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        7-3.  CROBOTS language

        The language features that are present are entirely suitable for

        writing robot control programs.  Basic programming constructs of

        if..then..else, while, and function calls can be used freely.

        Full expression evaluation is also provided, so that statements

        such as:

                if ((x = func1(y,1,++z,func2(c))) > 0)

                  a = 0; 

                else

                  a = x;

        are perfectly legal.  Ifs and whiles may be nested, and recursion

        is supported.  Variables declared outside a function definition

        are global in scope, whereas variables declared inside a function

        definition are local to that function.

        The following keywords are recognized:

        comments:

        "/* ... */"     comments cannot be nested

        constants:

        any decimal digits, optionally preceeded with a '-'

         declarations:

       "int"           variable declare

       "long"          same as int

       "auto"          default storage scope, optional

       "register"      legal, but ignored, same as auto

       "function (parms,.....)"  function definition

         logic control:

        "if (expr) STMT else STMT"

         iteration:

        "while (expr) STMT"

        function return:

       "return"        return

       "return expr"   return a with value

        assignment operators:

       "="             assignment  

       ">>="           assignment shift right

       "<<="           assignment shift left

       "+="            assignment addition

       "-="            assignment subtraction  

       "*="            assignment multiplication  

       "/="            assignment division  

       "%="            assignment modulo  

        "&="            assignment and  

       "^="            assignment exclusive or  

       "|="            assignment inclusive or

                                Page 9

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        bit-wise operators:

       ">>"            shift right

       "<<"            shift left              

       "&"             and

       "!"             unary not

       "~"             unary one's complement

       "^"             exclusive or

       "|"             inclusive or                         

        increment/decrement operators:

       "++"            prefix increment, see derivations

       "--"            prefix decrement, see derivations

        logical operators:

       "&&"            logical and  

       "||"            logical or   

       "<="            logical less than or equal   

       ">="            logical greater than or equal   

       "=="            logical equal  

       "!="            logical not equal  

       "<"             logical less than  

       ">"             logical greater than  

        arithmetic operators:

       "-"             subtraction or unary negation

       "+"             addition  

        "*"             multiplication  

       "/"             division  

       "%"             modulo  

        misc:

       ";"             statement terminator or null statement  

        "{ }"           compound statement  

       ","             parameter separator in function definition or call

        "( )"           expression or function definition or call

        Precedence and order of evaluation are the same as in K&R.

                Operator                Associativity

                ()                      left to right

                ! ~ ++ -- -             right to left

                * / %                   left to right

                + -                      "   "   "

               << >>                    "  "    "

               < <= => >               "   "    "

                == !=                    "   "   "

               &                       "   "    "

                ^                       "   "    "

                |                        "   "   "

               &&                      "   "    "

                ||                      "   "    "

                = -= += etc.            right to left

                                Page 10

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        Major derivations from K&R:

        -Local variables need not be declared before reference, i.e., any

        undeclared variable will default to a local variable. 

        -Postfix increment and decrement ("var++" or "var--") are

        recognized, but the result is the same as prefix

        increment/decrement ("++var").

        -Intrinsic function names are reserved.

        7-4.  Compiler limits

        defined functions: 64

        local variables per function: 64

        external variables: 64

        if nest level: 16

        while nest level: 16

        7-5.  Complier error and warning messages:

        The compiler has no error recovery and will stop on the first

        error found.  Sorry.  Warning messages do not stop the compiler.

        Error messages

       "syntax error" - Any input that results in improper C syntax will

        yield "syntax error", with an indicator pointing to the

        unrecognizable input.

       "instruction space exceeded" - compiler tried to generate more

        than 1000 machine instructions.

       "symbol pool exceeded" - the maximum local variable, external

        variable, or function definition symbol table was exceeded.

       "function referenced but not found" - a function was referenced

        that was not defined in the input file or is not an intrinsic

        function.

        "main not defined" - the input file did not define a 'main()'

        function.

       "function definition same as intrinsic" - a function was defined

        with the same name as an intrinsic function, which are reserved.

        "if nest level exceeded" - more than 16 'if's were nested.

        "while nest level exceeded" - more than 16 'while's were nested.

        "yacc stack overflow" - the compiler's parser overflowed,

        probably due to complex expressions and/or extreme nesting.

                                Page 11

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        Warning messages

        These messages will not cause the compiler to fail, but may cause

        the program to executed unexpectedly.

       "unsupported initializer" - variable declares cannot include an

        initializer.  For future releases.

       "unsupported break" - the 'break' statement was found and

        ignored.  For future releases.

        "n postfix operators" - postfix increment or decrement

        operators were used, and are coerced into prefix expressions.

        "n undeclared variables" - one or more variables were implicitly

        declared.

        "code utilization: n%" - reports the capacity of machine

        instructions generated.

        8.  CROBOTS C Intrinsic Function Library

        The intrinsic function library provides machine level control and

        certain arithmetic functions.  These functions do not consume

        any of the program code space or data stack, except for the three

        words for call/return sequences.  No explicit linking is required

        to use any intrinsic function.

        scan (degree,resolution) 

        The scan() function invokes the robot's scanner, at a specified

        degree and resolution.  scan() returns 0 if no robots are

        within the scan range or a positive integer representing the

        range to the closest robot.  Degree should be within the range

        0-359, otherwise degree is forced into 0-359 by a modulo 360

        operation, and made positive if necessary.  Resolution controls

        the scanner's sensing resolution, up to +/- 10 degrees.

        Examples:

           range = scan(45,0); /* scan 45, with no variance */

           range = scan(365,10); /* scans the range from 355 to 15 */

                                Page 12

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        cannon (degree,range)

        The cannon() function fires a missile heading a specified range

        and direction.  cannon() returns 1 (true) if a missile was fired,

        or 0 (false) if the cannon is reloading.  Degree is forced into

        the range 0-359 as in scan().  Range can be 0-700, with greater

        ranges truncated to 700.

        Examples:

           degree = 45;    /* set a direction to test */

           if ((range=scan(degree,2)) > 0) /* see if a target is there */

             cannon(degree,range);  /* fire a missile */

        drive (degree,speed)

        The drive() function activates the robot's drive mechanism, on a

        specified heading and speed.  Degree is forced into the range

        0-359 as in scan().  Speed is expressed as a percent, with 100 as

        maximum.  A speed of 0 disengages the drive.  Changes in

        direction can be negotiated at speeds of less than 50 percent.

        Examples:

           drive(0,100);  /* head due east, at maximum speed */

           drive(90,0);   /* stop motion */

        damage()

        The damage() function returns the current amount of damage

        incurred.  damage() takes no arguments, and returns the percent

        of damage, 0-99. (100 percent damage means the robot is

        completely disabled, thus no longer running!)

        Examples:

          d = damage();       /* save current state */

          ; ; ;               /* other instructions */

          if (d != damage())  /* compare current state to prior state */

          {

            drive(90,100);    /* robot has been hit, start moving */

            d = damage();     /* get current damage again */

          }

        speed ()

        The speed() function returns the current speed of the robot.

        speed() takes no arguments, and returns the percent of speed,

        0-100.  Note that speed() may not always be the same as the last

        drive(), because of acceleration and deacceleration.

        Examples:

          drive(270,100);   /* start drive, due south */

          ; ; ;             /* other instructions */

          if (speed() == 0) /* check current speed */

          {

            drive(90,20); /* ran into the south wall, or another robot*/

          }

                                Page 13

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        loc_x ()

        loc_y ()

        The loc_x() function returns the robot's current x axis location.

        loc_x() takes no arguments, and returns 0-999.

        The loc_y() function is similar to loc_x(), but returns the

        current y axis position.

        Examples:

           drive (180,50);  /* start heading for west wall */

           while (loc_x() > 20)

             ;              /* do nothing until we are close */

           drive (180,0);   /* stop drive */

        rand (limit)

        The rand() function returns a random number between 0 and limit,

        up to 32767.

        Examples:

          degree = rand(360);     /* pick a random starting point */

          range = scan(degree,0); /* and scan */

        sqrt (number)

        The sqrt() returns the square root of a number.  Number is made

        positive, if necessary.

        Examples:

           x = x1 - x2;     /* compute the classical distance formula */

           y = y1 - y2;     /* between two points (x1,y1) (x2,y2) */

           distance = sqrt((x*x) - (y*y));

        sin (degree)

        cos (degree)

        tan (degree)

        atan (ratio)

        These functions provide trigometric values.  sin(), cos(),

        and tan(), take a degree argument, 0-359, and returns the

        trigometric value times 100,000.  The scaling is necessary since

        the CROBOT cpu is an integer only machine, and trig values are

        between 0.0 and 1.0.  atan() takes a ratio argument that has been

        scaled up by 100,000, and returns a degree value, between -90 and

        +90.  The resulting calculation should not be scaled to the

        actual value until the final operation, as not to lose accuracy.

        See programming examples for usage.

                                Page 14

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        9.  CROBOTS C Program Structure

        9-1.  Basic program structure

        CROBOTS programs are not unlike other C programs.  The minimum

        CROBOTS program consist of a function named "main".

        Additionally, other functions can be defined, along with external

        variables.

        9.2 "sniper.r"

        The following CROBOTS program is provided as an example.

/* sniper */

/* strategy: since a scan of the entire battlefield can be done in 90 */

/* degrees from a corner, sniper can scan the field quickly. */

/* external variables, that can be used by any function */

int corner;           /* current corner 0, 1, 2, or 2 */

int c1x, c1y;         /* corner 1 x and y */

int c2x, c2y;         /*  "    2 "  " " */

int c3x, c3y;         /*   "    3 " "  " */

int c4x, c4y;         /*   "    4 " "  " */

int s1, s2, s3, s4;   /* starting scan position for corner 1 - 4 */

int sc;               /* current scan start */

int d;                /* last damage check */

                                Page 15

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

/* main */

main()

{

  int closest;        /* check for targets in range */

  int range;          /* range to target */

  int dir;            /* scan direction */

  /* initialize the corner info */

  /* x and y location of a corner, and starting scan degree */

  c1x = 10;  c1y = 10;  s1 = 0;

  c2x = 10;  c2y = 990; s2 = 270;

  c3x = 990; c3y = 990; s3 = 180;

  c4x = 990; c4y = 10;  s4 = 90;

  closest = 9999;

  new_corner();       /* start at a random corner */

  d = damage();       /* get current damage */

  dir = sc;           /* starting scan direction */

  while (1) {         /* loop is executed forever */

    while (dir < sc + 90) {  /* scan through 90 degree range */

      range = scan(dir,1);   /* look at a direction */

      if (range <= 700 && range > 0) {

        while (range > 0) {    /* keep firing while in range */

          closest = range;     /* set closest flag */

          cannon(dir,range);   /* fire! */

          range = scan(dir,1); /* check target again */

          if (d + 15 > damage())  /* sustained several hits, */

            range = 0;            /* goto new corner */

        }

        dir -= 10;             /* back up scan, in case */

      }

      dir += 2;                /* increment scan */

      if (d != damage()) {     /* check for damage incurred */

        new_corner();          /* we're hit, move now */

        d = damage();

        dir = sc;

      }

    }

    if (closest == 9999) {       /* check for any targets in range */

      new_corner();             /* nothing, move to new corner */

      d = damage();

      dir = sc;

    } else                      /* targets in range, resume */

      dir = sc;

    closest = 9999;

  }

}  /* end of main */

                                Page 16

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

/* new corner function to move to a different corner */

new_corner() {

  int x, y;

  int angle;

  int new;

  new = rand(4);           /* pick a random corner */

  if (new == corner)       /* but make it different than the */

    corner = (new + 1) % 4;/* current corner */

  else

    corner = new;

  if (corner == 0) {       /* set new x,y and scan start */

    x = c1x;

    y = c1y;

    sc = s1;

  }

  if (corner == 1) {

    x = c2x;

    y = c2y;

    sc = s2;

  }

  if (corner == 2) {

    x = c3x;

    y = c3y;

    sc = s3;

  }

  if (corner == 3) {

    x = c4x;

    y = c4y;

    sc = s4;

  }

  /* find the heading we need to get to the desired corner */

  angle = plot_course(x,y);

  /* start drive train, full speed */

  drive(angle,100);

  /* keep traveling until we are within 100 meters */

  /* speed is checked in case we run into wall, other robot */

  /* not terribly great, since were are doing nothing while moving */

  while (distance(loc_x(),loc_y(),x,y) > 100 && speed() > 0)

    ;

  /* cut speed, and creep the rest of the way */

  drive(angle,20);

  while (distance(loc_x(),loc_y(),x,y) > 10 && speed() > 0)

    ;

  /* stop drive, should coast in the rest of the way */

  drive(angle,0);

}  /* end of new_corner */

                                Page 17

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

/* classical pythagorean distance formula */

distance(x1,y1,x2,y2)

int x1;

int y1;

int x2;

int y2;

{

  int x, y;

  x = x1 - x2;

  y = y1 - y2;

  d = sqrt((x*x) + (y*y));

  return(d);

}

/* plot course function, return degree heading to */

/* reach destination x, y; uses atan() trig function */

plot_course(xx,yy)

int xx, yy;

{

  int d;

  int x,y;

  int scale;

  int curx, cury;

  scale = 100000;  /* scale for trig functions */

  curx = loc_x();  /* get current location */

  cury = loc_y();

  x = curx - xx;

  y = cury - yy;

  /* atan only returns -90 to +90, so figure out how to use */

  /* the atan() value */

  if (x == 0) {      /* x is zero, we either move due north or south */

    if (yy > cury)

      d = 90;        /* north */

    else

      d = 270;       /* south */

  } else {

    if (yy < cury) {

      if (xx > curx)

        d = 360 + atan((scale * y) / x);  /* south-east, quadrant 4 */

      else

        d = 180 + atan((scale * y) / x);  /* south-west, quadrant 3 */

    } else {

      if (xx > curx)

        d = atan((scale * y) / x);        /* north-east, quadrant 1 */

      else

        d = 180 + atan((scale * y) / x);  /* north-west, quadrant 2 */

    }

  }

  return (d);

}

                                Page 18

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        Notes:  The distance() and plot_course() routines are

        quite handy.  Save them for your programs.  Also, note that the

        main scan routine will "back up" a few degrees after a target has

        been found and fired upon.  This should catch robots trying to

        flee away from the direction you are scanning.  If the target

        moves the other way, the normal scan increment will find it.

        See the other sample CROBOTS program files.

                                Page 19

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        10.  CROBOTS CPU Architecture and Theory

        This information is provided if you need to use the debug

        facility, or are curious about the virtual machine interpreter.

        Don't bother reading this section if you not so inclined; it is

        not needed for normal play.

        10-1.  Stack usage:

        That stack is controlled implicitly by several pointers.  Stack

        pointers are not accessable through machine instructions.  Most

        instructions will either push data onto the stack, or pop data

        off the stack.  The stack is used from the bottom up (low memory)

        for data and temporary storage, and is used from the top down

        (high memory) for saving stack pointers and the program counter

        on function call/return.

        External (global) variables are allocated at the very bottom of

        the stack, and the local mark pointer for 'main' starts just

        after the externals.  External variables are addressed from the

        beginning of the stack, by offset.

        When a function is called (including 'main'), the stack pointer

        is marked (local mark) and is increased by the number of local

        variables needed for that function.  Local variables are

        addressed relative to the local mark, by offsets.  All

        calculations, function calls, and constants are pushed on and

        popped off the stack as needed (temporary mark or top of stack).

        A function call also saves its current stack pointers (local

        variable mark and frame mark) and program counter.  This

        return information grows from the top down.

        Arguments are passed to functions by value.  The first argument

        in a function call becomes the first local variable for the

        called function.  Consider the following:

        main() {               /* main has three local variables: */

          int a, b, c;

          ....;

          sub1 (a,b/2,c+1);    /* call sub1, and pass arguments */

          ....;

        }

        sub1 (x,y,z)           /* sub1 takes three parameters and */

        int x, y, z; {         /* has one local variable */

          int result;

          result = x + y + z;

          return (result);

        }

                                Page 20

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        The main() function allocates three local variables on the stack,

        sets its local mark at 'a', and sets the temporary stack pointer

        beyond the locals.  Just before sub1() is called, the value of

        'a' is pushed, followed by the result of 'b/2', and 'c+1'.  When

        sub1() is called, it sets its local mark where the value of 'a'

        is, so that 'a' is know as 'x' in func1(), likewise 'b/2'

        is known as 'y' and 'c+1' is known as 'z'.  Sub1() also

        allocates one more word for 'result', and sets the temporary mark

        after the storage for 'result'.

        The following diagram illustrates the stack usage:

                +------------+   <-- end of stack, high memory

                |main return |   <-- return info for main

                +------------+       (frame,ip,local mark)

                |sub1 return |   <-- return info for sub1

                +------------+       (etc.)

                |     |      |

                |     v      |  <-- additional function call return

                |            |       info grow downwards

                |            |

                |            |

                |            |

                |     ^      |  <-- additional function calls and

                |     |      |       expressions grow upwards

                |expressions |

                +------------+   <-- temporary mark (top of stack)

                |sub1 locals |

                +------------+   <-- local mark: sub1 function

                |main locals |

                +------------+   <-- local mark: main function

                |            |

                | Externals  |

                |            |

                +------------+   <-- beginning of stack

        10-2.  Link list

        The link list is a list built by the compiler that contains

        the names and link information of the functions within the

        program.  The link information contains the starting location of

        the function within the code, the number of parameters, and the

        number of other local variables within the function.  The link

        list cannot be accessed by the user program.

                                Page 21

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        10-3.  Instruction set

        The CROBOTS cpu has 10 instructions.  Each instruction occupies

        the same amount of storage, with or without operands.

        FETCH offset (external | local) - Fetch will retrieve a word from

        either the external variable pool or the local variable pool and

        push it onto the stack.  The offset has its high-bit set (or'ed

        with 0x8000) if it is an external (offset from the beginning of

        the stack), otherwise it is a local (offset from the local

        variable mark).  See STORE.

        STORE offset (external | local), opcode - Store pops the top two

        items, applies the arithmetic opcode to the two operands,

        pushes the result on the top of the stack and stores it in the

        variable referenced by the offset.  Offsets are either external

        or local, according to the method described in Fetch.  The result

        of the opcode is left on the stack.  See FETCH and BINOP.

        CONST k - Const will push a constant onto the stack.

        BINOP opcode - Binop will pop the top two items as top of stack =

        y, next to top of stack as x, apply the arithmetic opcode as

        (x opcode y), and push the result on the stack.  Opcodes are

        decimal representations of 'C' operators such as '+', '/',

        '>=', etc.  See STORE.

        FCALL link-offset - Fcall performs a high level function call

        facility.  The link-offset operand specifies an entry in the link

        list table.  Fcall pushes its return information:  the next

        instruction counter and the current local variable mark.  A new

        local variable mark and temporary mark (top of stack pointer) is

        set.  The cpu then branches to the first instruction of the

        function.  See RETSUB and FRAME.

        RETSUB - Retsub returns from a function, leaving the return value

        on the top of the stack.  Retsub restores the previous local

        variable pool, the next instruction counter, and re-adjusts the

        stack frame to the point just before the call.  The C

        compiler generates code to return a dummy value if the

        function does not explicitly return one. See FCALL and FRAME.

        BRANCH instruction - Branch pops the top of the stack and

        branches to the instruction if the value is zero.  The next

        sequential instruction is executed if the value is

        anything other than zero.

        CHOP - Chop discards the top of the stack by popping it into

        obilvion.

                                Page 22

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        FRAME - Frame facilitates fcall/retsub by saving the current top

        of stack pointer (temporary mark) in anticipation of a fcall

        statement. The top of stack pointer is saved in the call/return

        stack as a frame marker.  See FCALL and RETSUB.

        NOP - No operation.  Is used as a mark indicating the end of

        code.

        10-4. Machine level debugging

        Debug mode is used to trace by single stepping machine

        instructions.  Use this only if you need to see your program

        execute, or are just curious.

        First, get a listing on paper of a compile with full information

        by using the '-c' option:

                A>crobots -c yourpgm.r >prn:

        Next, start CROBOTS again with the '-d' flag:

                A>crobots -d yourprm.r

        Your robot will be placed randomly in the field, and a target

        robot will be placed at the center of the field (x=500,y=500)

        so your robot program can find and shoot at a target.

        The virtual machine interpreter will single step through your

        program (machine instructions, that is).  At every instruction,

        an machine instruction is disassembled, and the top of stack

        pointer and value are printed.  The top of stack and value are

        after the results of the instruction.  Other information may

        also be printed, such as function calls searching the link list,

        etc.

        On every step, you are prompted "d,h,q,<cr>:".  Entering 'd' will

        dump external and local variable pools, as well as vital

        information of your robot:  coordinates, heading, speed, damage,

        etc., and the status of any missiles your robot may have fired.

        Entering 'h' will simulate your robot taking a 10% damage hit, so

        you can check damage detection, etc.  Entering 'q' will quit the

        program immediately, and return you to DOS.  A carriage return

        alone will continue the stepping process.  All responses

        ('d','h', or 'q') should be in lower case only.  You should refer

        to the compile listing for offsets into the external and local

        variable pools, C code, etc.

                                Page 23

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        11.  Implemetation notes

        CROBOTS is written entirely in 'C'.  The compiler section was

        developed with the aid of the Unix* (TM) programs 'yacc' and

        'lex'.  Yacc (yet another compiler-compiler) accepts a 'grammar',

        which describes the CROBOTS 'C' language.  Yacc produces a 'C'

        function known as a parser.  The parser is the heart of the

        compiler, recognizing vaild 'C' constructs.  Lex (lexical

        analyzer) accepts a list of token combinations, and produces a

        'C' function to scan the compiler input for the tokens.  The yacc

        generated parser, yyparse(), repeatedly calls the lex generated

        analyzer, yylex(), to process the source program.  The initial

        screen display routines were developed with the 'curses' screen

        library.

        The 'C' source code was then ported to MS-DOS** (TM), and

        recompiled using the Lattice*** (TM) 2.15E compiler, using the

        'small' memory model.  The screen display functions were

        modified to use 'int86()', accessing the rom INT 10H cursor

        postitioning functions in the IBM-PC bios.

        * Unix is a trademark of Bell Telephone Laboratories.

        ** MS-DOS is a trademark of Microsoft, Inc.

        *** Lattice is a trademark of Lattice, Inc.

        **** IBM is a trademark of International Business Machines, Inc.

                                Page 24

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

        CROBOTS Order Form:

        +----------------------------------------------------------------+

        | 1. Complete and sign the source code license.               |

        |                                                                                  |

        | 2. Send this completed form along with $20 check or      |

        |    money order to:                                                       |

        |                                                                                  |

        |       Tom Poindexter                                                     |

        |       2903 Winchester Drive                                           |

        |       Bloomington, Illinois 61701                                     |

        |                                                                                   |

        |   -For orders outside the U.S., add an additional $5, and  |

        |    enclose  an international money order, payable in       |

        |    U.S. currency.                                                          |

        |                                                                                   |

        |                                                                                   |

        |                                                                                   |

        |  ______________________________________________|

        |  Name                                                                         |

        |                                                                                   |

        |  ______________________________________________|

        |                                                                                   |

        |  ______________________________________________|

        |  Address                                                                     |

        |                                                                                   |

        |                                                                                   |

        |  ______________________   ________  ____________   |

        |  City                     State     Zip                                      |

        |                                                                                    |

        |                                                                                    |

        |  Source code license:                                                    |

        |  Source code to CROBOTS is provided for personal use only. |

        |  You may incorporate portions of CROBOTS into your own     |

        |  programs.                                                                        |

        |                                                                                        |

        |  I agree not to distribute CROBOTS source code to anyone   |

        |  without prior written permission from the copyright             |

        |  holder, whether a fee is charged or not.                             |

        |                                                                                        |

        |                                                                                        |

        |  _________________________________________________ |

        |  Signature                                  Date                                |

        |                                                                                         |

        +----------------------------------------------------------------------+

                                Page 25

        CROBOTS (C) Copyright 1985 by Tom Poindexter.

                                Page 26