gulp-jbb-profile

Compile jbb profiles form specification files.

Installation

Install package with NPM and add it to your development dependencies:

npm install --save-dev gulp-jbb-profile

Usage

var jbb_profile = require('gulp-jbb-profile');

gulp.task('profile', function() {
    return gulp
        .src([ 'specs.yml' ])
        .pipe(jbb_profile({
            'name': 'my-profile'
        }))
        .pipe(gulp.dest('build'));
});

Options

• name

  The name prefix of the file to generate. If missing, the filename of the input file will be used. The compiler will generate an -encode.js and -decode.js file with the encoding and decoding instructions for your profile.

Specification Example

The following is a very simple specifications file that defines the properties of two objects: Vector2 and Vector3:

@uuid: 1
@revision: 1

Vector2:
    properties:
        - x
        - y

Vector3:
    extends: Vector2
    properties:
        - z

Specification Syntax

The syntax specifications file is a yaml data file that contains all the javascript objects to be supported, along with their properties. For example:

THREE.Vector3:
    properties:
        - x
        - y
        - z

There are various other properties available, explained in the following sections.

@xxx - Meta properties

You can optionally specify various metadata properties for your profile:

• @uuid: Specify the unique ID of this profile table (32-bit)
• @revision: Specify the profile revision
• @include[.encode|.decode]: Include the specified file (globally or only on encoding/decoding).
• @require[.encode|.decode]: Require the specified node module (globally, or only on encoding/decoding).

For example:

@uuid: 0x0100
@revision: 1
@include: lib/CustomFunctions.js
@include.encode: lib/EncodeFunctions.js
@require:
    THREE: three

extends/depends - Inheritance

Using the extends property you can define inheritance of properties from another object:

THREE.Object3D:
    properties:
        - position
        - rotation

# This will also inherit the properties
# of THREE.Object3D
THREE.Scene:
    extends: THREE.Object3D
    properties:
        - children

# This will only make sure that instances of THREE.Person are 
# tested before THREE.Object3D. No properties or are inherited.
THREE.Person:
    depends: THREE.Object3D
    properties:
        - position

If you don't want to inherit any properties, but you want your object to be tested before it's super-class you can use the depends keyword. This way it will not inherit it's properties.

init - Constructor

It is important to note that jbb does not instantiate the objects in a single call, rather it separates this process in two distinct phases:

1. At first, JBB will create an instance of the object, without knowing any of it's serialized properties.
2. When the properties are known, an initialization function will be called.

The init property can be configured according to your needs. Depending on each object's particularities, one of the following options can be used:

The following example illustrates the previous values:

# This will do:
#
#   inst = new THREE.Vector3()
#   inst.x = values[0]
#   inst.y = values[1]
#   inst.z = values[2]
#
THREE.Vector3:
    init: default
    properties:
        - x
        - y
        - z

# This will do:
#
#   inst = new THREE.Object3D()
#   inst.name = values[0]
#   inst.position.copy( values[1] )
#   inst.color.set( values[2], values[3], values[4] )
#
THREE.Object3D:
    init:
        position: $inst.position.copy( $value )
        color: $inst.color.set( $$red, $$green, $$blue )
    properties:
        - name
        - position
        - red
        - green
        - blue

# This will do:
#
#   inst = Object.create(THREE.Vector3.prototype)
#   THREE.Vector3.call( inst, values[0], 
#                             values[1], 
#                             values[2] )
THREE.Vector3:
    init: [x,y,z]
    properties:
        - x
        - y
        - z

# Demonstrating the note on second case,
# the extra properties will be defined afterwards:
#
#   inst = Object.create(THREE.Vector3.prototype)
#   THREE.Vector3.call( inst, values[0], 
#                             values[1], 
#                             values[2] )
#   inst.more1 = values[3];
#   inst.more2 = values[4];
#
THREE.Vector3:
    init: [x,y,z]
    properties:
        - x
        - y
        - z
        - more1
        - more2

# This will do:
#
#   inst = Object.create(THREE.Vector3.prototype)
#   user_function( inst, values )
#
THREE.Vector3:
    init: user_function
    properties:
        - x
        - y
        - z

frequent - Frequently Encountered Flag

This flag should be set to true if this object is frequently encountered. Such objects are encoded in a more optimised way.

NOTE: The optimisation works only for the first 32 objects, so carefully chose your frequent objects.

postInit - Post-init Script

This property contains a script that will be executed right after the object is constructed in order to initialise the instance. Script macros are available, refer to the Script Macros section below for more details.

For example:

THREE.Mesh:
    extends: THREE.Object3D
    postInit: |
        $inst.updateMorphTargets();
    properties:
        - geometry
        - material
        - materialTexture
        - materialWireframe

embed - Embed resources

This is an array of property names, that are string and pointing to URLs. The resources pointed by the URLs will be downloaded at compile time and embedded as a binary blob in the bundle. At decoding time, a blob URL will be used in place of the actual URL.

For example:

# This will download the file pointed by 
# the 'url' property and store it in the bundle.
AudioFile:
    properties:
        - url
        - volume
        - pan
    embed:
        - url

Script Macros

The following macros can be used when writing in-line javascript snippets (ex. postInit or init customisations):