LimpetGE Reference Manual

Audio Classes

The LBase class

This class needs to be the "base" for the "Scene" class, or more specifically, the "Scene" class needs to derive this.

All methods and properties follow the LimpetGE naming convention (follows the regex: "_?[lL][A-Z][A-Za-z0-9_]+"), so programmers can put any method/property in the "Scene" class so long as the names do not match that.

Implementing code should look something like....

class Scene extends LBase {
    constructor(args)
    {
        super(args);
    
        // Then for example, 
    
        this.hurt = 0.0;
        this.ambientLight =  vec3.fromValues(0.3, 0.3, 0.3);
        this.directionalLightColor = vec3.fromValues(1.0, 1.0, 1.0);
        this.runme = true;
        this.life = 100;
        this.bescape = false;
        ...
        ...
    
    }

    lLoop: function(delta)
    {
        ....
        ....
    }
    ....
    ....
    ....
}

LCamera class

An instance of the "LCamera" class is created when the "Scene" (derived from "LBase") class is, and a copy of the reference is placed in the global "lCamera" variable - as well as the property "lCamera" on the scene object.

When created, it uses the same "args" argument as when the "LBase" constructor is called.

This also uses a similar interface to the "LObject"/"LWObject"/"LIObject"/"LVirtObject" classes, so the camera can be used as a base for collision detection, and/or included in the Dynamic sparse array.

Regarding movements and rotations. There are in effect two modes...

• 3D mode"
• Flat mode

In "3D mode" movement can occur any which way, like a spaceship. Methods for this are:

• obj.move(...)
• obj.rotate(...)
• obj.rotateHere(...)

In "Flat mode" movement occurs as though travelling over a floor, with a definite "up". Methods for this are:

• obj.moveFlat(...)
• obj.rotateFlat(...)
• obj.rotateFlatHere(...)

The other movement and rotational methods can be used for either.

LGroupDef class

A "group" is an object with no structure. That is it can have children, dynamic or static collision functionality and so on, but nothing gets drawn by it itself.

This class is the structure base for the object. Implemented as....

var grpdef = new LGroupDef();
var game_object = new LObject(grpdef, whatever);

LStructureDef class

The structure definition is where the "building" of objects occurs. Building happens by creating a number of "shapes" using one of the add....(...) methods.

The "add...(....)" method takes a single argument which is a Javascript object consisting of named variables. Ones that are not applicable to that particular shape are ignored.

These named arguments are consistent throughout the methods, so I will document those in a separate section,

As for the "add....(....)" method arguments:

position	A transformation matrix ("mat4") that is applied to the component after creation, to place it in the appropriate place of the object. This defaults to the identity transformation matrix (no effect).
texturecontrols	A list of "LTextureControl" instances, (or "LTextureColor" instances) that define which texture (or color) to use in the collage of textures (provided to the shader) in the "args.texture" (args.colors) argument supplied in the constructor. This defaults to using the entire texture. There is a separate section for this as well.
texturecontrol	Mutually exclusive to the "texturecontrols" argument. This is a single instance of the above, and it is applied to all textures of the component.
hold	A list of "LI_***" global variables for which parts NOT to draw. This can be: LI_FRONT - Do not draw front LI_BACK - Do not draw back LI_SIDE - Do not draw side (of the cylinder) LI_SIDE + number - Do not draw "nth" side of a polygon (starting at 0) LI_TOP - Do not draw top of blocks LI_LEFT - Do not draw left of blocks LI_BOTTOM - Do not draw bottom of blocks LI_RIGHT - Do not draw right of blocks
corners	This only applies to those that are added to the static collision detection sparse array. If this is omitted then calculate the smallest corner block that is possible. If this is "null" then do not include corners from this component. If this is a list of "vec3" coordinates then use that. Note - the "args.position" matrix are not applied to this in this case.
collsize	The size of "sub-blocks" the corner blocks is to be divided into in the event of non-cartesian rotation
size	Only applies to the "addBlock" method. This is a "vec3" coordinate. The block created has the opposite corners of that coordinates, and the negative of that.
coords	Some kind of array of [x, y] coordinates or [x, y, z] coordinates (depending on the specific method) to build the component. Described below.
depth	If this is defined it is the depth of the component along the "z" axis. The exception to that is the "addBezierBlock" method, where it is the depth that is perpendicular to the bezier "curved plane(s)".
radius	For "round" type components this is the radius of the circular part.
segments	For "round" type components this is the number of polygons that go around the circumference. Defaults to something sensible
xsegments	For Bezier shapes, the number of polygons that go "left to right" in the matrix provided.
ysegments	For Bezier shapes, the number of polygons that go "top to bottom" in the matrix provided.
insideout	LimpetGE employs "gl.CULL_FACE, and normally components cannot be seen from the "inside". If this is set to the boolean "true" then this reverses that and it can only be seen from the inside, not the outside. Originally written for panoramas.

