Documentation and Examples

1. Installation and build

Isaac currently only supports the Linux operating system. It does run on Mac OS, but you will have to manually install the irrlicht engine.

To set up the system, get the latest version of the source code from github via

git clone https://github.com/grabherr/Isaac.git

Next, install the following development libraries:

libx11-dev mesa-common-dev freeglut3-dev libxcursor-dev subversion libasound2-dev

e.g. via

sudo apt-get install libx11-dev mesa-common-dev freeglut3-dev libxcursor-dev subversion libasound2-dev

on Ubuntu or Mint. Type 'make' to build Isaac and verify that there are no compilation or linking errors.

Third, install the irrlicht engine into a directory 'irrlicht-code' within the Isaac directory. To get the latest version of irrlicht and compile it, run

./getIrrlicht

which will download and compile the Irrlicht engine, followed by

./compileIrrlicht

Which will compile the irrlicht client. Note that you will have to run ./compileIrrlicht any time you modify the Irrlicht client, and that this script will also re-compile the Isaac code.

To test your installation, run:

./TestGameEngine -i data/empty.cfg > tmp

which brings up a fairly empty map in full screen mode. To navigate, use the arrow keys and mouse. To exit irrlicht, press 'z'. Note that you will have to manually stop or kill the executable TestGameEngine as well.

2. Using Isaac: the Makefile system

To add a a new executable, simply create a file that has the extension .cc and contains the exact line

int main(int argc,char** argv)

then type 'make'. It will be automatically recognized. To add new code, add files with the extensions .cc and .h, making sure that they have the same name and are located in the same directory. Including the .h file will cause the .cc file to be compiled and linked in.

3. Configuration files

For a basic setup of maps, screen resolution etc., the engine can read a simple test configuration file. The sections are:

################# BASIC CONFIGURATION ############<basics>GraphicsEngine ./irrlicht-code/bin/Linux/IrrClient# Resolution 1680 1050 full# Resolution 800 600Resolution fullGravity 0.</basics>
Which defines the location of the IrrClient executable, the screen resolution ("full" without explicit resolution will detect the native monitor settings), and the global gravity (set it to 9.81 for a real-world setting).
####################### MAPS #####################<map>MapName        SimpleTerrain        data/Skyboxes/terrain-heightmap-empty.bmpTexture1       data/Skyboxes/floor.jpg# Texture2     data/Textures/grass1.jpgSkyUp          data/Textures/clouds1.jpgSkyDown        data/Textures/clouds2.jpgSkyLeft        data/Textures/clouds3.jpgSkyRight       data/Textures/clouds1.jpgSkyFront       data/Textures/clouds2.jpgSkyBack        data/Textures/clouds3.jpgSkyDome        data/Skyboxes/skydome.jpgDefaultScale 15.
Here, we specify the map via skyboxes, a floor, a terrain map, and a scale between the 3D engine's and the physic's coordinates.
############### Models (optional):<physics>X 4200 Y 1400Z 5200;XR 33YR 2ZR 30physmode 0MD2Model data/Models/cube.ms3dMDTexture data/Models/cube.jpgName CubeType Cube</physics></map>####

Objects can be added to the map via the config file, but note that they cannot be further manipulated programmatically (for an explanation of physics mode etc., see 'coding examples').

4. Programmatic Interface

The top-level interface is provided by the class GameEngine in engine/GameEngine.h. Methods are:

Read the configuration file:

void ReadConfig(const string & fileName);
Set the global scale:

void SetScale(double s);
Set up the map:
virtual void SetupMap(int n);
Run the engine:
virtual void Run();
Register a global object (see below)
void RegisterGlobal(IGlobal * p);
Add a scene node:
void AddSceneNode(const MsgSceneNode & n, IManipulator * p = NULL);
Add explicit lighting:
void AddLight(const MsgLightNode & l);
Control collision detection:
void DoTriangleCollision(bool b) void DoObjectCollision(bool b )
The main interfaces to objects are MsgScenenode (in graphics/Messages.h), IManipulator, and IGlobal (both in engine/IManipulator.h). For a description, see 'coding examples'.

5. Coding examples

5.1 Example1.cc: minimal setup

Here, we provide a minimal setup. All that is needed to start up the engine are these 5 lines of code:

#include "engine/GameEngine.h"      // Include file GameEngine eng;                   // Declare the object eng.ReadConfig("data/empty.cfg"); // Load the config eng.SetupMap(0);                  // Specify the map id eng.Run();                        // And off we go!

This will show a more or less empty map without any objects in it.

5.2 Example2.cc: add objects

There are two ways of programmatically adding objects, one is to explicitly define each vertex, index, and texture coordinate, the other is to send a model name to the client, have it load the mesh, and send back the information if needed. Objects have three physics modes:

0 - full numerical physics
1 - static physics (relative coordinates do not change, but can be manipulated via a Manipulator)
2 - basic physics, without rotation etc.

In this example, we simply put a cube and a ball onto the map at defined coordinates.

5.3 Example3.cc: us Manipulators

Here, we define a manipulator that controls the movement of the objects. Note that the choice of physics mode determines the default behavior and movement of the objects.

5.4 Example4.cc: lighting

The example is essentially the same as before, except that we added some specific lights and enables lighting in the objects.

5.5 Example5.cc: animation

This is a simple example of how you change and control frame-based animations.

5.6 Example6.cc: streaming textures

Here, we stream textures onto a surface. IMPORTANT: Run ./TestCalmWaters to generate data showing water waves on a pool, otherwise the example will not work.

5.7 Example7.cc: texture coordinates

A simple example on how texture coordinates can be used to mimic depth (will be updated soon!).

5.8 Example9.cc: sound

Two scene nodes go in circles and play sounds. Move around to listen to the doppler effect, or other things that are computed dynamically and close to real-time (in the client).

5.9 Example9.cc: TBD

(Skip for now)

5.10 Example10.cc: server/client

Simple setup to run the server on one machine, and the client on the other. To execute, first run the server as:

./Example10 -i data/empty.cfg -c <clientname>

on the server machine, and then the client as:

./irrlicht-code/bin/Linux/IrrClient 800 600 false <servername>

on the client machine, where the first three arguments are the screen resolution (800 by 600 in this case), followed by fullscreen (true/false), and then the server name. Server and client names can be just the names, IP addresses, or "localhost" if you run both on the same physical machine (which all the other examples do by default)
.