                                FunkBots v1.15
                        The Ultimate Funk Experience(tm)
                                Copyright 1998

http://www.chebucto.ns.ca/~at555/

1) Legal Issues

2) What's New

3) Introduction

4) The FunkBot Battle

5) Battle Files

6) FunkScript

7) The Contest

8) Credits

9) The Future of FunkBots

10) Contacting Me


-----------------------------------------------------------------------------
1) Legal Issues
-----------------------------------------------------------------------------

You freely use and distribute FunkBots. It is copyrighted freeware. You may
distribute FunkBots, but ONLY unmodified with all files intact.

-----------------------------------------------------------------------------
2) What's New
-----------------------------------------------------------------------------

This is the third release of FunkBots. Here's what's new in v. 1.15:

-shot.x, shot.y, shot.speed.x, and shot.speed.y return their decimal
 places instead of being rounded off
-Scrolling around in large areas will not slow down the battle near as much
-Fixed define bug (where define x messes up robot.x)
-Bots can't cheat and modify/access data vars outside 0 - 999.
-All vars including data[] now set to 0 at start up
-You can now enter negative number, instead of having to use 0 - 2 for -2
-'else' statments added to 'if' blocks
-Bot names are now case sensitive.
-Nifty new title screen by Collin Kidder

New from v. 1.10:

-First of all, this section. Expect this in every update.
-You can now draw your own FunkBots! (see Battle Files section)
-Fixed some bugs in FBM files.
-Added rand[], total.robots, and robot.alive to documentation.
 I forget to mention them before (oops!)
-Added new variables: robot.total.hits, and robot.hits, and robot.kills
 (thanks to suggestion from bengt@playboj.com)
-Added some stuff to The Future of Funkbots
-Exponents (powers), and square root opperators
-Now 1000 data variables per robot instead of 100, and they're FLOATS!
-Adjustable screen resolution and battle feild size (for you who think the
 FunkBots are too big). Battle Field size is held in variables area.x
 and area.y
-define bugs fixed: you can put comments after them.
-Added debug variable (very usefull feature!)

Still to done (for v. 1.20)

-User controlled bots
-Function support

-----------------------------------------------------------------------------
3) Introduction
-----------------------------------------------------------------------------

This documentation is horrid. Sorry. I can't write. If you want to write
a tutorial or something PLEASE do so.

FunkBots is a program where robots, called funkbots, must fight each other
with artificial intelligence. The AI is provided by the player, you, by
programming it with a programming language called FunkScript. The main
purpose of FunkBots it for the contest that will be held, where everyone's
funkbots will fight. The winner of the contest will win a "mystery prize".

-----------------------------------------------------------------------------
4) The FunkBot Battle
-----------------------------------------------------------------------------

Run the program file, fb.exe. Press enter at the title screen, then you can
watch an example battle. Press up and down to scroll the stats at the left.
Press Escape any time to quit. If the graphics or sound aren't working like
they should, read section 4, Battle Files.

You will notice square items popping up occasionaly. These give the FunkBots
ammo or energy. Here is what every item stands for:

N:  Normal ammo
P:  Power ammo
S:  Seeking ammo
PS: Power Seek ammo
M:  Mine ammo
PM: Power Mine ammo
1:  Gives the FunkBot +1 energy
2:  Gives the FunkBot +2 energy
5:  Gives the FunkBot +5 energy

The circles that fly around the screen are ammo being shot. Here is a
description of each:

------------------
Dark Green: Normal
------------------

This goes in a straight line to it's destination, then keeps going. If it
hits a FunkBot, it explodes and the FunkBot loses -1 energy.

------------------
Light Green: Power
------------------

Like Normal, but takes off -2 energy.

-----------------
Dark Red: Seeking
-----------------

This starts off towards it's destination, but it is allways slowly turning
off course towards the closest FunkBot (not including the one that shot it).
A nasty attack. -1 energy.

---------------------
Light Red: Power Seek
---------------------

Like Seeking but -2 energy.

---------------
Dark Blue: Mine
---------------

If this reaches it's destination without hitting a FunkBot, it stays there,
ready for a FunkBot to run into it. -1 energy.

----------------------
Light Blue: Power Mine
----------------------

Like Mine, but -2 energy.

The words to the left give info about every FunkBot. Press up and down to
scroll through them. It tells you it's name, number, x and y location,
energy level, and how much ammo it has of all types.

The FunkBots themselves have two numbers on them. The white one is it's
number, corresponding to the left, and the black is it's energy.