The specific "add....(...)" methods. These can be moved/rotated using the "position" argument to an appropriate place on the structure.

The "CULL_FACE" option in the OpenGL routines are enabled, so things cannot be seen from "inside" blocks, or from the "back" for patches. Also there are problems if you do not go "anti-clockwise" when you should.

This will not go into the mathematics and generic mechanics of Bezier patches, there is enough resource on the web for that, it just goes into the LimpetGE implementation of this.

The coordinates entry looks something like the following:

    coords: [
        [[0.2,   0.0, 0.0], [0.2,    0.15, 0.0], [0.15,  0.3,  0.0], [0.0,   0.3,  0.0]],
        [[0.2, -0.15, 0.0], [0.2,    0.0, -0.3], [0.0,   0.3, -0.3], [-0.15, 0.3,  0.0]],
        [[0.15, -0.3, 0.0], [0.0,   -0.3, -0.5], [-0.2,  0.0, -0.5], [-0.2,  0.15, 0.0]],
        [[0.0,  -0.3, 0.0], [-0.15, -0.3,  0.0], [-0.2, -0.15, 0.0], [-0.2,  0.0,  0.0]],
    ],

In other words, an array of "lines", and each line being an array of "coordinates", each coordinate being a "vec3" array.

The system works by:

1. Creating "Bezier lines" using the coordinates on each of the "lines arrays"
2. Creating a number of points, as reresented by the "xsegments" argument (defaults to 16) along these "lines" equi-distant from each other, (creating a default total of 17 lines).
3. This number of "perpendicular-ish" "sub bezier lines" are creating using the appropriate "nth" point of each point.
4. These "sub-lines" are then also divided by a number represented by the "ysegments" argument (again, defaults to 16), creating a number of "sub-points" along each line, (creating a default total of 289 "sub points": 17 x 17).
5. These "sub points" form a "mesh" that is used as a base to create the polygons for the Bezier patch.

The upshot of which, is that the four "corners" of the above array are (usually) the only coordinates points that the sheets actually "map" to (or is "pinned" to). The rest of the coordinates control the "curvature" of the sheet.

For "Bezier Blocks", regarding the "hold" and "textureconrols" parameters, the LI_TOP, LI_LEFT, LI_BOTTOM and LI_RIGHT controls represent the appropriate "side" as represented by the above array.

The "coords" array must have a width of at least two, and a height of at least two. Also there needs to be the same number of coordinates in each line. With those two criteria in mind,   the array can be of any size.

LObject class

The main object class for the game. An object is a distinct "thing" in the scene, that can move independently of other objects if dynamic.

This class was not designed to be "derived", however, there is nothing stopping the programmer from doing so. Care should be taken that there is no "name" clashes as the normal "LimpetGE" naming conventions do not apply to the methods and properties.

Regarding movements and rotations. There are in effect two modes...

• 3D mode"
• Flat mode

In "3D mode" movement can occur any which way, like a spaceship. Methods for this are:

