JsBilla short documentation

Jari Kärkkäinen
2009-02-18

1. Why oh WHY?
2. Features
	2.1 Gamefield and balls
	2.2 Language changer
	2.3 Difficulty switcher
	2.4 Hall of fame
	2.5 Ajax
	2.6 API	
3. Demos
4. Licensing

1. Why oh WHY?
JsBilla is ball catching game where goal is to gather all balls into ballsack by
clicking on them.
After completion score can be saved. Lower the score better is the player.

Game is also a demonstration of javascript possibilities when some OOD/OOP thinking 
is applied into design. This should not be a big deal, after all the whole language
is based on DOM. Regrettably js has a reputation that causes in most of us feelings
somewhere between horror and repulsion. This obviously has something to do with js
history of poor DOM support in major browsers.   

2. Features
JsBilla can be instantiated as game. There is gamefield with given amount of balls,
language changer that changes game language even when game is on, game difficulty
switcher and simple hall of fame display.
Default layout of game can be modified with CSS and JsBilla object getters.
Game points are saved and retrieved using ajax.

Game can also be instantiated as just for fun bouncing balls by changing
global isGame variable value. Then many balls just bounc rapidly.

	2.1 Gamefield and balls
	Gamefield is table element where balls, effectively span elements, are
	placed. Balls travel diagonically in 45 degree angle across field and 
	take a 90 degree turn when hitting a wall, except in corners turn is
	180 degrees. Balls do not bounce from other balls.
	Balls are attached with onclick event that moves clicked ball into ballsack.
	
	2.2 Language changer
	Language changer gets languages from lang.js file. Each language is 
	associative	array of strings. For each language a button is created 
	into language changer area. Buttons are associated with onclick event
	that sets new language for game.
	
	2.3 Difficulty switcher
	Game difficulty is determined by number of balls and their speed. Game
	difficulty levels are defined in hardness.js. Mid game changing of 
	difficulty resets the game. Difficulty is controlled by selecting
	approbriate radio button.
	Each level has its own hall of fame.
	
	2.4 Hall of fame
	Hall of fame shows best scores played. Scores are updated in fixed
	intervals.
	
	2.5 Ajax
	Game has simple ajax functionality defined in ajaxfunctions.js. Points
	are saved and retrieved asyncronously. Request spamming is controlled
	using changing spamcode. Spamcode does not prevent cheating.
	Ajax functions use only XMLHttpRequest so support for older IE versions
	is dropped intentionally.
	Server side handling is done with AjaxBackEnd  PHP class defined in 
	ajaxbackend.php. 
	
	2.6 API
	There is none. Codebase is short and simple and should be easily studied
	with any level of programming experice. Some comments or hints of
	usage are inserted into index.html and gamefunctions.js. When studying
	start from gamefunctions.js.

3. Demos
In demos visual layout is rather ugly, but that is intentional. Bright
colours are used to show different sections in game.

Playable demo is at http://chioctodon.net/grabmyballs/ and
for fun demo is at http://chioctodon.net/grabmyballs/?isgame=0

4. Licensing
JsBilla is published free of charge under MIT License, see license.txt.