
JJJJJ CCCCC BBBB   OOO  TTTTT  SSSS
  J   C     B   B O   O   T   S       By J.Cronje (1998)
  J   C     B BB  O   O   T    SSS
  J   C     B   B O   O   T       S   s9805027@student.up.ac.za
JJJ   CCCCC BBBB   OOO    T   SSSS    j_cronje@hotmail.com


< http://www.geocities.com/SiliconValley/Haven/8434/ >

Ver 0.51 (ShareWare)

------------------------------------------------------------------------------

What is JCBOTS?
---------------

JcBots is a game for programmers. It contains its own language which is
based on assembler. It also contains a Compiler & Simulator. You must
program a robot, to fight and survive in a battle against other robots
which is also created by programmers. Who can program the best robot ?
Your bot can move around, scan for any obstacles, scan for enemies,
Learn the map,fire at the enemy, collect energy, collect ammo,
jump into fire and act intelligent (If you can program it that way).

There can be up to 6 robots on the same map at a time. Team play is
not yet added.

NOTE : The program is NOT case sensative. So an "A" = "a" & "a" = "A".

------------------------------------------------------------------------------

The Map
-------

The map is a grid of 30 x 25 cells. So, the bots can only move North,South,
East and West. I didn't like the idea of angles like C-Bots.

Each cell can contain the following type of objects

* AREA_OPEN   : An open area, the bots can move through here.
* AREA_WALL   : A solid wall, can't move through it. Can't shoot through it.
* AREA_AMMO   : If the bot stands on this cell, it will receive ammo.
* AREA_ENERGY : This cell gives you energy.
* AREA_KILL   : Dangerous cell. It will decrease your bots energy.
* AREA_ENEMY  : It can contains another bot. (The enemy)

The MapFile
-----------

This file is used to store the map information. You can create your own
graphics for each type of block. Ex. You can have different styles
of walls, floors, ect..

First of all, you must create the graphics and define the type of blocks
in the map. You can do this by indicating the character for the cell between
"" and followed by a constant which I mentioned above (AREA_OPEN/AREA_WALL..
except AREA_ENEMY).

The character between the "" will be case sensative!
"a" is not equal to "A". This is so that you can add more type of blocks.

Example : "W" AREA_WALL        ; All the W's in the map will be a solid wall
                               ; Comments can be placed using the ; symbol.

Next, the graphic must follow ( 8 x 8 pixels ). 8 pixels on each line.
Represented by hexadesimal numbers. 255 = FF and so on.

Example : "W" AREA_WALL

          FF FF FF FF FF FF FF FF       ; This will create a wall with one
          FF FF FF FF FF FF FF FF       ; color. Color 255.
          FF FF FF FF FF FF FF FF
          FF FF FF FF FF FF FF FF       ; The palette consist of 16 colors
          FF FF FF FF FF FF FF FF       ; with 16 shades of each.
          FF FF FF FF FF FF FF FF       ; 0F will be White.
          FF FF FF FF FF FF FF FF       ; 04 will be a darker White.
          FF FF FF FF FF FF FF FF

After the graphics has been created, the map must came.
You must start with a "#MAP" on its own line.
Then followed by the map, which is 25 lines long and 30 characters on
each line.

Example :
         "W" AREA_WALL

         FF FF FF FF FF FF FF FF
         FF FF FF FF FF FF FF FF
         FF FF FF FF FF FF FF FF
         FF FF FF FF FF FF FF FF
         FF FF FF FF FF FF FF FF
         FF FF FF FF FF FF FF FF
         FF FF FF FF FF FF FF FF
         FF FF FF FF FF FF FF FF

         "." AREA_OPEN

         0F 0F 0F 0F 0F 0F 0F 0F
         0F 0F 0F 0F 0F 0F 0F 0F
         0F 0F 0F 0F 0F 0F 0F 0F
         0F 0F 0F 0F 0F 0F 0F 0F
         0F 0F 0F 0F 0F 0F 0F 0F
         0F 0F 0F 0F 0F 0F 0F 0F
         0F 0F 0F 0F 0F 0F 0F 0F
         0F 0F 0F 0F 0F 0F 0F 0F

         #MAP

         ..............................
         ..........................W...
         ..............................
         ......WWWWW.............W.....
         ..........W...................
         ..........W...................
         ..........W...........WW..W...
         ..........W...............W...
         ..........................W...
         ..............................
         ..............................
         ...........................W..
         ..............................
         ..............................
         ......WWWWW...................
         ......WWWWW...................
         ......WWWWW...................
         ......WWWWW...................
         ......WWWWW..........WWW......
         ..............................
         ..............................
         ..............................
         .........................WW...
         ..............................
         ..............................

         #END                            ; End with an #end command.

