Chimera Script reference
v2.04 OSX and Windows

*** obsolete, still working, i need to update a lot of statements **

Chimera is a 3D powerful engine completely driven by scripts.
The "script" is a text file, containing statements, variables, loading and disposing operations ... in short it is like an interpreted program written in a language similar to C++. On startup, the engine opens the scene (the scene file, selected in Settings), then searches and executes the "script".  The script is the core of your scene, it  handles EVERYTHING from the loading operations of objects, sounds and textures, to positionments and effects.
The purpose of this reference is a comprehensive script explanation.

Sections

How to
Keyboard Map
Syntax and conventions
Basic language keywords

Load  Delete  New

Scene
Object
Shadow
LightGlow
LightBloom
Blur
CSG
Texgfx
Radio
Water
Fluide

Particle
Flare and Lensflares
Light
Skybox
Keyframer
Deform

Status 

HOW TO

To build a scene put the Chimera application where you want then, in the same folder, create a folder named Data
By default the engine executes the content of the Data folder.
Put all you will need for your scene - objects, sounds, textures and music – in this Data folder and launch Chimera.
In the data folder acceptable file formats are:

- script.txt      the main script file;
- objects:       3DS (3DStudio), OBJ (portable Alias Wavefront) and proprietary GFX;
- textures(*):  JPG,PNG all Quicktime valid format and Quicktime movies (for OS X), AVI movies (for Windows);
- effects:        VP (vertex program) and FP (fragment program);

Keyboard Map

R (render) key select the render mode (solid or wire frame)

I (info) key cycle from (upper left to lower right): a) bounding boxes, b) id for any vertex
c) id for any face, d) vectors of keyframer's paths

Syntax and Conventions

First of all let’s get a look at basic script syntax.
If you already have a basic knowledge of the C programming language you are OK, otherwise ... well, it is not very difficult to understand anyway, the basic syntax is quite similar to C, any instruction must be ended by a semicolon (";").
This is the quickest script you can write:

scene start;

Variables are ONLY floating point, but the engine uses them automatically as integers, short etc,
There's no char or string definitions (c'mon, if you want to write something cool on the screen you must use a cool texture...).
Variable declaration is unnecessary, as a variable is declared directly thru assignment, here are some examples:

a = 1;           //declare and assign "a"
b = sin(a);    //...and b

The full math syntax/operators of C are valid:

a *= c;        //equivalent to...
a = a*c;
a !=b;
a = (c++);     //etc etc...
/* unused line */

It is possible to declare an array and use it through indexing:

array a[200];
a[27]=sin(b*c);

IMPORTANT! As in C,  please keep in mind that the script language is CASE SENSITIVE:

A = 100;
b = A * 100;    //ok
b = a * 100;    //WRONG!!!! "a" is not "A"

MYSHIP = load("BUCKROGERS");
delete MYSHIP;    //ok
delete myShip;     //WRONG!!!!

The data handlers (object, flares etc..) are organized with identifiers. If you first declare an object as:

myShip = load("ship");
myFlare = new cFlare();

then you can use the myShip and myFlare identifiers thru the script:

object myShip position(10,20,10);
flare myFlare color(1,1,0);

For those familiar with OOP: just imagine you're using a class without the "->" , the previous statement is like: myShip->position()...
and, of course, you can state:

delete myShip;
delete myFlare;

That isn't strictly necessary though, as the engine will automatically deallocate all open resources on exit.

KEYWORDS