When there is only one FunkBot left, the battle is over. Press Enter or Esc
then to quit.

If the battle field is larger than what can be displayed on current screen,
use the mouse to scroll around.

-----------------------------------------------------------------------------
5) Battle Files
-----------------------------------------------------------------------------

Battle files are used to set up the battles. They are ASCII text, and can be
created and edited with any text editor like MS-EDIT or Notepad for Winblows.
Use EDLIN if you're a freak.

The file default.btl is used unless you specify otherwise. Tell it what file
to use with the command line. For example:

fb myfight.btl

Will run FunkBots with myfight.btl as the battle file.

The battle files are made up of this=that statements. Each must be at the
very left of the line with no spaces. For example:

robot=basic.fb

Here is every option you can enter and what it does:

robot=file.fb

  This adds a FunkBot to the battle. You can have up to 256 in each battle.
  Add a new robot= for each FunkBot.

image=file.pcx (***NEW!!!***)

  If you put this directly below robot=, that robot will use the specified
  image file for its graphics. This must be in 256 color (8-bit) BMP, PCX, 
  LBM, or TGA  format. It also must be 30x42 pixels and use the game 
  palette. You can rip the palette from the example images, pimp.bmp or 
  funky.pcx. Color 0 (it's pink in the palette), will be set as transparent.

game.speed=#

  This sets the number of Cycles Per Second the game runs at. The default
  it 60.

robot.energy=#

  The amount of energy each robot starts with. The default is 20.

item.delay=#

  The number of cycles before a new item appears. A cycle is when every
  robot's FunkScript is done once. The default is 60.

normal=#, power=#, seeking=#, power.seek=#, mine=#, power.mine=#,
energy.1=#, energy.2=#, energy.5=#

  The sets the "chance" for each item type. The chance is used to decide
  what type a new item is. For example, if you say normal=5, and total of
  all the chance values is 21, then there is a 5 in 21 chance of a new item
  being normal ammo. The chances cannot total more than 300. The default
  values respective to above are: 10, 10, 10, 10, 10, 10, 10, 10, and 3.

rec.movie=file.fbm

  This saves the battle as a FMB (FunkBot Movie) file so you can watch it
  over, and over, and over, and over, and over agian.

play.movie=file.fbm

  Plays back a FBM file. When playing a FBM the only other battle file
  options that count are game.speed=, video=, sound=, and res=. The 
  FunkScript and custom graphics (if there are any) are saved in the 
  file, so you can play an FBM file without them.

res=# (***NEW!!!***)

  Set the screen resolution.
  0 - 640x480 (default)
  1 - 800x600
  2 - 1024x768
  3 - 1280x1024
  4 - 1600x1200

area.x=# (***NEW!!!***)

  Set the x size of the battle field. The default is 538. If you want it
  to fit the screen perfectly make it x resolution - 102.

area.y=# (***NEW!!!***)

  Set the y size of the battle field. The default is 480. If you want it
  to fit the screen perfectly make it equal the y resolution.

video=#

  If FunkBots autodetects your video setup wrong, then you can tell it what
  to use. Here is what number to use for what:

  0: AUTODETECT (default)
  3: VESA1
  4: VESA2B           
  5: VESA2L            
  6: VBEAF            
  7: XTENDED         
  8: ATI              
  9: MACH64            
 10: CIRRUS64          
 11: CIRRUS54          
 12: PARADISE          
 13: S3                
 14: TRIDENT           
 15: ET3000            
 16: ET4000
 17: VIDEO7            

   3, 4, or 5 are your best bet.

sound=#

  You can tell it what sound card to use.

 -1: AUTODETECT (default)
  0: NONE   
  1: SB               
  2: SB10             
  3: SB15             
  4: SB20             
  5: SBPRO            
  6: SB16             
  7: GUS             
  
The first screen that comes up at first shows all the options that are set.
It also shows all the robots and their x and y locations (set randomly).
Press up and down to scroll through them.

Battle files are completely case insensitive. Anything it doesn't
understand is just ignored.

-----------------------------------------------------------------------------
6) FunkScript
-----------------------------------------------------------------------------

Like the battle files, FunkScript is written in ASCII text. It is a mishmash
of C and BASIC. I assume that if you are attempting to program a FunkBot
that you have programming experience.

