Overview

+--------------------------------------------------------+
|Blave: A CAVE like extension for the Blender Game Engine|
+--------------------------------------------------------+


* What it does:
---------------

The Blave Extension gives the Blender Game Engine the ability to output
Applications to multiple screens with any position and orientation.

Therefor it tries to synchronize the Blender Game Engines on different machines
whereby a server does all the Game Logic and sends all the scene changes
to the clients which just apply them.

Furthermore every client sets its camera and projection matrix so that
a correct perspective for its connected screen from a given user view point
is reached.


* How it works (currently...):
------------------------------

The necessary Game Engine classes get an additional handle base class to track
their instances (currently 'KX_Scene', 'KX_GameObject' and 'SG_Spatial').

When something happens with such an instance (by calling certain methods on it),
an action along with the necessary parameters will be stored in a data queue.

On request all the stored new actions will be send to the clients which apply
these actions to their corresponding instances.

For every client there has to be defined an object in the scene
which reflects a physical screen whereby the Z axis of the object defines
the normal of the screen and the Y axis defines the direction
from the bottom to the top.

Every screen object must also have two float properties to define the size:
'width' and 'height'.

Additionally there must be defined an object which reflects
the user's view point.

The transformation of this object (and of the screen objects)
can dynamically change whereby the view point object's orientation
has no relevance.


* Limitations:
--------------

The general framework is almost complete and works fine.

It only works with the blenderplayer program and not out of the editor.

The number of recognized actions is currently very small:

- translation, rotation and scaling of objects (SG_Spatial transformations)
- adding replica objects to and removing objects from scenes
- Armature pose transformations

All other Game Logic actions have currently no affect on client side
and can cause crashes.
(so the test applications should be rather simple... :)

Additionally it currently doesn't work with dynamically loaded scenes,
only the start scene is working.

* Usage:
--------

The components are started by adding certain double hyphen options
to the blenderplayer commandline.

- to start a client:

  blenderplayer ... --port <nr> ...

- to start the server:

  blenderplayer ... --viewpoint <view point object name> \
                    --screens <triples ('screen name' 'client host' 'port')> ...

  - example:

  blenderplayer --viewpoint V --screens 'S0 host0 2000 S1 host1 3000' test.blend

The clients have to be started before the server application
and must have access to the blend file and media files
(the server doesn't send any application files to the clients).