• obj.move(...)
• obj.rotate(...)
• obj.rotateHere(...)
• obj.moveMat(...)

In "Flat mode" movement occurs as though travelling over a floor, with a definite "up". Methods for this are:

• obj.moveFlat(...)
• obj.rotateFlat(...)
• obj.rotateFlatHere(...)

The other movement and rotational methods can be used for either.

LWObject class

This supports the same methods and properties as the LObject class. In fact, it is derived from it. However it is optimised so that it can only be added at the top level on lScene using the "lPlace(....)" method. Things will go wrong if an LWObject instance is used otherwise.

LIObject class

This supports most of the same methods and properties as the LObject class. In fact, it is derived from it. However when "mkvisible" or "procpos" is called on the parent (or ancestor), the functionality is not automatically called here. Therefore those functions need to be called independantly on these objects.

LVirtObject class

The Virtual Object. This has no structure, and is not included in the game object tree. However it can be used for extra dynamic collision functionality. For instance, it is useful to determine if something can go somewhere without moving it, or to create a temporary area to see if something, possibly specific, moves there.

These can "move", and perform ray tracing, like a normal object if required.

LStaticGroup class

This class instances can be included in the game object tree, but themselves have no structures, or game objects, associated with them. They simply pass respective calls to their children.

LGroup class

This is a quick method for creating a "one off" group object.

var grp = new LGroup(args, control)

var grp  = new LObject(new LGroupDef(args), control);

This then can be included in the game object tree, collision sparse arrays or anything else as per a normal "LObject" type.

LStructure class

This is a quick method for creating a "one off" structures and the associated object.

var obj = new LStructure(shader, args, control)

var obj  = new LObject(new LStructureDef(shader, args), control);

Components can be used by using the "structure" property of the object:

obj.structure.addBlock({........});
...

This then can be included in the game object tree, collision sparse arrays or anything else as per a normal "LObject" type.

Textures

Textures are a bit peculiar in LimpetGE in that they need to be handled in shaders a lot more than other aspects. Also, if flat colors are used, these are represented as "mini textures", being a series of one-pixel points, each one a color to be used in the objects.

The overall mechanism that is employed is:

• An image, that is in fact a "collage of images", is defined at the time the "StructureDef" is created.
• "Sections" of this collage, representing separate images in it, are defined in an instance of the "LTextueControl" class.
• Each "component" that is added to the structure has a number of textures it emplys (how many defined by the component). Which ones for what are defined in an array, or object, passed in the "texturecontrols" argument.

Note: When defining colors in LimpetGE, they are defined using a "vec4" type array, representing red, green, blue and alpha values respectively. Each value is a float between 0.0 and 1.0.

The texture loading is handled in the "doInitBuffer" function of the specific shader (documented in the Shader section), which is programmer controlled. The following applies to the "standard" shaders supplied, and is recommended to follow this convention as much as possible.

In the "args" argument object of the "LStructureDef" constructor, - (an instance of this is passed as an argument to doInitBuffer) one of the following is passed:

• args.texture : This is a string representing the URL of a texture collage.
• args.color : This is a "vec4" array representing the color to use for all surfaces.
• args.colors : This is an array of "vec4" arrays representing colors to be used on surfaces.
• args.rawtexture : This is a re-loaded texture object containing the collage of images to use.

When creating collages of images, it is recommended the collage image is "re-scaled" so that the pixel height and width is equal to (2 ^ n) - where "n" is any integer. In other words, the width is one of 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 etc pixels wide, and ditto for pixels high. They need not be the same, just 2 ^ n.

When the components of the structure are created, using the "add....(...)" methods, a "texturecontrols" argument is supplied, which can contain:

• A list or a number keyed object containing a number of "LTextureControl" instances (see below).
.
• A list or a number keyed object containing a number of objects returned by the "lTextureColor(size, number)" function (see below).
.
• LTEXCTL_STATIC_LIST - This is a global constant that evauates to an infinite array consisting of virtual "LTextureControl" instances that represent the entire texture image/color.
• An array returned by the "ltextureColorAll(size, num)" function - see below
• An array returned by the "ltextureList(LTextureControl instance)" function - see below

