Level Parser¶

If you need to extend or modify the level parser – or are, perhaps, simply curious – this section describes how the level parser works.

When a Gamma manager loads a level, it parses the level specifications with it’s gma.manager.levelParser object. The gma.levelParser is designed to create gamma objects from the level specification object. By default the level parser object will be an instance of gma.levelParser.

Level parsing begins with the processLevel(level) method which does the following:

Check to see if the level has been previously processed
- If it has, then return the level, parsing the level stops here
Set any defaults on the level using gma.levelParser.preProcess
Process the level

Determining if a level is already processed¶

The level parser will consider a level as already processed if it has a property on it called processed, which is set to true.

The levelParser will ensure this property is set to true on the level once it has been processed.

Pre-Processing the level¶

The gma.levelParser.preProcess function serves two purposes :

Expand Replicate With¶

Firstly, the gma.utils.expandReplicateWith method is used to expand the level specification where the replicateWith key has been used. See ReplicateWith in the level creation topic.

Set up all necessary defaults on the level¶

Secondly set up defaults for a level’s light, camera, entities and spawn location. This is done using gma.levelParser.default_light, gma.levelParser.default_camera, gma.levelParser.default_entities and :metho: properties.

This function will also initialise the following properties:

level.removed¶

This list is used by gma.manager.twitch when it calls gma.manager.removeDead, which then uses it to store references to any entities that have died with a reincarnate tag.

gma.manager.loadLevel uses this list of reincarnatable enemies to set their status back to alive if when the level is reloaded.

level.following¶

This is a dictionary that holds any item that specifies it follows another item. Currently only the light and camera may specify this, and they are limited to following the character.

The dictionary is then used by gma.manager.loadLevel, which uses the information in calls to gma.sceneHelper.attach on the manager’s gma.manager.sceneHelper.

level.levelExtras¶

References to any level specific items (currently, just lights and camera) that have been added the the rendered scene. This list is maintained so that when gma.manager.clearLevel is called, it knows what extra items in the current scene belong to the current level and must be removed. (This allows lights and other objects to be permanently added to the scene, regardless of the currently level.)

Processing a level¶

The levelParser is designed such that processing each item in the level is done independently of other items. This is accomplished by a suite of validate_* and process_* functions (the star represents the property on the level that these functions will operate on). Gamma provides processing functions for entities, light, camera, other, utility, following, template, removed and levelExtras.

For example to process entities in a level specification,

var myLevel = {
    entities : [
        {left:19, right:30, top:9, height:3}
    ]
};

Gamma provides the following functions in gma.levelParser:

self.validate_entities = function(manager, key, value, level) {
...
};

self.process_entities = function(manager, key, value, level) {
...
}

self.default_entities = function(manager, key, value, level) {
...
}

Arguments to validate and process functions¶

Each validate and process function will receive, in this order, a manager object, the key of the property being processed, the value of the property being processed, and the level object being processed.

Changes made to the level object are permanent and cannot be reversed.

Validate function¶

The validate function checks whether it is possible to create a gamma object with the properties specified. These functions will simply return a Boolean saying whether the information is valid or not.

This function is allowed to transform the data to be valid for processing.

Process function¶

The process function will turn each object specification into an actual gamma object. This way gma.manager.loadLevel does not need to worry about whether the objects in the level are gamma objects or just specifications.

Default function¶

The default function is optional. It is used by gma.levelParser.preProcess to set up a default for the level where one is not specified.

Processing a Custom Type¶

You can create you own type of object in the level parser. For example, say we want to make the levelParser aware of a skybox property on the level, then all we need to do is create validate_skybox and process_skybox functions. Then optionally create a default_skybox function and override gma.levelParser.preProcess such that it is used.

var myLevelParser = (function() {
    var self = gma.levelParser();

    var oldPreProcess = self.preProcess;
    self.preProcess = function(level) {
        level = oldPreProcess(level);

        level.skybox = level.skybox || self.default_skybox();
    };

    self.validate_skybox(manager, key, value, level) {
        //validate the information given for the skybox property here
    };

    self.process_skybox(manager, key, value, level) {
        //Do any necessary processing/transformation to the information given for the skybox here
    };
})();

Then we just set this new levelParser on the manager, and then when we use gma.manager.loadLevel, it will be aware of the skybox property and handle it as you have specified.

Note

If the levelparser can’t find an associated validate and/or process function for a property, it will use the generic gma.levelParser.validate_other and gma.levelParser.process_other methods.