Basic keywords(you can NOT use them as variable names, they are used, for example, in load, delete  and other statements:

the if .. else, while and for statement have the same syntax as in C
remember you're using a sort of advanced scripting system :-) so you can combine functions:

for (c=0;c<100;c++){ ...       //note: "c" is auto declared

while (a+=0.1 <= sin(z){ ....  

a = sin(0.1);
array c[20];
c = atan(a);
if (a*b = 1 && p<c[10]){ .... }else{ .... };

the random, sleep and time statement can be useful:

/* stops the script execution for 2 seconds */
sleep(2000); 

/* get a random position from -100 to +100 range */
object_position = random(-100,+100);

/* time is useful for sync effects */
currTime = time;
while (time<currTime + 5000)
        currTime = time;

Notes for non-programmers

the script engine has full support of functions and variables ... "compressing" code is vital (but not compulsory) for speed and readability, for example this code:

object STARSHIP diffuse(0,0,0);             //this sets STARSHIP object with diffuse color black
object STARSHIP diffuse(0.5,0.5,0.5);     //this sets STARSHIP object with diffuse color gray
object STARSHIP diffuse(1,1,1);             //this sets STARSHIP object with diffuse color white

is equivalent to:

COLOR = 0;
object STARSHIP diffuse(COLOR ,COLOR ,COLOR );
COLOR = 0.5;
object STARSHIP diffuse(COLOR ,COLOR ,COLOR );
COLOR = 0.6;
object STARSHIP diffuse(COLOR ,COLOR ,COLOR );

and, in a more appropriate and short form, it is also equivalent to:

for (COLOR=0;COLOR<=1;COLOR+=0.5)
   object STARSHIP diffuse(COLOR ,COLOR ,COLOR );

if you want to assign random colors to the STARSHIP object, you can specify:

COLOR = random(0,1);
object STARSHIP diffuse(COLOR ,COLOR ,COLOR );

or, better, put the functions directly into the statement:

object STARSHIP diffuse(random(0,1),random(0,1),random(0,1));

LOAD

the load function returns an index to an entity, for example an object, or a particle, or a texture:

SHIP = load("DISCOVERY");
newTexture = load("bigImage");

the load operation always refers to files already in the DATA folder, remember you can't use extensions:

SHIP = load("DISCOVERY");             //ok
SHIP = load("DISCOVERY.3DS");    //WRONG

the engine automatically detects the right extension and loads the object (if the format is supported, of course...).
Loading textures or vertex programs doesn't require allocation, so they can be reused later in other classes, for example:

lightTexture = load("lamp");
darkTexture = load("lampoff");
....
flare BigLamp texture(lightTexture);
flare BigLamp texture(darkTexture);
....
particle Smoke texture(darkTexture);

are equivalent  to:

flare BigLamp texture(load("lamp"));
flare BigLamp texture(load("lampoff"));
....
particle Smoke texture(load("lampoff"));

but the first one is nicer because the texture allocation is just one
This function varies from  class to class, so I put a better explanation in the chapters regarding the various classes (object, particle, flare etc.).

Please note, for GLSL shaders the load works using a name only with special suffix.
For Example:

id lampShader = load("lamp"));

Seach for LAMP.FRAG and LAMP.VERT and combine all into a program, no problem if one is missing the engine uses only the part found (vertex or fragment).

DELETE

delete statement disposes of  the specified identifier:

myShip = load("DISCOVERY");
myFlare = new cFlare();
delete cObject(myShip);
delete cFlare(myFlare);

Once again, it is not necessary to dispose of all entities, as the engine automatically closes all opened resources on exit.
Use this statement only for your convenience ... for example if you want to dispose of an object and load another.

Keep in mind that you can use the "active" statement to disable an effect, or to hide an object, without disposing of it:

SHIP = load("DISCOVERY");
object SHIP active(0);    //object is now hidden

NEW

The new function allocates a new class, representing an object, effect, etc:

MYFLARE = new cFlare();

Usually classes can be allocated on-the-fly, only object class doesnt require "new" but "load", for example:

mySeaPlane = new cWater();                //right, this is an "effect operator", not a "real object"
myStarship  = new cObject();               //wrong, an object must have a geometry!!
myStarship  = load ("StasrhipMine");   //right, an object is allocated during loading

SCENE

scene statements control camera(s), the general appearance of the scene and the user input (if enabled):

CAMERA MOVEMENTS

you can position a camera with simple statements:

scene position(1,0,0);
scene position(2,0,0);
scene position(3,0,0);
scene position(4,0,0);

or functions:

for (pos_x = 0; pos_x < 100; pos_x ++)
{
    scene position(pos_x,0,0);
    sleep(100);
}

for (t=0;t<1000;t++)
    scene position(random(0,500),random(0,500),random(0,500));

the best way to move a camera in a smooth movement is thru a "keyframer", a keyframer makes a smooth trajectory where you define only the waypoints.
Click on the keyframer link for more samples

USER INTERACTION

The following statements controls the user input relative to camera movement.
They are valid only if user input is enabled with scene keybd(1) (ignored in debug mode)

To gain more control about objects selection and status of keypressed buttons during script execution see the status function

CUBEMAPPING

Cubemapping is a very cool environment mapping mode, available only on newest videocards.
Cubemapping requires SIX textures, representing the environment, and these six textures are envmapped on the objects.
To enable cubemap you must have SIX textures named cubemap_xxx where "xxx" is the orientation (left, top, right, bottom, front and back) for example CUBEMAP_FRONT.TGA and CUBEMAP_BOTTOM.JPG are both valid, the orientation follows the "standard" defined by nVidia in their demos:

All six textures must be equal in depth (eg.: all of them 24bit per pixel) and size (eg.:all of them 256x256 pixels) ... sorry this is imposed by hardware.
The cubemap will be applied automatically on objects with envmapping textures, if the hardware can't support cubemapping the engine uses automatically the standard envmapping.
To apply a standard envmapping on a object check the object statement.
Tip: since cubemap is better if it's coherent with the visibile background ;-) you can define a skybox using the SAME SET of  textures, for example:

SKY = new cSkybox;    //create a skybox
skybox ("cubemap");     //load a skybox with the same standard (cubemap_left etc etc);
skybox active(1);

scene cubemap;           //activate cubemap, now reflections on the object are coherent with environment!!

It's possible to enable a separate set of cubemap for every object, check the texturing chapter for more info.
It's possible to enable realtime cubemapping over an object, check the texgfx chapter for more info.

VERTEX and FRAGMENT PROGRAMS

It is possible to apply a vertex program (also know as vertex shader in DirectX programming) or a fragment program (also know as pixel shader) on every object .These programs are very powerful programs running straight on the GPU (leaving free your cpu ...and requires hardware support of course).
The use of GPU programming is only limited by your imagination, because they can control :colors, texture coordinates, lighting and vertex position in realtime .
These program must be written and placed in the scene file then we instruct a main scene to load and apply on objects.
Since vertex and fragment programs can be shared by different objects they must be loaded like textures and assigned in the general "scene" class.

 
(left: sample vertex colors, right: cel shading)

the following example loads a vertex program and assigns it to an object:
....
tekkaman = load("blade");
object tekkaman active(1);
....
perturbVP = load("perturbVP");
scene vprog(tekkaman,perturbVP);

if the shader is used once and for just a single object you can compress code:

scene shader(tekkaman,load("perturbVP"));

for convenience a shader can be called by scene and object, the following statement are equivalent:

scene vprog(tekkaman,perturbVP);
object tekkaman shader(perturbVP);

if you need to send a parameter to the shader call:

scene vpparm(perturbVP,0,0,-100,time);    //shader "perturbVP" receive 0,0,-100 and the current time

In the Chimera "SDK" distribution you can find some samples of vertex programming.

OBJECT

The object class is the core of the engine, because without objects, it is hard to make a scene :-), acceptable object format may be 3DS, OBJ, MD2 and others.
It is possible to apply a vertex program to every object.
When first loaded,  the original file will be converted in GFX format, which is smaller and more suitable for the engine.
The original object file may contain a single object with a single material or multiple object and material definitions.
Materials are a good source of effects because an effect (envmapping, bumpmapping and so on...) can be assigned on a specified material.
Material effects are automatically applied if the corresponding texture is found, for example, material covered by texture "TERRAIN.TGA" will show bumpmaps  AUTOMATICALLY if "TERRAIN_BUMP.TGA" is found (see texturing)

DEFORMATION

These statements control the realtime deformation of an object

As an example, you can dinamically ondulate a surface to recreate water or flag effects, or morph an object into another.
To specify (vertex) identifyer you can use key 3 on the keyboard (not keypad), this show you all vertex number of all object.

for (int t=0;t<6.28;t+=0.001)
    object Dummy y_value(0,sin(t));    //"ondulate" vertex 0 of object "Dummy" along y axis

for a range of vertices the following code:

for (int numVertex=0;numVertex<100;numVertex++)
    for (int t=0;t<6.28;t+=0.001)
        object Dummy y_value(0,sin(t)); 

is equal to:

for (int t=0;t<6.28;t+=0.001)
        object Dummy y_array(0,99,sin(t)); 

see also vertex programs about deformation

TEXTURING NAMING CONVENTION

Assuming only one effect will be applied on a specific material for speed reasons except for lightmaps (effects are applied through multitex ARB in one pass only, if possible),  the texture naming convention to implement effects is:

Added textures, or simply "effects" can be different in sizes and formats from the base texture.
Some examples .... Imagine having a ship containing a lot of materials (and a lot of texture). Now let's say you want to assign an envmapping (cubemapping. if defined, is automatically applyied in place of the standard envmap) to the right and left engine and to the cockpit. These objects are covered by the textures ENGINE.TGA and COCKPIT.TGA (the object will look as the one in the left image, below)
If you create two textures named ENGINE_ENV.PNG and COCKPIT_ENV.PNG (actually the same, i.e. the middle image), the result will look as the image on the right.

Now suppose I wanna apply transparency to cockpit.
Transparencies are NOT represented by another texture but are within the same texture, so I open COCKPIT.PNG with an image editor (let's say Photoshop or GIMP), and add an alpha channel. This specific, gray-scaled channel represents transparency. Solid white  means opaque, and solid black is fully transparent, fading from black to white simulates different degree of transparency - as an example, in the textures below I added some white to the border to simulate a dirty effect on the glass (the granular spray tool will do this nicely):

We can use this effect in a creative manner. For example: transparency is not just useful with glass objects, but also for defining fences or complex structures, (such as trees, fences, metallic carpentry etc) by just using a flat surface and a transparency texture:

Please note Chimera contains an automatic "alpha tester" for sorting alpha object.

Now we want to apply bumpmapping to the central surface.
Bumpmaps require an active light to work, but we already have a light active, so if the base texture is this BODY.TGA (second image) we can create a grayscaled texture calling it BODY_BUMP..PNG  (third image)and the result will look as the image on the right:

Now about glows or "lightmaps": a lightmap is a secondary texture applied to the base texture to define the level of brightness and color of the base texture.
The object ID lightmap(0/1) statement controls the blend mode of the lightmap, in the default mode "black" is trasparent and the lightmap increases the brightess of the main texture, in the alternate mode the lightmap "darkens" the main texture to produce dark, shadowed zones (this is the common trick used by the 99% of the games to show complex but static shadows in the main ambient, for example the classic light filtering thru the steps of a stairway).
The engine can apply also a glow effect on these lightmaps, to enhance quality.
Let's consider my loved stardock: on the left there is the base texture BASE.JPG, on the right is BASE_LITE.JPG (the same texture, this time processed by altering the contrast and brightness of the first one):

the lightmap colorizes the base texture and is NOT affected by lighting.
In the default mode the result is (see images below): in  the left image the base texture with a soft light coming from the left; in  the second image just the  lightmap,  in the third image the two textures are blended together (notice the "windows" are lighted in the dark side), in the fourth image the effect is optionally enhanced with the fullscreen glow effect

Now about dot3 bump mapping (or "tangent space bump") and specular bump mapping: they require an active light to work and vertex program enabled on your board,  if the base texture is this MARBLE.PNG (image on the left) we can create a normalized texture calling it MARBLE_NORMAL.x or MARBLE_SPECULAR.x (image on the right, note: "_normal" and "_specular" are only naming convention to achieve the proper effect, the normalized texture is the same):

here the result: the first image on the left is the base scene, the middle image (dot3 bump mapping) is obtained with the normalized MARBLE_NORMAL.x and the image on the right (specular bump mapping) is obtained renaming the normal texture in MARBLE_SPECULAR.x :

There are a lot of tools helping you create the normalized map, the previous sample was created with the NormalMapFilter, a Photoshop plugin made freely downloadable from nVidia web site.
For OS X you can also use my free NormalMapGenerator software, in Misc Stuff section of my website.

You can also assign a "moving" multitexture (like an AVI) and make it "play" on a material: this is a textgfx effect, applied after the object is loaded.
Static shadows and lightmaps can be generated by the internal radiosity processor.
See also vertex programs about texture effects.

To implement dynamic shadows you need a light and an object casting shadow (duh!), two or more lights produce two or more shadows.
The target object and the "fake" (the shadow caster, can be the same object) object are defined into costructor (see sample).
Basic statements are:

/* oad an object */
CUBE = load("CUBE");
object CUBE active(1);

/* load ship */
SR4 = load("SR4");
object SR4 active(1);

/* define a light */
LIT = new cLight(-1);
light LIT move(-500,0,-500);
light LIT active(1); 

/* build the shadow class */
myShadow = new cShadow(0);
shadow myShadow defobj(SR4,SR4);
shadow myShadow color(0,0,0,0.8);
shadow myShadow active(1);

scene start;

in this image: left standard shadow, middle shadow with volume, right: shadow with volume and high color (1,1,1,1)
 

A little trick of the trade: because shadow implementation is very slow on old hardware, many games and demos do not calculate the shadow using the real object but using a simplified, invisible object. Consider these two models: the left one uses a good 2K poly resolution, the right object is the little brother, 400 poly and no texture, which is never put on screen but is used for shadow casting:

Chimera supports the use of "fake" objects for shadows, in the first script you can add:

/* load fake/small ship */
SR4Fake = load("SR4Fake");        //load fake model
object SR4Fake active(0);             //notice fake model isn't active
....
shadow myShadow defobj(SR4,SR4Fake);

notice the fake ship is NOT active, and you DO NOT need to reposition or rotation it in concert with the visible ship,as it is all self-managed by the engine.
Static shadows can be generated by the internal radiosity processor.

//TODO : Chimera supports also PCF Shadow Mapping :)

LIGHTGLOWS

simple sample of activating a glow (once, since is a fullscreen effect)

myGlow = new cGlow(0);
glow myGlow settings(512,2,2);
glow myGlow color(0.6,0.6,0.6,0.6);
glow myGlow active(1);

LIGHTBLOOM

Fullscreen lightbloom (or "bloom") is a cool effects to enhance the lighting quality of the scene.
Lightbloom enhance the lighted areas with a photorealistic diffuse glow, this effect do not requires any texture to works, the work is indipendent from the number of polygons.

 BLUR

Blur is the standard effect to create "trails" using multiple images/buffer overimposed, its used for "speed" effect and more.
Like the glow and the bloom is a fullscreen effect so all the scene is included and do not requires special parameters.

CSG

Real-time CSG is a cool feature that enables dynamic addition and subtraction between two solid objects.
Like shadow-casting, it is a bit heavy for old hardware so ... use them, if possibile, with low-poly count objects.

LIT = new cLight(-1);
light LIT move(1000,0,0);
light LIT active(1);

CUBE = load("CUBE");
object CUBE move(-10,0,0);    //moves to intersect BALL
object CUBE lighted(1);
object CUBE active(1);

BALL = load("BALL ");
object BALL lighted(1);
object BALL move(10,0,0);    //moves to intersect CUBE
object BALL active(1);


myCSG = new cBlur(BALL,CUBE);
CSG myCSG opmode(0);
CSG myCSG object1(BALL);
CSG myCSG object1(CUBE);
CSG myCSG active(1);

scene start;

with CSG operations we have three possibility (from left to right):

CSG myCSG object1(BALL);    
CSG myCSG object2(CUBE);
CSG myCSG opmode(0);

CSG myCSG object1(CUBE);    
CSG myCSG object2(BALL);
CSG myCSG opmode(0);

CSG myCSG object1(CUBE);    
CSG myCSG object2(BALL);
CSG myCSG opmode(1);

in the third example the operator creates the shared volume between BALL and CUBE so the result is the same (by exchanging object1 with object2)

Note that  this is all in realtime, so if you rotation the BALL or move the CUBE the resulting object is always the result of the add/subtract operation.

TEXGFX

texgfx is an operator to control texture effects. For example texture scroll, multitexture and reflection effect.
It is possible to apply a tex effect on every object texture, supposing the object has a texture already applied or, at least, defined texture coordinates.

SCROLL

Move a texture on a material

this is a sample code from the Horizon2 scene, we set a random shift over previously loaded cloud_object object

cShift = new cTexgfx(cloud_object);
texgfx cShift assign(cloud_object,0,0);
texgfx cShift shift(0,random(0,1000)/100000,10);     //this shift ranges from 0 to 0.001 every 10 milliseconds
texgfx cShift active(1);

MULTITEXTURE

Assigns one or more new texture(s) to a material and changes it periodically:

this is a sample code from Horizon2 scene, after loading 30 textures we set a random change every "random" milliseconds:

totTex = 30;
tex0 = load("tex0");
load("tex1");
load("tex2");
......
load("tex30");

Rotor = new cTexgfx(cloud_object);
texgfx Rotor assign(cloud_object,0,0);             //assign the "rotor" effect to object "cloud_object", object 0 material 0
for (t=0;t<totTex;t++)
    texgfx Rotor texture(tex0 + t);                     //assign texture from n to n+30
texgfx Rotor change(random(2000,8000));        //assign random change time
texgfx Rotor active(1);

REFLECTIONS

A texture can be used as a secondary picture of the scene. This kind of texture is created on the fly and applied to an object and requires a "virtual" camera, positioned where you want, to take shots of the scene and transferred to the texture, so you can simulate reflections, picture-in-picture or external screens, etc

the kind of texture to be replaced can be defined with the target statement: the first image from the left is the original scene, in the second image the particle is reflected onto the primary texture, in the third image the reflection is mapped onto the lightmap (secondary) texture:

reFlect = new cTexgfx(FLOOR);
texgfx reFlect move(0,-200,0);    //reflect the scene from the following angle and position:
texgfx reFlect angle(90,0,0);
texgfx reFlect reflect(20,0,-1);
texgfx reFlect target(0);             //the reflection replaces the lightmap (like a light)
texgfx reFlect active(1);

Its also possible to map the surrounding environment straight to the cubemap (a standard cubemap must be present):

scene tfilter(3);
scene cubemap;

reFlect = new cTexgfx(Ball);
texgfx reFlect reflect(10,0,60);    //in this case 60 is ignored
texgfx reFlect target(999);
texgfx reFlect active(1);
 

To enable reflections over a secondary texture you must avoid to use mipmapping filters in you scene, use instead a non mipmapped mode, for example:

scene tfilter(3);    //bilinear anisotropic

RADIO

The Chimera engine contains a lightmap generator based on the Radiosity algorithm.
Radiosity assures the full handling of global illumination, shadows generation and efficient light distribution but, like any other raytracing legacy process, it is very slow (time heavily depends by the numbers of vertices) and requires some attention to the parameters.
The process is completely driven by the script and can be used once because the radio class -optionally- saves the generated lightmap texture (the "lightmap" is a secondary lighting textures overlapping the main texture, see the object chapter about lighmaps) for every object. This way when you launch the scene again you can use the lightmap from the previously processed scene WITHOUT having the radiosity processor redo all the calculations from start.

Take a look at the following images:

the one on the left is the original scene, in the center a new image-file generated by the radiosity processor (managed by the engine as a lightmap) , in the third image the resulting scene.
You may also disable saving the resulting lightmaps to disk and make a scene with interactive calculation every launch.

It's important to understand that Radiosity DOES NOT HANDLE point lights (i.e. invisible light sources): EVERY object, particle, flare in the scene works as a light source, ok it seems absurd but it's amazing: imagine a scene where all object are subjected to illumination  and a circle of particles is dancing in the middle of the scene, or with a simple skybox outside the window... then all the objects are lighted by all these "light" sources, with corresponding  colors and level!
Another example: a dark alley with dark windows: place a lightmaps on these windows (so they seems lighted) and place a flare on a street lamp, both flare and lighted windows act as lights brighting the scene and making proper shadows!
In short, in building a scene to be rendered with the Radiosity algorithm, keep in mind the following :
- disable (or delete) any "real" realtime "opengl" point light (do noth bother too much with this...the radio process does this automatically);
- put the "ok, I'm lighted" flag on every object you want to be part of the radiosity lighting process (eg.: object myFloor lighted(1) );
- put the "ok, I'm NOT lighted so I AM a light" flag on every object you want to act as light source (eg.: object myNeonPanel lighted(0) ...  object myMoonSphere lighted(0) );
OR:
- create flares or particles (flares and particles cannot be "lighted" so they always act as a light source)
or eventually both the solutions.

To obtain the best results there are two concept to understand: the polygon subdivision and the number of the passes of the rendering.
Polygon subdivision represent the precision level of the resulting render. Since the process works with vertices is important to "slice" large polygons in several smaller polygons to improve precision (and slow render time) ... ok ... imagine to have a floor made by two triangles (see image on the left, below).
That floor is too simple to cast shadows behind the wooden boxes because in the "box zone" there is just a sigle vertex, its possible to improve the object with a level 2 subdivision (the image on the center) or a level 3 subdivision (image on the right). Every level splits any triangle in four triangles.
The subdivision level depends from the complexity of the object itself.
In the statement table there are a couple of statements regarding general subdivision or specific object subdivision.

About rendering passes: the lenght of rendering loop (how many passes) depends after all on how much you are satisfied by the scene.
Usually Radiosity requires several passes to "work" really as a true radiosity process. Take a look at the following image: in the first passage Radiosity calculates the illumination level straight from light to object (first image on the left, notice the hard shadows and low level of illumination of the floor and the cube), THEN, in the second pass, every object accumulates light from the surrounding objects (please note that, in the right image, that the shadow is softer and the floor acquires illumination from the cube, and vice versa):

Another example, this time with coloured light sources:
left image:  in the original scene there are three unlighted objects- a red cube, a blue cube and a green cube working as lights;
middle image: the scene after one rendering pass: the walls and the middle cube are lighted by the three cubes;
right image: walls, floor and the middle cube interact with the color of each other doing a correct diffuse lighting.

radiosity class basic statements are:

optional parameters (to call BEFORE the begin process) are:

the shortest script to achieve radiosity is, for example:

myObj = new ("damned_alley");        //load some object
.....
streetLamps = new(...);                    //load some flare
....
scene start;
.....
new cRadio(-1);
radio begin;
delete cRadio;

in this mode (without parameters)  the engine automatically saves the lightmaps in the data folder (take a look, you must have a damned_alley_00_lit.tga file).

Multiple passages can ben done simply using the script syntax, for example you can do a three pass render with:

pass = 3;
while(pass > 0)
{
   new cRadio(-1);
   radio begin;
   delete cRadio;
   pass--;
}

now, something more complex to produce the four scene pass in the image:

backyard = load("walls");                //load the objects and
object backyard lighted(1);             //..specify they are to be lighted 
....
woodenboxes  = load("box");     
object woodenboxes lighted(1);
....
simplefloor  = load("floor");
object simplefloor lighted(1);
....
posterflares  = new cFlare(-1);        //load the flares and put these onto the wall poster (no, I'm not sponsored by Diesel Jeans (tm) :-)
....
dklevel = 1;                                  //sets the dark level untouched by light multiplier
litpowa = 10;                                //sets the initial light multiplier
iterator = 4;                                 //sets four pass render
while(iterator > 0)
{
    new cRadio(-1);                            //create process
    radio lowshadow(dklevel);           //sets the dark level
    radio polydiv(1);                          //leave the original polygon subdivision
    radio polyodiv(simplefloor ,3);    //...except for floor, it's a simple object so we can split it in 32 triangles
    radio litpower(litpowa);               //sets the light power multiplier
    radio lmsize(256);                       //sets the size of the lightmaps (256x256 pixels)
    radio lmangle(160);                            //sets the light angle for all the object
    radio lmoangle(simplefloor ,110);      //....expect for floor, we want it more reflective
    radio savemode(1);                    //instruct the process to do a save of the lightmaps at the end of the process
    radio begin;                              //start the process
    delete cRadio;                          //when done it clears the memory

    iterator--;                                 //pass -1
    litpowa = 1;                            //reset the lightpower (because from the second pass there is more "light" around)

   ( .... and back to the top for another pass ... )
}

WATER

Water surfaces are controlled by the properties of the water operator.
This effect is applicable on an object's surface, and these surfaces must be defined in a object.
For example, you can easily create a landscape, and a "sea" as a sub-object, represented by a plane (in 3DStudio), or a grid of vertices (25x25 is enough).
Then we apply the water effect on this "sea".
If you hate prebuilded waves and want more customization use the fluide operator.

left image: original object - center: hill random wave - right: linear wave

this snippet is taken from the "Distant Shores" scene, it loads a grid and enable the water fx on it:

//load sea surface
SEA = load("seaplane2");
object SEA scale(80000);
object SEA move(+740,-1000,+700);
object SEA rotation(-180,0,0);
object SEA diffuse(1,1,1);
object SEA active(1);
object SEA fog(1);

//add water effect to SEA object
H2O = new cWater(SEA);
water H2O speed (50,10);
water H2O wave(0,2,0.02);    //"hill" wave, 2 is a very low height (and 0.02 is the default force trimmer)
water H2O active(1);

FLUIDE

Fluide surfaces are controlled by the properties of the fluide operator (similar to water operator, but with more handling parameters).
This effect is applicable on an object's surface, and these surfaces must be defined in a object.
For example, you can easily create a landscape, and a "sea" as a sub-object, represented by a plane (in 3DStudio), or a grid of vertices (25x25 is enough).
Then we apply the fluide effect on this "sea",

this snippet is taken from the "MoonBay" scene, it loads a grid and enable the fluide  fx on it:

//load sea surface
wSurface= load("seaplane2");
.....

//add water effect to wSurface object
myPerturb = new cFluide(wSurface);
fluide myPerturb assign(wSurface,0);
fluide myPerturb speed (10);
fluide myPerturb wavetime(0.001);
fluide myPerturb addimpulse (50,50,2,100);
fluide myPerturb active(1);

FLARE

Flare class controls the properties of flares - i.e. lighting textures.
Members of the flare class can be used to create light effects such as lamps, sunlight, lens flares, etc.
Flares are either linked to the vertex of an object (e.g. a jet engine) OR freely positioned in your screen, independent from  any object independent.
You can use a single flare to create all the lights on an object - engines, navigation lights, cockpit lights and so on, or use multiple emitters from a single flare class (i.e. having the same look) to define each light.
Flares can use more than one texture, and textures can be swapped at specified intervals, to simulate light flashing and so on.
You can also cast an automatic (but customizable) "lens flare" from the same emitter.
In the example below, the engine glow is made using a single flare class with two emitters, appended to two object vertices - the engine nozzles:

now the flare can be "appended" to an object vertex or it can be standalone (sun etc.)

Some examples....

How to create a distant sun:

SUN = new cFlare(-1);
flare SUN texture(load("SUN"));
flare SUN move(14500,-16000,+500);
flare SUN size(10);
flare SUN speed(10);
flare SUN color (1,1,1,1);
flare SUN active(1);

How to put engine flares, then flashing  lights onto a starship, using three textures:

/**************** load the object ***************/
SHIP = load("starship");   
object SHIP active(1);
obj_engine = 0;

/****************engine flares ***************/
ENGINES = new cFlare(SHIP);
flare ENGINES texture(load("FLARE_BIG");
flare ENGINES add(SHIP, obj_engine, 20);    //add emitter to vertex #20
flare ENGINES add(SHIP, obj_engine, 57);    //add emitter to vertex #57
flare ENGINES offset(0,1,0,0);                     //light offset otherwise flare is "in" the model
flare ENGINES offset(0,1,0,0);
flare ENGINES active(1);

/****************positional lights ***************/

LITPOS = new cFlare(SHIP);
flare LITPOS texture(load("FLARE_BIG"));
flare LITPOS texture(load("FLARE_MEDIUM"));
flare LITPOS texture(load("FLARE_SMALL"));
flare LITPOS size(1);
flare LITPOS test(2);
flare LITPOS change(50);                //flare cycle from big to small every 50 ms
flare LITPOS add(SHIP,31,1032);    // notice a single LITPOS can be used for three lights
flare LITPOS add(SHIP,31,1214);
flare LITPOS add(SHIP,79,204);
flare LITPOS offset(0,-1,0,0);
flare LITPOS offset(1,+1,0,0);
flare LITPOS offset(2,-1,-1,0);
flare LITPOS active(1);

Flares can be linked to an object vertex. If you plan to move a set of flares thru keyframer, you must create a hidden object (a triangle is ok), then apply keyframer onto this object, and use the same fake object to generate particles.

LENSFLARE

A "lensflare" can be appended to the same emitter of the flare, for the lensflare you do not need to specify a texture because sets of lensflare are already defined for your convenience, it's also possibile to set the "brightness" of the screen when the camera is looking in the flare direction (sunlight effect),  Here is a visual of a lensflare appended to the a flare emitter (the cyan one, see previous image)

the "distant sun" code is now:

SUN = new cFlare(-1);
flare SUN texture(load("SUN"));
flare SUN move(14500,-16000,+500);
flare SUN size(10);
flare SUN speed(10);
flare SUN set(0);                    //choose the flareset
flare SUN lens (0.6,0.8,12,0); //modify some parameters...
flare SUN color (1,1,1,1);      //this is ignored except for flareset #3
flare SUN active(1);

let's analyze the parameters: flare ID set(0...5) use predefined flare set n, ranging from 0 to 5 (for now), indicatively these sets are (from 0 to 5):

Please note that flareset #3 (in blue in the upper image) is a special set of flares, which doesn't use the preset colors but a color set defined by user.
To produce the following flare just pass flare SUN color (1,1,0,1);

As a first parameter of flare SUN lens (0.6,0,12,1) we have the dimension of the flare, and this depends from the scene.
The second parameter of flare SUN lens (0.6,0,12,1) defines the brightness of flare (when observer "looks" in the flare direction), this is the difference between
flare SUN lens (0.6,0,24,0)  (in the previous image) and flare SUN lens (0.6,0.8,24,0) below:

the third parameter of flare SUN lens (0.6,0,24,0) defines the number of sides of the flare, this is the difference between
flare SUN lens (0.6,0,24,0) (below, first image) and flare SUN lens (0.6,0,6,0) (below, second image):

the last parameter of flare SUN lens (0.6,0,24,0) defines if flare must be filled or not, this is the difference between
flare SUN lens (0.6,0,24,0)  (below, first image) and flare SUN lens (0.6,0,24,1) (below, second image):

PARTICLE

particle statements control the properties of particle systems.
Particle systems can be dynamic or static, generated by spare points or from an object's vertex, and point-defined or volume defined.
Like flare particle system can be linked to an object vertex or leave alone, a single system can use more than one emitter.
Some visual examples (from left to right):
standalone particle system, generated from a point, with all-axis random acceleration;
standalone particle system, generated from a point, with Y vertical acceleration;
standalone particle system, generated in a a defined area (and not from a point);

Particle systems linked to an object can act both in LOCAL and WORLD space. Local space means that particle generation, distribution and movement are relative to object orientation, and in global space are relative to "real" world orientation. For example, looking at the flare sample, appending a single particle system to a ship, and defining two emitters related to the two engine ship is a nice way to simulate gas exhaust... then if you move the ship, if the PS (particle system) is in local space, gas is coherent with the ship and will rotation with it, while in world space the PS leaves trails (altough is always fixed to the vertices).
PS's are dynamic by default (because they are used largely for simulating dynamic entities like fire) but you can "freeze" them, just in case you need say, a galaxy... ;)

For a particle system lnked to an object use:

Standalone (not object linked) particle system can use:

To create a single standard emitter:

FIRE = new cParticle(-1);
particle FIRE texture(load("SUN"));
particle FIRE move(14500,-16000,+500);
particle FIRE size(10);
particle FIRE rgb1(1,1,0.5,1);    //set starting color to yellow
particle FIRE rgb2(0,0,0,1);      //set enging color to black
particle FIRE active(1);

now add a slow movement on the Y axis

particle FIRE direct (0,0.2,0);  
particle FIRE accel (0,0.2,0);

By now, tired of fire, we add this cool PS to the usual double-engine of the usual boring ship (the code is near the same as flares!!!):

SHIP = load("starship");
object SHIP active(1);
obj_engine = 0;

ENGINES = new cParticle(SHIP);
particle FIRE texture(load("FLARE_BIG");
particle FIRE add(SHIP, 0, 20);    //add emitter to vertex #20
particle FIRE add(SHIP, 0, 57);    //add emitter to vertex #57
particle FIRE offset(0,1,0,0);
particle FIRE offset(0,1,0,0);
particle FIRE active(1);

The next advanced example produces, thru simple math, concentric waves of particles:

scene move (0,0,-160);

SYS = new cParticle(-1);
particle SYS texture(load("STAR"));
particle SYS total(250);
particle SYS size(5);
particle SYS rgb1(1,1,1);
particle SYS rgb2(1,1,1);
particle SYS dead(0);
particle SYS active(1);

dist = 8000;
rings = 5;
ringstar = 50;
dr = 1100/(rays-1);
n = 0;

for(ir=1; ir<=rings; ir++){
    r = dist+(ir-1)*dr;
    for(it=1; it<=100; it++){
        t=n*6.283185308/ringstar;
        particle SYS single(n,r/100*cos(t),r/100*sin(t),0);
        n++;
    }
}

scene start;
while(1){
    for (t=0;t<360;t+=0.01){ particle SYS angle(t,t,t); }
}

As particle systems can be linked to an object vertex, if you plan to move a particle system thru keyframer, you must create a hidden object (a triangle is ok), then apply keyframer on that object.

LIGHT

light statements control the properties of lights, i.e. the illumination level of the objects and the entire scene.
A "light" is an invisible entity (at least .... until you append a flare ;-) and in that case we can only decide the position and the colors, but a light can also be "linked" to an object, like flares and particles, so the best way to make moving dynamic lights is to link this entity to a moving object.
NOTE: Although the Chimera engine has no light limit, some standard openGL implementations do not support more than 8 lights.

like particles and flares the light can be positioned "stand alone" or attached to a moving or still object:

Important notes about lights:
- Light controls bump-mapping and shadows, without light these effects are disabled;
- Shadows are cast by ALL lights defined, be aware that too many lights casting shadows slow down the scene;
- Bump-mapping depends from first light only;
- you can position a light with a keyframer only by applying a keyframer on an object (visible or invisible) and linking the light to the object.

//TODO : Chimera supports now Volumetric Light / Light Scattering and the usual "GodsRays" coming from a single obiect

SKYBOX

skybox statements controls the appearance of the skybox , i.e. the background of the scene landscape,
There can be only one skybox at a time, but you can dynamically create and dispose of them.

to create a decent skybox, you must have six textures named "picname_xxx" where "xxx" is the orientation (left, top, right, bottom, front and back). For a skybox and a cubemap, for example SPACESTATION_FRONT.TGA and SPACESTATION_BOTTOM.JPG are both valid, the orientation follows the "standard" cubemap defined by nVidia in his demos

snippet from Night Fly scene:

scene cubemap;            //enable and load cubemap reflections

SKY = new cSkybox;
skybox ("cubemap");    //skybox uses the same textures so lanscape is coherent with reflected stuff
skybox rotation(0,0,0);
skybox active(1);

KEYFRAMER

The keyframer (framer in short) class is an abstract class that builds an interpolated path, derived  from a series of control positions.
The path can be assigned both to camera and objects, theoretically with just 4 control points you can define a circular path.

the keyframers used by stars from Stardance scene
(use V key in debug mode to display the keyframers)

a path is defined by a series of control points, each of which has a distance of a certain number of frames from the next. Imagine a flat circular path... You can define this path using 4 control points, and since control points usethe same convention as the "C" language , i.e. arrays starting with 0 not 1, we have for example:

point #0:    x = -10 y = 0 z = 0        //west
point #1:    x =   0 y = 0 z = +10      //north
point #2:    x = +10 y = 0 z = 0        //east
point #3:    x =   0 y = 0 z = -10      //south

you first have to define the total control points you will need, we define 4 control points, every point uses 300 frames to move the object (or the camera) to the next point:

CIRCLE = new cFramer(-1);
framer CIRCLE total(4,300);

We define the control points, and we also specify the rotation, although in this specific case, the rotation is unused:

framer CIRCLE move(0,-10,0,0);
framer CIRCLE rotation(0,0,0,0);
framer CIRCLE move(1,0,0,+10);
framer CIRCLE rotation(1,0,0,0);
framer CIRCLE move(2,+10,0,0);
framer CIRCLE rotation(2,0,0,0);
framer CIRCLE move(3,0,0,-10);
framer CIRCLE rotation(3,0,0,0);

finally we start keyframer:

framer CIRCLE start;

If you want to vary the speed of execution (for example if you want to accelerate for half the circle), you can specify a different number of frames for every point:

framer CIRCLE frames(0,300);
framer CIRCLE frames(1,200);
framer CIRCLE frames(2,100);    
framer CIRCLE frames(3,200);

if you do not want to specify the number of frames when defining the path (e.g. because you are building a path with some formulae),you can allocate the control points one at a time at every step, for example:

CIRCLE = new cFramer(-1);
framer CIRCLE add(0);           //add a point...
framer CIRCLE frames(0,300);    //... for 300 frames
framer CIRCLE move(0,-10,0,0);  //define the point
framer CIRCLE rotation(0,0,0,0);
framer CIRCLE add(1);           //add another point...
framer CIRCLE frames(1,200);    //... for 200 frames
framer CIRCLE move(1,-10,0,0);  //define the point
framer CIRCLE rotation(1,0,0,0);
.....

You may use status to control path completion and/or object position, this an example of a keyframer construction, execution and deletion after it's finished:

ID = new cFramer(-1);
framer ID total(3,300);
framer ID move(0,3226,-5760,136);
framer ID rotation(0,97,48,0);
framer ID move(1,2987,-2983,-77);
framer ID rotation(1,116,61,0);
framer ID move(2,2315,-806,-479);
framer ID start;
while( status cFramer(ID)) sleep(50);
delete cFramer(ID);

DEFORM

deform class is an abstract class. Like texgfx, this class defines geometric operations to apply to an object, like spin, scale etc.
you can apply more than one deform on an object, or define more than one effect per deform instance.

these are specified effects:

Please remember: the deform effect is constant, you do NOT need to control it. For example, this script shows a rotating planet:

EARTH = load ("planet");
object EARTH active(1);

ORBIT = new cDeform(EARTH);
deform ORBIT spin(0,0.2,0);        //spin around Y axis by 0.2 degree steps
deform ORBIT active(1);

scene start;

If you want to stop the planet, simply specify:

deform ORBIT active(0);

or delete the effect:

delete cDeform(ORBIT);

Note:

ORBIT = new cDeform(EARTH);
deform ORBIT spin(0,0.2,0);        //notice the spin around Y axis by 0.2 degree steps
deform ORBIT active(1);

it's basically like:

for (angle=0;angle<3000000;angle+=0.2)
    object EARTH rotation(0,angle,0);

the difference being  that in the former case,  deform operates in a parallel thread (not "breaking" the script flow).

STATUS

status function returns the "active" state of an entity and other information about positions etc, it's very useful to check the status of a keyframer (running or not), positioning of the objects (to make something interactive) and keyboard/mouse user selection.

ACTIVE STATUS

currenlty is usefull only with keyframers because they go "disabled" automatically

the scene execution is frozen until keyframer has completed:

framer ID start;                                   //start keyframer
while( status cFramer(ID))                   //wait while status is true (active)
     sleep(50);   
delete cFramer(ID);                            //delete and continue execution

POSITION STATUS

Positional status (eg.:status cObjPX(ID)) is useful when you want to interact with the object and you dont know the exact position:

and, for the camera:

For example: you have an object STAR, and you apply a keyframer on STAR, so the STAR moves and you dont know the exact position, 'cause keyframer is interpolating between positions, but you want to move a light accordingly with the STAR object ... you would recover the position thru cObjPX,PY ... and apply that position to light:

STAR = load("STAROBJECT");
LITE = new cLight();
STARPATH = new cFramer(STAR);
......
framer STARPATH start;              
while( status cFramer(STARPATH)){
    x = status cObjPX(STAR);
    y = status cObjPY(STAR);
    z = status cObjPZ(STAR);
    light LITE move(x,y,z);
}

or, in the shortest (and less readable) form:

while( status cFramer(STARPATH))
    light LITE move(status cObjPX(STAR),status cObjPY(STAR),status cObjPZ(STAR));

USER DETECTION

in this sample "status" monitors the spacebar key, if it's down rotations the object CUBE:

angle_y = 0;
while(1){
    isClicked = status keystate(49);
    if (isClicked)
    {
        angle_y += 2;
        object CUBE rotation(0,angle_y,0);
    }
    sleep(100);
}

in this sample "status" monitors detection of an object by the user thru the right-mouse button, if this happens the color of the selected object changes to yellow and previously selected object color is restored to white:

NONE = -1;
oldObject = NONE;
while(1)
{
    isClicked = status keystate(2);
    if (isClicked)
    {
        currObject = status selection(0);

        if (oldObject != currObject && currObject != NONE)
            object oldObject diffuse(1,1,1);

        if (currObject != NONE)
            object currObject diffuse(1,1,0);

        oldObject = currObject;
    }
    sleep(100);
}


enable the keyboard, assign the right rotation (in 2 degree step) of the scene on the right cursor arrow.
With status we can replicate (or customize) the camera movement, for example this this code is equivalent:

angle_y = current_camera_y;
while(1){
    if (status keystate(39))
    {
        angle_y += 2;
        scene rotation (0,angle_y,0);
    }
}