# Almost Bowling 0.75

almostBowing Documentation
Last edited May 8, 2003

Sections:

- 1.0 Installation
- 2.0 How to play
- 3.0 Technical documentation
- 4.0 Legal Mumbo jumbo
- 5.0 Whatever I put there

## 1.0 Installation

### Windows:

Extract almostBowling_windoze.zip to the directory where you want to install almostBowling. This zip archive has the files in it's own directory, so extracting to "C:\Program Files\" would put the executable that will start the game in "C:\Program Files\almostExec\"

almostBowling can be run by double-clicking almost.exe in the almostExec directory that was created. If you create a shortcut to almost.exe it will not work if the working directory (in the Shortcut tab) is set to the almostExec directory.

Source is in almostBowling-0.75_windoze_source_VC6.zip and should compile in Microsoft Visual C/C++ 6 into it's own almost\exec directory.

### Linux:

Extract almostBowling_linux.tar.gz to the directory in which you want almostBowling installed. Like for Windows this archive contains a direcory in it. You will need the SDL libraries installed, probably mesa (for opengl) and it would be nice to have hardware accelerated video drivers. It will also need to be run from the directory containing the program data (likely the same as the one containing the program)

Source is in almostbowling-0.75_linux_source.tar.gz and I will not instruct you how to compile it.

### Mac OSX

There is not currently an OSX binary The code should compile with similar problems as experienced for Linux, but some code changes may need to be made so that it is playable. All I think may be a problem is that when the cursor reaches the top (or any other side) of the screen, the method I use to see how far it has moved will tell me that it didn't move upwards (or off of the screen in another direction), which would make throwing the ball require that the mouse is moved off of the top of the screen first. So that this is clearer to the user I would suggest uncommenting the call to drawCursor() in drawScene() in scene.c.

## 2.0 How to play

### Objective:

The goal is to knock all of the 'pins' off of the 'field.' The pins are smaller than your ball, and usually arranged in a trianglurar shape. You knock them off by throwing your ball at them. When they are all knocked off you will be taken to the next level. There is not currently a limit on how many times you can throw the ball in each level.
How to throw the ball:

