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    Next Versions
 4.3	Changes
 
--------------------------------------------------------------------------

1.      General Informations


	First thing: sorry for my english.... ;-)

	"Another Pool" simulates a pool game like 8-Ball with 16 Balls,
	(white, black, 7 striped, 7 filled balls (here: red and yellow))
	on a 7-feet-table. 
	The (original) rules have been slightly modified to be easier
	implemented (you will see it, if you play...). 
	Another Pool is compiled with GNU-C 2.57 and uses cbgrx 2.0 (alpha-
	release).
	
	Another pool simulates billiards as realistic as possible (for me :-).
	So you can play "english" (with spin), play curve-balls and the 
	balls will naturally roll, after sliding a while if hit in the 
	center (so they won't stop after colliding with other balls as you
	would expect from an "unrealistic" (only-) full-elastic collision
	but roll...). 
   
	If you want to start the game, the files konst.dat and table.dat 
	must (!) be in the same directory as apool.exe. go32.exe must be in
	this directory as well or in path-environment. The .fnt files should
	be also in the apool-directory.
	
!!!     If the game won't start correctly, look at the file "VIDEO.BAT"
	for further details on installing the video-driver correctly.
	
!!!	If the file "table.dat" is missing, enter "billard -init 32",
	to create it (s. 2.2).
				   
	By the way: it would be useful to own a 486DX or more. The
	program won't work without fpu :-( [and it's of course no good idea 
	to use the 387-emulator ;-)]. So 483SX- or 386 without 387-users
	can't play Another Pool (sorry).
	
-------------------------------------------------------------------------

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).
		
	 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...
		
	 x:     computer plays only one shot for actual player

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

	 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
	 
	 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
	  
	  
	 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!)
	 
	 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" 
	  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.

	 "apool -init x" 
	   calculates the 'geometry' of table new. "x" is the width of the
	   pockets (25 < x < 45). -init x creates the file "table.dat" new.
	   x = 32 is the default size.

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 (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.
		
4.2     Next Versions:

   0.99 - 1.0:  - if "real" cbgrx2.0 is out, there will be a double page-mode
		  implemented, so the balls won't flicker anymore.
		- english comments in the source code and .dat-files.
		- better menus, if I have time enough.
		- more and 'better' rules will be implemented.
		- computer-opponent will use the cushion and tests, if
		  playing a foul (before playing ;-) ...
		- Some more changes at the sides (Balls will get z-spin,...)
		- ...

		
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 a Micrsoft-Mouse
	  doesn't have one), keys: "e" + mouse-move, "+/-".
		
------------------------------------------------------------------------------

	If you have any suggestions or problems with Another Pool (-V 0.981)
	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/apool
	
	Have fun and mail me all your experiences...  ;-)

	Gerrit
	