------------------------------------------------------------------------------

The ConfigFile    "JCBOT.CFG"
--------------

This file contains some configurations that you might change.
Here you will be able to change the map which must be used, ect.

Settings:

* MAPFILE   : The mapfile with extension.
              Ex. MAPFILE = JCBOT.MAP

* DEBUGFILE : File used for debug, when debugmode is true.
              Ex. DEBUGFILE = DEBUG.LOG

* DEBUG     : Toggles Debugmode. Can be TRUE/FALSE
              Ex. DEBUG = TRUE       ; Will set debugmode to true.

* AMMO      : The amount of ammo for each robot. This will also be the maximum.
              It can be between 0 and 100 included.
              Ex. AMMO = 50          ; Will give each bot 50 rounds of ammo.

* UNLIMITED_AMMO : Toggles the UnlimitedAmmo mode. Can be TRUE/FALSE
              Ex. UNLIMITED_AMMO = True ; The bots ammo won't get up.

* FIRE      : Sets the maximum number of bullets which can be in the air for
              each bot. Can be between 1 and 10 included.
              Ex. FIRE = 3      ; Each bot can have 3 bullets in the air.

              If this is set to 1. Then, If a bot shoots he must wait until
              that bullet reached its target, before he can shoot again.

End this configfile also with an #end command.

If there is no config file, the following defaults will be used.
MAPFILE = JCBOTS.MAP
DEBUGFILE = DEBUG.LOG
DEBUG = FALSE
AMMO = 50
FIRE = 5
UNLIMITED_AMMO = FALSE

------------------------------------------------------------------------------

The Compiler  "Compile.exe <RobotSource w/o extension> "
------------

The RobotSource File must have an extension of ".JC".

The Variables
-------------

There is only 3 types of variables in the bot-Language.
#INT,#STRUC,#PIC. The maximum length of a variable is 15 characters.
The first part of your program must contain the variables.


#INT <The Name of the variable>

Example : #INT  Direction      ; Declare a variable "Direction" of
                               ; Integer type. 16 Bit value.


#STRUC[ <Dimensions>: .. ]  <Name of variable>

Example : #STRUC[10:10] Map  ; Declares an array of integers.
                             ; The array will have 2 dimensions with
                             ; a depth of 10 each. The same as
                             ; " Map : Array [1..10,1..10] of integer; "
                             ; in Pascal

#PIC <Name of Variable>

Example : #PIC RobotPicture

          ...FF...           ; A picture that can be used for the robot
          ..FFFF..           ; Followed by this 8 x 8 grid.
          ...FF...           ; "." and "0" are transparent pixels.
          FFFFFFFF           ; "F" light color, "1" dark color.
          ...FF...
          ..FFFF..
          .FF..FF.
          FF....FF


PreDeclared Variables
---------------------

These variables is build in and there is no need to declare them.
They are read-only.

Constants
NORTH = 0
EAST  = 1
SOUTH = 2
WEST  = 3

AREA_OPEN   = 0;
AREA_WALL   = 1;
AREA_KILL   = 10;
AREA_ENERGY = 11;
AREA_AMMO   = 12;
AREA_ENEMY  = 2;

Variables
SCAN_DIST  : Contains the distance of the founded object.
SCAN_FOUND : Contains the founded object ( Use the AREA_.... constants )
VSCAN_DIST : Same as above but for the VSCAN command.
VSCAN_FOUND: Same as above but for the VSCAN command.
LOC_X      : Contains your current X position on the map.
LOC_Y      : Contains your current Y position on the map.
ENERGY     : Contains your current Energy (0 - 100).
AMMO       : Contains your amount of ammo.
CAN_FIRE   : Contains the amount of shots that can be taken until the
             maximum number of bullets in the air exceeds.
             Ex. If the maximum number of bullets in the air is 3.
             Initialy CAN_FIRE will then contain 3. If you shoot then
             it will be 2. If that bullet hits a wall, CAN_FIRE will
             become 3 again.

Labels
------

Labels is used when you want to jump/goto a certain position in the
program. (Create loops and stuff like that).

A Label can be up to 15 characters long.
When you use a label, there must be a ":" before it.

No other commands are aloud on the same line as the label.
Example:

:Do_Again
         Add    Count,1

         IF  Count < 5                  ; Repeat until Count=5
             Goto  Do_Again


The Code
--------

After all the variables has been declared, you must add a line which
contains "#CODE" and your code must end with an "#END".

