This is the documentation file of the billiards game ANOTHER POOL (V 0.981).
[ copyright (c) by Gerrit Jahn, (http://www.planetjahn.de) ]

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

Contents:

1.      General Informations

2.      
 2.1    The Keys
 2.2    Command Line Options
 2.3    The File "Const.dat"

3.	Rules 
 
4.      
 4.1    Known Bugs
 4.2    TODO
 4.3	Changes
 
--------------------------------------------------------------------------

1.      General Informations


	"Another Pool" tries to simulate a classical pool game like
	8-Ball with 16 Balls, (white, black, 7 striped, 7 filled balls 
	(here: red and yellow)) on a 6-to-8 feet-table. 
	The (original) rules have been slightly modified to be easier
	implemented.
	Another Pool was compiled with GNU-C 2.57 and uses cbgrx 2.0 (alpha-
	release).
	The Linux-Versions have been compiled using gcc 2.95.3 and
	the SDL-graphics-library (www.libsdl.org)
	
	As mentioned above, Another pool tries to simulates billiards 
	as realistic as possible.
	It is possible to put spin on the white ball and change the angle 
	between cue and table. Therefore you should be able to play 
	curve-balls. The balls will roll in an allmost natural way.
	On "normal shots" (that is no spin), the balls will slide in
	the beginning and thenn start continuosly to roll after some time
	left until they roll on the surface. Therefore the balls won't do
	simple elastic shots but for instance one ball will roll in his
	direction after hitting another ball at his centrally after a shot
	period of acceleration.
   
	If you want to start the game, the files konst.dat and table.dat 
	must (!) be in the same directory as apool.exe. For the DOS-Version
	go32.exe must be as well in this directory or in the path-environment. 
	The .fnt files should be also in the apool-directory.
	
	By the way: it's not cool to run this program on computers < 486 ;-)

	Cool ;-) A bit outdated for now. Since we now have 2002, the
	game will work properly on allmost every computer. 
	If the graphics are to slow, you may change some parameters
	line step and timestep in the file konst.dat.
	
-------------------------------------------------------------------------

2.



2.1     The Keys

	During the game the following keys will cause an action: 

	 c:     computer plays for actual player
		(until you press any key if the computer plays or  
		"c" again if you are playing (not the computer).

		buggy in the linux version for now (seg-fault)
		
	 e:	press "e" and move mouse to change the "hit-point" on
	 	the white ball, which causes spin (back-, top, side-spin).
		If you have a mouse with three buttons, you may press
		the middle button instead.
		
	'+' or '-':	change angle between cue and table. If you do
			this and change the hitpoint (--> 'e'), too, you
			will perhaps play a "curve-ball".
			If you use a three-button-mouse you may 
			hold the middle button then press the right
			button to do the same... If you have a wheel
			mouse, you may use the mouse-wheel to 
			change the angle.
		
	 x:     computer plays only one shot for actual player
	 	
		Linux: s. c:

	 d:     start computer-demo
		(in demo-mode: press any key to stop demo)

		Linux: s. c:

	 w:     white ball rolls to mouse-cursor (test-procedure)
	 
	 W:     another computer-help (also a test-procedure)
	 	doesn't work correctly.
	 
	 u:     undo last shot (no redo implemented!)
	 
	 r:     "slow motion"-mode on/off. Just sets the graphics-refresh
	 	rate down.
	 
	 s:     show statistics.
	 
	F1:     help

	F2:     credits

    ENTER or SPACE: same as left mouse button

	 n: new game
	 
       ESC: "fast" quit game (works in allmost every situation)
       
	 q: show statistics before quitting the  game
	  
	  	Linux: nothing happens, except quti.
	  
	 if you're asked to press "any key" during the game, press a n y 
	 key   E X C E P T   "ESC" !!! (ESC quits!) You may also
	 press a mouse button.
	 
	 Most keys work only when the game is waiting for you. Some 
	 special keys like ESC work during the game, too.
		 

	 
2.2      Command Line Options

!!!
     If the game will flicker too much or the balls won't slide softly
     you can try to change the values of steps and time_step.
     You also might do this, if the game is too fast on your machine ...
     									  !!!
	"apool 16"  (DOS only)
	  starts billard in standard vga mode (640*480-16). May work, 
	  although you don't have a vesa-compatible graphics-card. (May
	  even not ;). Since V0.98: Std.-VGA is very slow! :-(
 
	 "apool" 
	   enables 640*480 256 SuperVGA-Mode. Needs a vesa-driver (see 
	   video.bat) or a vesa compatible graphics card. Is (lots of) 
	   faster then standard vga.

	   Linux: 800x600 for now in 32bit-Color-Mode.

	 "apool -xy Xres Yres" 
		 The default size of the apool Window is 800x600. with "-xy" one
		 can change this to an arbitrary size. The size of the balls and
		 the table will be arranged in a reasonable way.

2.3     The File "konst.dat"

	This file contains all the "physical" constants the game needs. 
	you can easily change them and see what happens...

	konst.dat has the following structure (DOS-Options for example):
	
	0.0000001       alpha	transformation gliding <---> rolling (-> spin)
	0.0001	        beta	friction that decreases z-spin
	0.2	        gamma	decrease of Spin when ball hits a side
	0.000000025     delta	rolling- / gliding-friction
	0.75            eta	1-loss of spin by transf. from spin -> speed
	0.4	bandes		intersection z-spin <--> sides --> speed
	0.9	banderef 	decrease of speed when hitting a side
	0.75	bandez		bandes<bandez<1 !; decr. of z-spin at sides
	1.0	mass_white	mass of the white ball (others: 1.0)
	1	step		painting new after 'step' calculations steps
	6	clev 		"level" of computer-op., (deepness of combies)
	3.75	curves		how strong "breaks" ball (perp.) out,(p.c.-b.)
	3.75	curvep		h.s.b.b. (parallel.) out,(playing curve-balls)
	64536	time_step	t.-freq.= 18.2 t/s * 65536 / (65536-time_step)

description: 
	
	-alpha: if you kick a ball it won't roll first but glide/slide. 
		alpha describes how fast the transformation from gliding/
		sliding to rolling will be.
	
	-beta:  if you don't hit the ball in the center it gets spin.
		beta is the factor, how fast the spin around the z-axis
		decreases. (a kind of friction, don't know the english name,
		in german you say "Bohr-Reibung", means drill-friction)

	-gamma 	describes the loss of the z-spin, when a ball hits a side

	-delta: "rolling- /gliding-friction"; describes, how fast the
	        velocity of the balls decreases.
		
	-eta:   describes the loss of energie by transforming rotation (spin)
		to velocity.
		
	-bandes:        Describes the influence of the z-spin at the cushions.
		 
	-banderef:      the loss of speed, if a ball was reflected by a
			cushion.
	
	-mass_white:  	the mass of the white ball (the other balls have the
	              	mass 1).
	
	-step:	describes how often the program paints all the balls new.
		50 means that the program paints after 50 calculation-
		steps. If you have a computer faster than a 486DX2-66,
		you may decrease the value of step, to get smoother graphics. 
		(e.g.: P5-100 : 15-25, DX2-66 : 50).
		A change of "step" must follow a change of "time_step", 
		to keep the initial game-speed.
		
	-clev:  describes how "deep" the computer-opponent thinks. 2 means
		that the computer will play combinations with 3 balls, ...
		change clev to 0 and look at the result.

	-curve(s/p):	if you (in the game) press the middle button and then
	        	the right button, you can change the angle between
			the table and the queu. If you now change (with only
			the right button) the hit-point on the white-ball, you
			can play curve-balls. curve(s/p) describes, how strong
			the ball breaks out. (curves: perpendicular, curvep:
			parallel)
		
	-time_step:	the "frequency" of the timer (s. timer). you get
			the "real" frequency by calculating
			f = 18.2 / s * 65536 / (65536 - time_step).
			If you increase the value of time_step, the game
			may become more "smooth", check this out!
			(s. "step")
			
-----------------------------------------------------------------------------

3.	Rules

	- Kick off, Place Cue-Ball:
	
	  In the beginning of the game you or your opponent have to kick off:
	  
	  The player who begins can place the cue-ball anywhere in the left
	  quarter of the table (same procedure if the white ball disappears).
	  After this, you can set power and spin with the right/middle mouse
	  button and shoot with the left button. 
	  
	- Choose Color:
	  
	  In a new game, you can hit any balls except of the black one.
	  If you pocket a ball correctly (without fouls), you 'choose' the
	  color of this ball.
	  You have to play this color until the ende of the game.
	  
          If no color is chosen and you sink balls with different colors,
	  you can play again (and choose again if you sink another colored
	  ball).
	  
	  If no color is chosen and you pocket a colored ball and make a 
	  foul at the same shot your opponent plays the next shot (and 
	  can 'choose', if he pockets a ball).
	  
	- Black Ball
	
	  If you have pocketed all 'your' balls, you have to play the black
	  one (without any foul!) in a hole to win the game.
	  If you shoot the black one in a hole by making a foul, you lost
	  the game.
	  If you play the black one too "early" in a hole, you lost the 
	  game, too.
		  
	- Freeball, Fouls
	
	  If your Opponent makes a foul, you have a `freeball'. That means,
	  you can hit ANY ball first (including the black one) and shoot
	  ANY ball in a hole (excluding the black one, except you MUST play
	  the black one).
	  
	  If you don't make a foul and don't pocket a ball (after your 
	  opponent has made a foul), you will have an 'extra-shot', a 
	  second chance, the punishment for the foul of your opponent.

	- The following actions are fouls:
	
	-- pocketing the white ball.
	-- hitting first another ball than one of 'yours'.	(e.f.)
	-- pocketing wrong colored balls.			(e.f.)
	-- the white ball doesn't hit another ball.
	-- no ball hits a cushion.

	(e.f.) means: except you have a freeball
	
	 - The Loser kicks off the new game...

	 
	( maybe implemented in one of the next versions: 
	  - Fouls: 	if a player kicks off and less than 4 balls hit the
	   		cushions  and no ball rolls in a pocket.
	  - Rule: 	the black ball has to be pocketed in opposite to the 
	          	position of the last pocketed ball of the players
			color. )
	
	 
-----------------------------------------------------------------------------

4.

4.1     Known bugs: 

		- balls flicker if moving. not under linux.

4.2  TODO:

	- changes in physics enginge
	- more reasonable use of time-control ;-)
		
4.3	Changes since version 0.97

	In V 0.975:
	- The handling of spin (english?) works now "physically" correct.
	  Depending on this the "rolling" of the balls works better.
	- Some "fine-work" on the geometry (holes, sides).
	
	In V 0.98:
	- Timer-dependent painting, the game will NOT increase speed anymore
	  if some balls are pocketed.
	- Some bugs "at" the sides removed.
	- If wanted, a "special-S3-version" (faster, "smoother" graphics) 
	  can be compiled. (with -DS3 at gcc ... -c graphics.c -DS3)
	  If anybody is interested in this, he/she may send me a mail ...
	
	In V 0.981:
	- spin and angle between cue and table now can be changed via keyboard
	  (not only with the middle mouse button, as ordinary Microsoft-Mice
	  don't have one), keys: "e" + mouse-move, "+/-".
	
	in V 0.982:
	- linux version availabe. Size of the windows under linus ist
	  customizable. some minor corrections. Added some bugs ;-)
		
------------------------------------------------------------------------------

	If you have any suggestions or problems with Another Pool (-V 0.982)
	look at the web-page http://www.planetjahn.de for my email-address.
	
	You will find the newest version on my homepage
		
	http://www.planetjahn.de (and move over to apool)
	
	Have fun and mail me all your experiences...  ;-)

	Gerrit
	