While moving your mouse in the direction you wish the ball to go (relative to the 'field,' not the direction the camera is facing) press the left mouse button (primary mouse button).
When you release this button (you don't need to hold it for long, just tap it) your ball will be thrown with the direction and speed you were moving the mouse at while holding the left mouse button (primary mouse button).

The ball will move around for ten seconds (a countdown timer will appear in the upper left), until it falls off the 'field,' or until you press the right mouse button (secondary mouse button). When one of these events occur your ball will be reset, but the 'pins' will not, they will continue moving.

### Other keys:

- Esc or Control+Q Quit
- F5 Restart this level
- F12 Skip to next level (may be removed in the future)
- P to pause and un-pause.

## 3.0 Technical documentation

### The Files:

The important code consists of 6 files. They are:

- main.c // little more than the main function
- scene.c // level specific code: load level, colision detection, drawing
- objects.c // object loading: displayable and collision objects
- text.c // text drawn on screen, and the cursor routine
- vectorMath.c // vector math functions (vector cross, magnitude, normalize, et.c)
- includes.h // includes, and some macros like gravity and screen resolution

The other files are data used at runtime
The other files:

- scenelist.txt // list of each scene in the games
- *.scene // contains scene specific information in a text format
- *.trx // a colored triangle mesh in a text format

#### The format of scenelist.txt

    numscenes 2
    scene blah.scene
    scene end.scene

numscenes needs to be the same as the number of scenes.

Each "scene" line contains "scene" followed by the filename of the scene. The filename can NOT contain spaces, and is limited in the number of characters it can have. It ends at the newline, should end in .scene (not checked), and should refer to something in the current directory (no slashes). Wildcards may cause problems too.

#### The format of a .scene file

    bgcolor [0.0, 0.0, 0.25]
    txtcolor [1.0, 1.0, 1.0]
    lowerBound -5.0
    worldMesh lvl5.trx
    collisionMesh lvl5_Collision.trx
    cameraLocation [0.0, -30.0, 10.5]
    numPins 1
    location [0.0, -20.0, 1.1]
    radius 1.0
    mass 4.0
    mesh Ball5.trx
    location [-0.0, -2.459, 0.0]
    radius 0.6
    mass 1.0

there are three areas in a scene file
first, the scene specific information
then the ball specific information
then the pin specific information

scene specific

    bgcolor [0.0, 0.0, 0.25]
    txtcolor [1.0, 1.0, 1.0]
    lowerBound -5.0
    worldMesh lvl5.trx
    collisionMesh lvl5_Collision.trx
    cameraLocation [0.0, -30.0, 10.5]
    numPins 1

which is:

    bgcolor [redAsFloat, greenAsFloat, blueAsFloat]
    txtcolor [redAsFloat, greenAsFloat, blueAsFloat]
    lowerBound bottomOfWorldAsFloat
    worldMesh filenameOfWorldTriangleMesh
    collisionMehs filenameOfCollisionTriangelemesh
    cameraLocation [floatX, floatY, floatZ]
    numPins theNumberOfPins

the ball and pin specific information follows the same format, but the pin specific information repeats the number of times specified as numPins. There must always be ball information, though not always pin information (none if no pins)
The format for both is as follows

    location [floatInitialX, floatInitialY, floatInitialZ]
    radius radiusAsFloat
    mass relativeMassFloat
    mesh filenameOfTriangleMesh

all filenames in a .scene file are subject to the same restrictions as those in scenelist.txt (see above)

the color values range from 0.0 to 1.0 for each channel. [1.0, 1.0, 1.0] would be white, [1.0, 0.0, 0.0] would be red, and [0.0, 0.0, 0.0] would be black.

#### .trx files are my own triangle format. Format of a .trx file:

    numfaces 2
    NORM [0.0, 1.0, 0.0]
    COLOR [255, 255, 255]
    COORD [-0.58298420906066895, 0.0, 0.67701411247253418]
    COLOR [255, 255, 255]
    COORD [0.47014880180358887, 0.0, 0.48895478248596191]
    COLOR [255, 255, 255]
    COORD [-0.54537272453308105, 0.0, -0.52656650543212891]
    NORM [-0.0, 1.0, 0.0]
    COLOR [255, 255, 255]
    COORD [-0.54537272453308105, 0.0, -0.52656650543212891]
    COLOR [255, 255, 255]
    COORD [0.47014880180358887, 0.0, 0.48895478248596191]
    COLOR [255, 255, 255]
    COORD [0.58298420906066895, 0.0, -0.67701411247253418]

a .trx file has two regions,
the number of faces
and the information for each face.

it should be pretty clear that numfaces specifies the number of faces (which needs to be the same as the number of faces in the file).
The rest of the file is for each triangle, and is the following format, repeated for each face:

    NORM [floatX, floatY, floatZ]
    COLOR [byteRed, byteGreen, byteBlue]
    COORD [floatX, floatY, floatZ]
    COLOR [byteRed, byteGreen, byteBlue]
    COORD [floatX, floatY, floatZ]
    COLOR [byteRed, byteGreen, byteBlue]
    COORD [floatX, floatY, floatZ]

the NORM is a unit vector that points in the direction the face should be viewable from (I think). My export script generates it from the normalized cross product of the vector from v[0] to v[1] with v[1] to v[2].

Repeated 3 times after NORM is

    COLOR [...]
    COORD [...]

this sets the color and location for each vertex on this triangle.

each channel of the color value is a whole number ranging from 0 to 255
[255, 255, 255] would be white, [255, 0, 0] would be red and [0, 0, 0] would be black
don't go beyond 255, and don't type a negative number.

triangles are only visible from one side, and I believe it is the side in which the vertices go counter-clock-wise.

The NORM vector is used for collision calculations, but could be calculated in my program.

### Implementation ramblings

#### The physics

The physics is an approximation mostly. In fact, rigid body dynamics is an approximation in itself. The objects do not deform. I use completely stationary objects and only non-deforming spheres. The scale cannot really be determined (would you believe if I told you that ball was 2 meters across?). The world is defined of triangles alone, and collisions are only responded to when there are intersections between objects.

### Level Development

The levels were made in blender (www.blender3d.org) and exported in python. On this CD I have two blend files. They are levelSet1.blend and levelSet2.blend. levelSet1.blend contains all of the levels included as .trx files, and the export script. levelSet2.blend was going to contain new(er) levels, but time ran out and it is mostly blank, but still containing that export script. I will not explain how to use blender here (better suited for blender-related websites), but it should be noted that my exporter exports only triangles and vertex colors. The mesh must be made of triangles, must have vertex colors, and probably should be of some interest.

The .scene files were made by hand.

## 4.0 Legal Mumbo jumbo

This software ... GPL ... ? I guess I don't care enough at the moment. It is mine, ask before you use it. It may be released under a license later

Oh, I am not responsible for any damages this may cause to your computer. This program is not suitable for accurate simulations of anything useful. In fact, it is not even meant purely for your entertainment.

## 5.0 Whatever I put there

I have a lot of things I would like to have done... They are:

- Command line parameters...
  I started to work on implementing command line parameters (look in main.c), but they became a relatively low priority. In main.c I specify what I wanted them to be for.
- Better levels:
  Time didn't allow very interesting levels. Though more recent changes in the code will allow new levels without recompiling in the code.

Nick Winters, 2003