Commands:
( Where something is stored, that must be a variable )

* MOV a,b       ; Sets the variable "a" to the value of "b".
                ; "b" can also be a variable or a number.
* ADD a,b       ; Adds "b" to "a" and store the result in "a".
* SUB a,b       ; Substract "b" from "a" and store the result in "a".
* MUL a,b       ; Multiplies "a" and "b" and store the result in "a".
* DIV a,b       ; Divides "a" by "b" and store the result in "a".
* AND a,b       ; Logical "and" with "a" and "b". Stores in "a".
* XOR a,b       ; Exclusive-or with "a" and "b". Stores in "a".
* OR  a,b       ; Logical "or" with "a" and "b". Stores in "a".
* NOT a         ; Logical "not" with "a". Stores in "a".
* PUSH a        ; Push the value "a" on the stack.
* POP a         ; Pops the top value in the stack into "a".
* GOTO <Label>  ; Goto the program position where "Label" is.
* GOSUB <Label> ; Goto a subroutine in the program at "Label".
* RET           ; Returns from a subroutine.

* IF a ? b      ; Checks "a" with "b" using "?". If it is true, then the
                  next command is performed, else the next command is skipped.
                  The "?" can be : "="   Equals
                                   "<>"  Not equal
                                   "<"   Less Than
                                   ">"   Greater Than
                                   "<="  Less Than or Equal
                                   ">="  Greater Than or Equal

* HALT          ; Kills the robot.
* RANDOM a,b    ; Generates a random number between 0 and "b".
                  Stores the result in "a".
                  Example : RANDOM  Direction,4
                  Stores a randomnumber in "Direction" which can be 0,1,2,3
* ROBO_PIC a    ; Sets the picture of your bot to the picture in "a".
* AMMO_PIC a    ; Sets the picture of your bullets to the picture in "a".

* WALK a        ; Walks in the direction "a". Where "a" can be 0,1,2 or 3.
                  If you walk into a wall, 1 energy will be lost.
                  If you walk into a robot, 2 energy will be lost, the
                  other bot will also loose 2 energy. (Cool, if you run
                  out of ammo).
* FIRE a        ; Fires a bullet into direction "a". Where "a" can be 0,1,2,3.
                  If you have no ammo, no bullet will be shot. The bullet
                  will travel until it hits a wall or a robot.
* SCAN a        ; Scans for any object in direction "a". The result is
                  stored in 2 predefined variables. SCAN_FOUND will
                  contain the value of the object found. Use the constants
                  that are available.
                  SCAN_DIST will contain the distance of the object.
                  It will be 1 if the object is only 1 block away.
* VSCAN a       ; Also scans, But only for robots. This will scan through
                  walls until it founds or a bot or is out of the map.
                  VSCAN_FOUND and VSCAN_DIST will return the values.

* OUT "a"    ; Used for debug. The string "a" will be saved to the debugfile.
* OUT a      ; Used for debug. The Value in "a" will be saved to debugfile.

------------------------------------------------------------------------------

How to run a battle
-------------------

1. First Compile the robots.
   Example : We have two robot programs "Random.jc" and "Mad.jc".
             So in DOS we type "Compiler Random" and then "Compile Mad".

2. Run the JCBOT program.
   Example : In DOS we type "JCBOT Random Mad". This will put "Random"
             and "Mad" in a battle.

The Result
----------
Example:

Random    0 : - 5 3 :  8 : 16
Mad      45 : 9 - 6 : 15 : 75
Killer    0 : 3 1 - :  4 :  8
  ^       ^     ^      ^    ^
  |       |     |      |    |--- The total score for each bot. (Shots*2+Energy)
  |       |     |      |-------- Total number of shots that did damage.
  |       |     |--------------- How many times did who shot who.
  |       |--------------------- Energy left at the end of the game.
  |----------------------------- Name of RobotFile.


------------------------------------------------------------------------------
THIS IS ONLY A BETA VERSION OF JCBOTS. THERE MIGHT BE LOTS OF BUGS WHICH
WILL BE FIXED IN FUTURE VERSIONS. IF YOU FIND ANY SERIOUS BUGS, MAIL ME
AT "S9805027@STUDENT.UP.AC.ZA" BETWEEN 1998-2001 OR AT "J_CRONJE@HOTMAIL.COM"

FEEL FREE TO GIVE THIS TO EVERYONE YOU KNOW. IT IS SHAREWARE. PLEASE
MAIL ME WITH ANY COMMENTS.

HTTP://WWW.GEOCITIES.COM/SILICONVALLEY/HAVEN/8434/
------------------------------------------------------------------------------
