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

there will be a complete new version of this file in one of the
next releases....


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

Contents:

1.      General Informations

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

3.	Rules 
 
--------------------------------------------------------------------------

1.      General Informations


	"Another Pool GL" 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 8 feet-table. 
	The (original) rules have been slightly modified to be easier
	implemented.
	Another Pool GL was developed using gcc-2.95.X and gcc.3.2
	under Linux (also tested under Win32). Since the game came out
	in 1995 as 2D-MS-DOS-release many changes have been introduced
	till now ;-)

	The underlying graphics-library is now SDL 
	(http://www.libsdl.org). The OpenGL Documentation can be obtained
	at http://www.opengl.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 shots with no spin), the balls will slide in the
	beginning and then start continuosly to roll after some time
	left until the speed of the surface matches the speed of the
	center of the ball. 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 center after a
	short acceleration-period.

	At the moment the table is a bit so slippery in my opinien. The
	underlying physics enginge has to be modified a bit...
   
	If you want to start the game, the file konst.dat must (!) be
	in the same directory as apool-binary. For the Win32-release
	the SDL.dll must either be located in the Windows System
	directory or in the apoolGL-directory.

	The old MS-DOS release was developed on an 486DX2/66 in
	1995. Since we now use OpenGL the pc has to be a bit faster
	now ;-) But since the timer is now used in a more effective
	way, ApoolGL should work on everey system. The frame rate will
	decrease if the system is slow but it should be playable. 

	Try to use the F4/F5-keys since they switch from low to high detail
	and turn display of textures on and off and the other way around.
	
-------------------------------------------------------------------------

2.



2.1     The Keys

	During the game the following keys will cause an action: 

  SPACE: in menu mode activates free look mode. You can rotate the table
  	     using the mouse. A click on the left mouse button stops
	    	 free look mode. The center of the rotation is the center
				 of the table for now...(will be changeable in one of the next
				 releases.
	 
  CURSOR KEYS: move table up/down/left/right.

  PAGE UP/DOWN: Zoom in and out.
	 
	 c: computer plays for current 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... If you have a wheel
			mouse, you may use the mouse-wheel to 
			change the angle.

			not implemented in the OpenGL-release for now.
)

   f:     toggle display of frames per second
		
	 x:     computer plays only one shot for current player
	 	
	 d:     start computer-demo
	       	(in demo-mode: press SPACE stop demo immediately)

	 u:     undo last shot (no redo implemented!) und works fine now

	 h:     simulation mode. Using the current values for spin, speed
	 				and cue direction the end position will be calculated.
					The trace of the balls will be marked by triangles.
	
	 z:     in play mode: the end position of the balls will be 
	        calculated immediately
	
	 w:     toggle special target mode. The white ball will be centered
	        and the tables rotates with the white ball in the centre.
					Just give it a try, looks cool. still some bugs...

	 t:		  rotate table to top view
	 s: 	  rotate table to side view (short edge of the table)
	 l:	    rotate table to last view.
	 
	F1:     help, show keys.
	
	F2:     credits

	F3:     toggle table texture on/off.
 
  F4: 	  toggle display of textures on and of.

  F5: 	  change gemetric detail level from very low to low to med to
	        high to very high to very low and so on... very low has
					graphics errors!

  F6: 	  change shadow mode. Default is planar, next level is
			    stencil1 followd by stencil2 (slow). Stencil2 has wrong
					colors.
					Next level is off followed by planar again.

  F7:     toggle texture detail level (high/low)

	F8:     Environment Textures for the metal caps on top of the edges.

	F9:     change ball environment mapping. Default is off. F9 changes
	        to dynamically rendered cube mapping (slow) followed by 
					static spherical mapping (fast) and off again.

  F11:    changes table theme. Default ist blue/marble, F11 changes 
	        via red/leather to green/wood.

	F12:    shows statistics screen.

	 n: new game
	 
 ESC: quit game
       
	 Some keys only cause an action in menu mode.

 During shot:
 
 	mouse motion changes the angle of the "camera"
	right mouse button and motion changes zoom level.

	SPACE and "z" calculates the final position of the balls.

	ESC quits as allmost everywhere.
	 
2.2      Command Line Options

   see apool -h for full set of command line options.
	 The most important ones are described below:

	 "apool -F"

	 starts apool in full screen mode.

	 "apool -x <xres> -y <yres>" 

	 stats apool inside a window of the size x*y or full screen with 
	 the resolution next to x*y if available by your Windows-System.

	 "apool -g <glevel>" starts apool with gemoetric detail level
	 set to glevel. Default is 3 for Linux and 2 for Windows. 5 is 
	 highest. 

	 "apool -d 0" starts apool with textures disabled.

	 "apool -h" shows the help message.
	 
	 default is 1024x768 Window-Mode, and textures enabled.

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)
	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)

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).
	
	-clev:  describes deepness of computer-opponents "thinking". 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)

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

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).
		Do this by moving the mouse and press any button when your kick off
		position has been reached.
	  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
	  ball (without any foul!) in a pocket to win the game.
	  If you shoot the black one in a pocket by making a foul, you lost
	  the game.
	  If you play the black one too "early" in a pocket, you lost the 
	  game, too.
		  
	- Free ball, Fouls
	
	  If your Opponent makes a foul, you have one `free ball'. That means,
	  you can hit ANY ball first (including the black one) and shoot
	  ANY ball in a pocket (excluding the black one, except you MUST play
	  the black one).
	  
	  If you don't make a foul and don't pocket a ball when you have a
		free ball, you get an additional 'extra-shot' - kind of punishment
		for the foul of your opponent.

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

	(*): except you have a freeball
	
	 - The loser of the current game kicks off the next game...
	 
-----------------------------------------------------------------------------

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

	Gerrit