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 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 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 preProcess function serves two purposes :

Expand Replicate With

Firstly, the 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 default_light, default_camera, default_entities and default_spawn to get defaults for these particular properties.

This function will also initialise the following properties:

level.removed

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

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 loadLevel, which uses the information in calls to attach on the manager’s 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 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 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 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 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 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 validate_other and process_other methods.

Fork me on GitHub