gulp-jbb-profile v1.0.3
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:
- At first, JBB will create an instance of the object, without knowing any of it's serialized properties.
- 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):