You can assign values to debug, robot.x, robot.y, and data[#]. The [#] means
that data needs an index value. This can be any valid value statement (see
below). The data's are used to store any values you need to keep track of.
The format for assigning is:

robot.x = value

where value is any valid value statement (see below). You need a space on
either side of the =. Here are some examples:

robot.x = (2 + 4) * item.x[2]
data[2 + data[1]] = 3

A FunkBot can only move 1 pixel left or right and 1 pixel up and down every
cycle. For example, if at the end of the FunkScript its x value is 5 more
than it was, it will be reduced to only 1 more.

Value statements can be any mathematical equation using numbers, variables,
operators, and parentheses.

The valid operators are: 
^ (power), + (addition), - (subtraction), * (multiplication),
/ (division), % (modulus/remainder), < (less than), > (greater than),
<= (less than or equal to), >= (greater than or equal to), = (equals),
<> (doesn't equal), && (and), || (or).

The following variables can be used:

robot.x[#] - # refers to which robot. It gives the x location
robot.y[#] - y location
data[#] - whatever you assign to them. You can use 0 - 999.
robot.energy[#] - a robot's energy
robot.ammo[robot][type] - gives how much of "type" ammo "robot" has
robots.alive - how many robots are alive
robot.alive[#] - equals TRUE (1) if # is alive, FALSE (0) otherwise.
robot.hits[robot1][robot2] - how many times robot1 has hit robot2
robot.total.hits[#] - how many times a robot has hit any other robot
robot.kills[#] - how many other robots robot # has finished off 
total.robots - how many robots there are, alive or dead
item.delay - the item delay set in the battle file
num.items - number of items on screen
item.chance[#] - set from battle file
item.x[#] - x location of an item
item.y[#] - y location
item.type[#] - the type of an item
num.shots - how many shots are on screen
shot.x[#] - x location of a shot
shot.y[#] - y location
shot.speed.x[#] - the number of pixels a shot moves every cycle (+ or - a #)
shot.speed.y[#] - y speed
shot.type[#] - the type of the shot
area.x - the x size of the battle field
area.y - the y size
rand[#] - produces a random number from 0 to # - 1.
sqrt[#] - returns the square root (why is this considered a variable and not
  and opperator? Because it's treated like a variable... not an opper.)
debug - This is used to debug your FunkBot. The value of this is displayed
  at the left during the battle with your robots stats. (D:0.0000) 
  How is this usefull for debugging? You figure it out ;)

Note that when using robot.x and robot.y to assign a value to it, you don't
use an index value, but in any other case you do.

The data[] variables and debug can have decimals, but anything else will be
rounded off. For some reason if you assign something like 43.423 it will 
change to 43.42299010. This isn't that big of a deal, but I'll try to fix
it. 

There are also the following constants: normal, power, seeking, power.seek,
mine, power.mine, energy.1, energy.2, energy.5, and me (equals the # that
that FunkBot is).

Here are some examples:

1 + 3
(2 + 2) * 3
robot.x[me]
robot.x[data[3]]
item.type[num.items]

Opperators:

^ raises left side to the power of right side
+ adds the values on either side
- subtracts
* multiplies
/ divides
% modules (remainder of left side divided by right)
>, <, <=, >=, <>, =: If it is true (ex: 4 > 2) then it equals TRUE (1),
otherwise FALSE (0).
&& If both values are TRUE (nonzero), then it equals TRUE
|| If either value is TRUE, it equals TRUE.

ex:
4 > 2
3 + 2 < 3 % 2
robot.x[me] < 100 && robot.y[me] < 100

The order that the opperators are done is:
^
*, /, %
+, -
>, <, >=, <=
=, <>
&&
||

Opperators on the same line are done at the same time, from left to right.
The order can be overridden with parentheses:
(3 + 3) * 2 is different than 3 + 3 * 2

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

"If" statements are used to only execute blocks of code if certain values are
true.

The syntax is:

if (value)
  ...
endif

if value is TRUE (nonzero), then all the code before endif is executed. if
it is FALSE, then the code is skipped up to endif.

For example:
if (robot.x[me] > 100)
  robot.x = robot.x[me] - 1
endif

Nested "if"s are aloud:

if (value)
  ...
  if (value)
    ...
  endif
  ...
endif

The ( and ) around value are optional.

You can also put 'else' statements in 'if's like this:

if (value)
 ...
else
 ...
endif

If value is TRUE, then the code between 'else' and 'endif' is skipped.
You can nest multiple if/else statements together to test multiple
conditions:

if (value)
 ...
else
  if (value)
    ...
  else
    if (value)
      ...
    endif
  endif
endif

It can be rearanged more like the way in BASIC, to make it easier
to read:

if (value)
  ...
else if (value)
 ...
else if (value)
 ...
endif endif endif

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

Loops are done like this:

do
  ...
  break
loop

At loop, it goes back to do, so all the code in between is repeated over and
over. Use break to leave the loop.

ex:
do
  data[0] = data[0] + 1
  if (data[0] > 3)
    break
  endif
loop

Nested loops are aloud.

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

To shoot you do this:

shoot ammotype x_dest y_dest

for example
shoot normal 0 0
would shoot a Normal shot with 0, 0 as it's destination.
You can only shoot once every 30 cycles.
Attempting to shoot when you have no ammo or 30 cycles haven't passed does
nothing.

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

You can place comments in your FunkScript with semicolons (;)
Anything on a line after a semicolon is ignored.

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

FunkScript is completly case insensitive. You must have spaces between
everything except [, ], (, and ). Indenting is only for legibility. Also,
you can put enters whenever you want. If fact, each line can only be 80
chars long, so if a command needs to be longer just continue it on the next
line.

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

define can be used to use symbols to replace things. For example:

define blah data[3]

Put that at the start of the FunkScript and you can put blah anywhere and it
will be replaced with data[3]

-----------------------------------------------------------------------------
7) The Contest
-----------------------------------------------------------------------------

I am holding a contest where your FunkBot will compete against other
FunkBots. See the FunkBot homepage for more information.

-----------------------------------------------------------------------------
8) Credits
-----------------------------------------------------------------------------

-FunkBots is designed and programmed by Jonathan Sharkey.
-It is written in C and compiled using Djgpp by DJ Delorie.
-It uses Allegro by Shawn Hargreaves for graphics and sound code.
-The linux version is ported by Michael Smith.
-All graphics are by Jonathan Sharkey except for the explosions, which are
 from the Allegro demo game by Shawn Hargreaves, and the title screen, by
 Collin Kidder.
-All sound except for the item "pop" and "funky" are from the Allegro demo
 game by Shawn Hargreaves.

-----------------------------------------------------------------------------
9) The Future of FunkBots
-----------------------------------------------------------------------------

If FunkBots is successfull, FunkBots 2 will happen. Here is how I envision
it:

-The battle fields will be made out of cubes to form a 3d environment. 
 Each cube space will either be empty or filled with a block type. Some 
 types might be: normal, ice (low friction), sticky (high friction), 
 rubber (velocity after smashing into it is more than when you hit it), 
 poison (hurts you). You could also create your own custom block with the 
 battle editor, and edit options like friction, bounciness (don't know the 
 term), etc. A block with a negative friction would be interesting ;) You 
 will be able to create random and custom battle fields.

-You will shoot with a cannon. You will be able to rotate it 360d, move it 
 up and down 90d (90=up, 0=straight). You will then be able to shoot with 
 a specified velocity.

-Your funkbot will have wheels which can be tighted and loosened to change 
 friction. To move you would call a function to increase or decrease your 
 velocity. Negative velocity would mean moving backwords. You can also 
 rotate 360d

 Another option is that you don't rotate, but boost yourself in a 
 specified direction. I'm not sure which I will do yet. (Mabey both?)

 In either case you couldn't make yourself start moving at 5m/s an expect 
 to stay like that. You'd have to keep calling it, other wise you'd stop 
 from the friction.

-Gravity will be adjustable, with a default of 9.8m/s

-Rather than getting items, you will use gain a certain amount of fuel 
 each turn. You can spend this fuel as you like, or save it. Everything 
 you do, shoot, move, etc., will require fuel.

-You be able to use other built in robot features such as parachutes, 
 radar, and nothing else comes to mind right now... any ideas?

-You will right the FunkScript in C, and it will be compiled with a C
 compiler.

I would like suggestions about what you would/wouldn't like to see in
FunkBots 2. Also let me know if you would interested in working on it. It
would be great it there was a whole team of people working on it; it could
end up really good!

-----------------------------------------------------------------------------
10) Contacting Me
-----------------------------------------------------------------------------

Email Jonathan Sharkey: at555@chebucto.ns.ca
Email Michael Smith:    aa529@chebucto.ns.ca
FunkBots homepage:      http://www.chebucto.ns.ca/~at555/

Contact me for:
-Questions
-Suggestions
-Comments
-To enter the contest (also tell me if you plan to in the future, I want to
 know!)
-If you spot a bug (this is still the beta version!)
-Anything else
