Botswana

A web-based game with programmable bots (in Javascript). Live demo here.

Usage

Choose the bots you want to fight (and you can add custom bots via URL)
If you want to use a different ruleset, add it via the box at the bottom
Press Start.
Hit the space bar to pause.

Included bots

Crusher
Destroyer
Dumbo: very simple bot
Teleporter: for use with teleport ruleset
SampleBot: empty bot
Xavier

Included rulesets

default
demo1: smaller bots, set obstacles, set initial placement, various parameter tweaks
demo2: completely redone drawing code
demo3: faster bullets, different look, CSS 3D transform
conveyor: different strips of the world move bots up or down
expulsion: adds teleportation circle in center of world, varying bot radii
orbit: bots orbit around the center point
teleport: adds "teleport" command (see the Teleporter bot)
walls: moving walls, larger world

How to write a bot

All bots inherit from the parent Bot class in bots/bot.js. A bot script will be instantiated a number of times, depending on the ruleset.properties.bots.botsPerTeam value.

Properties of the parent bot class

name: team name
id: numeric id
x, y: coordinates of the bot's current location
color: the assigned team color (from the ruleset)
angle: the bot's current angle in radians
radius: size of bot
health: from 0 to 100
alive: boolean
weapons: object with number of remaining ammo for each weapon type
canShoot: boolean
waitFire: number of clicks to wait before firing
collided: boolean
hitByBullet: boolean

Methods exposed by the parent bot class

this.distanceToPoint(x1, y1, x2, y2): returns distance from point 1 to point 2
this.myDistanceToPoint(x, y): returns distance from the bot to the point
this.getDirection(target, threshold): basic pathfinding helper function. Uses fields to avoid obstacles. target needs to have x and y properties (point, bot, etc.). A threshold of 0.05 works well. Returns an object:
- response.command: the bot command needed to move closer to the target
- response.angle: the angle to the target

Bot script template

The minimum code required for a bot:

var NewBot = function() {};

NewBot.prototype = new Bot();

server.registerBotScript("NewBot");

If you want your bot to be named something different from the class name you've used, pass a second parameter to the server.registerBotScript function:

server.registerBotScript("NewBot", "Noob");

The game engine calls each bot's setup() function at the beginning of the game.

NewBot.prototype.setup = function() {
	// Do stuff here
};

And then each click, it calls the bot's run() function. This is where the bulk of the bot logic should go.

NewBot.prototype.run = function() {
	return { command: 'wait', team: {} };
};

The run() function returns an object with two properties:

command: the bot's command for this round (a string). Default commands (rulesets may add or modify commands):
- forward
- backward
- left
- right
- fire
- mine
- strafe-left
- strafe-right
- wait
- self-destruct
team: an object that will get sent to the other bots on the team. You can access it via this.state.payload.

State available to bots

A list of properties available under this.state:

world: a copy of ruleset.properties.world. In general, there are width and height properties that let you know how big the world is.
bots: an array of all the currently living bots.
- id: bot's unique ID (integer)
- name: bot's team name
- x and y: bot's location
- angle: angle the bot is pointing
- health: the current health of the bot (0–100)
obstacles: an array of all the obstacles. Each obstacle has the following properties:
- x and y: coordinates for the upper left corner of the obstacle
- width: width of obstacle
- height: height of obstacle
items: an array of all the items. Each item has the following properties:
- x and y: coordinates for the center of the item
- radius: radius of item
- type: type, currently only health and ammo are supported (but rulesets may add new items)
weapons: an array of all the weapons currently in play. Each weapon has the following properties:
- x and y: weapon's location
- angle: angle the weapon is pointing
- owner: ID for the bot who fired the weapon
- type: string, currently only bullet and mine are supported (but rulesets may add new weapons)
payload: object passed in via the team property returned from the bot's run() command

How to write a ruleset

Custom rulesets allow you to modify game parameters and dynamics.

Custom ruleset template

Minimum code required for a custom ruleset:

var ruleset = new Ruleset(server);

ruleset.name = "customrulesetname";

// Ruleset tweaks go here

server.setRuleset(ruleset);

Anything in the ruleset is tweakable. For example, to change existing properties or add new ones:

// Tweaking an existing property
ruleset.properties.botsPerTeam = 5;

// Adding a new property
ruleset.properties.confundusCharm = 10;

To add a new command (see teleport):

// Adds "pulse" as a command available to bots
ruleset.commands.pulse = function(bot) {
	// Do things
}

And since it's an HTML/CSS game, you can also include DOM changes (see demo2):

$("body").css("background", "#f00");	// Don't do this

Available properties

properties
- weapons
- items
commands
- If a command moves a bot, it should return a position object; otherwise it need not return anything.

Available functions

resetGame(): called at the beginning of a new game
registerBotScript(teamNum, botScript, name): registers a new bot script (you generally won't want to change this)
generateObstacles(): returns array of obstacles (objects with x, y, width, and height properties)
generateItems(): returns array of items (objects with x, y, radius, and type properties)
initializeBot(bot, id): initialize bot (you generally won't want to change this)
postInitBot(bot): post-init per-bot setup hook
setInitialPlacement(bot): sets bot.x and bot.y at the beginning of each game
initializeGame(): game init hook
startRound(clicks): called at the beginning of each round
resetCollisionFlags(bot): resets collision flags
updateFlags(bot): updates bot flags and counters
updateBot(bot, pos): hook to allow the server to move bots (see orbit, conveyor)
parseCommand(command, bot): parses command (you generally won't want to change this)
checkCollisions(bot, newPosition): checks for collisions
postProcess(bot): called after each bot is processed
endRound(): called at the end of each round
gameOver(): returns true or false depending on if game over conditions have been met
getWinner(): returns name of the team who won
getHealth(): returns array of combined health for each team

Drawing functions

These are part of ruleset. To add new functions, modify draw.world().

draw.world(): draws everything in order (clear, backgroundLayer, health, obstacles, bots, weapons, particles, foregroundLayer)
draw.clear(): clears the canvas
draw.backgroundLayer(): draws the background layer (default ruleset draws a grid)
draw.foregroundLayer(): draws the foreground layer (default is nothing)
draw.obstacles(): loops through obstacles and calls draw.obstacle for each one (you probably won't need to modify this)
draw.obstacle(obstacle): draws an obstacle
draw.items(): loops through items and calls their callbacks
draw.bot(x, y, angle, color, radius, health): draws a bot
draw.weapon(x, y, angle, type, owner, obj): draws a weapon (bullet, mine, etc.)
draw.particles(): loops through particles, runs the decay on each (TODO: move this out of drawing code), and calls draw.particle for each one (you probably won't need to modify this)
draw.particle(particle, newPos): draws a particle
draw.health(): modifies the HTML elements that store the health
draw.paused(): draws the paused state (dark overlay, white pause icon)
draw.endgame(winner): draws the endgame state

Drawing properties

These are part of ruleset.

draw.width: if you modify properties.world.width, modify this as well
draw.height: if you modify properties.world.height, modify this as well
draw.ruleset: makes the ruleset object available to drawing code
draw.server: makes the server object available to drawing code

bencrowder/botswana