LTextureControl class

This defines which part of a texture image collage to use for a specific surface. An instance itself does not contain any texture/image data itself, just the geometric "slice" or "rectangle" of the texture to use for the surface.

The "scale" of these units can be anything so long as consistence. For example, if a collage is two images high, and four images wide, then:

• The image_size can be [4, 2]
• The base can be [1, 0] for the second image along on the bottom row
• The size can be [1, 1] for the image

The above can be used regardless how wide or high the images in the collage are (as long as they are all the same).

Images can be "inverted" or "reflected" by using negative values in the "size" argument, in this case, the "base" should be moved to reflect this, so for the above example for the same "section" to be reflected as though looking at a reflection on water (reflected vertically)...

• The image_size: [4, 2]
• The base: [1, 1] for the second image along on the bottom row, top left corner
• The size: [1, -1] for the reflected image

There is a global constant - LTEXCTL_STATIC - that represents a LTextureControl instance that includes the entire collage - equivalent to "LTextureControl([1, 1], [0, 0], [1, 1])".

To apply images, or parts of the collage, the "texturecontrols" array is used. Which ones to which surfaces the "LI_*" keys are used for keyed objects, (or those particular positions in an array), for instance, imagine a dice face collage that looks like:

Note - the dimensions of the image has been padded out to obey the "2 ^ n" criteria for images.

Then - this is applied by...

var dice_struct = new LStructureDef(shaderSimple, {texture: "dice_faces.png"});

var die_one   = new LTextureControl([4, 2], [0, 1], [1, 1]);
var die_two   = new LTextureControl([4, 2], [1, 1], [1, 1]);
var die_three = new LTextureControl([4, 2], [2, 1], [1, 1]);
var die_four  = new LTextureControl([4, 2], [0, 0], [1, 1]);
var die_five  = new LTextureControl([4, 2], [1, 0], [1, 1]);
var die_six   = new LTextureControl([4, 2], [2, 0], [1, 1]);

var dice_cube = new LObject(dice_struct, null);

dice_cube.addBlock({size: [1, 1, 1],
                    texturecontrols: lIndArray([
                            [LI_FRONT,  die_one],
                            [LI_BACK,   die_six],
                            [LI_TOP,    die_three],
                            [LI_LEFT,   die_two],
                            [LI_BOTTOM, die_four],
                            [LI_RIGHT,  die_five],
                    ]));

Note: The "lIndArray" function changes array pairs into a key-value entry in an object. See later this document.

Alternatively, if you look at the "LI_*" values, the "txturecontrol arguments could be written..

dice_cube.addBlock({size: [1, 1, 1],
                    texturecontrols: [die_one, die_six, die_two, die_three, die_five, die_four]);

Any entries omitted, or are "null", the surface will not be drawn. Same as including it in the "hold" argument.

The texture will automatically stretch or shrink in each dimension independently so that it is the smallest size that will cover all parts of the surface.

Colors on surfaces

At time of writing, LimpetGE does not include "static colors" for individual surfaces, however, this can be done using textures designed for the purpose, and some helper functions exist to do this.

If the "color" argument is supplied with the appropriage color values in the LStructureDef constructor (using standard "shader" routines), then a texture image is created one pixel wide and one pixel high consisting of that color. Omitting "texturecontrols" argument from the "add....(...)" componenet creation methods means that all the image is used for all surfaces, in effect coloring the object that color.

Should the "colors" argument is supplied, with an array of colors, then an image 1 pixel high, and the array length pixels wide, is created and used as a texture.

When componenets are then created using the "add....(...)" methods, the "texturecontrols" array or list can pass LTextureControl objects returned using the "lTextureColor" function. This consists of:

For example:

var colors = [
                [1.0, 0.0, 0.0, 1.0],   // red
                [0.0, 1.0, 0.0, 1.0],   // green 
                [0.0, 0.0, 1.0, 1.0],   // blue
                [0.5, 0.5, 0.0, 1.0],   // yellow
                [0.5, 0.0, 0.5, 1.0],   // purple
                [0.0, 0.5, 0.5, 1.0],   // turquoise
                [0.0, 0.0, 0.0, 1.0],   // Black
                [0.0, 0.0, 0.0, 1.0]    // Black
            ];
// Above padded out with "black" so it is 2 ^ n in length

var red       = lTextureColor(8, 0);
var green     = lTextureColor(8, 1);
var blue      = lTextureColor(8, 2);
var yellow    = lTextureColor(8, 3);
var purple    = lTextureColor(8, 4);
var turquoise = lTextureColor(8, 5);

var cube_struct = new LStructureDef(shaderSimple, {colors: colors});

var cube = new LObject(cube_struct, null);

cube.addBlock(size: [1, 1, 1],
              texturecontrols: [red, green, blue, yellow, purple, turquoise]);

Applying textures to surfaces

Imagine the object center is at the origin, and the texture image is at a positive value along the Z axis, perpendicular to it, but the right way up regarding the X and Y axis, then the way the textures are applied is:

Some helper routines used in textures. Used in shader routines if anywhere.

LAssets class - LimpetGE assets

Games require various ancillary "assets", or "files" to run. It does not always make sense that these are downloaded asynchronously as required the way a web browser does, or necessarily rely on the cache to stop duplicate downloads. There is a case for pre-downloading these.

In order to achieve this LimpetGE provides the "LAssets" class, which facilitates downloading images, sounds and 3D modelled objects ("XXX.obj" files). It downloads these, stores them in Javascript "Blob" objects, and deploys these where appropriate.

Due to the asynchronous nature of browser downloads, these need to be performed before the game is run, not at the start of it. When download is complete an "event" is run from the class that facilitates starting the actual game. Something like:

For the above, in the HTML file, the body tag would include the attribute: onload="do_onload();" to instigate this. It would also have a "span" or "div" element with an id="inprogress" attribute, and a disabled input button button like: <input type="button" id="playbutton" disabled="disabled" value="Play game" /> used to start the game.

To access the assets themselves, use the "asset.data" property:

The specification:

LKey class

The keyboard key control object. This is used internally by the "lInput" object, but can be used outside that if required - but normally is not.

The lInput oject

This behaves like a static class instance. It is used to control keyboard and mouse button input. Functions and methods are:

The global variables "lDoDown" and "lDoUp" are used internally for this functionality. The "HTML" section of the documentation goes further into this.

LPRNG and LPRNGD class

A predictable random number generator. Designed for speed rather than "true randomness", should be good nough for games.

The LPRNGD class is identical with the exception it returns a floating point number, not an integer.

Transformation Matrix Helper Functions

Various helper functions exist to assist transformation matrices, primarily to place objects.

HTML Helper Functions

A number of functions exist to assist creating the HTML containing page for the game...

For use if the "lElelemnt(...)" function it is best to show by example.

    document.getElementById("container").appendChild(
        lElement("table", null, null, [
            lElement("tr", null, null, [
                lElement("td", null, "Top left"),
                lElement("td"),
                lElement("td", null, "Top right"),
            ]),
            lElement("tr", null, null, [
                lElement("td", {colspan: "3"})
            ]),
            lElement("tr", null, null, [
                lElement("td", null, "Bottom left"),
                lElement("td"),
                lElement("td", null, "Bottom right"),
            ]),
        ])
    ]);

Will produce the same DOM section if the folowing HTML was used (whitespaces added for readability):

<table>
    <tr><td>Top left   </td> <td></td> <td>Top right   </td></tr>
    <tr><td colspan="3"></td>                               </tr>
    <tr><td>Bottom left</td> <td></td> <td>Bottom right</td></tr>
</table>

Other Miscellaneous Functions