Added
2013-05-02 - 0.1.0 - First BETA release (Open Source Only)
Updated
2013-05-21 - 0.1.1 - Turbulenz Webcast Build (Open Source Only)
2013-05-04 - 0.2.0 - First SDK release (SDK 0.26.0)
2014-01-29 - 0.2.1 - Behavior change to 2D text rendering sequence and addition/modification of advanced callbacks (SDK 0.28.0)
BETA
This feature is currently in beta and does not represent the final set of available APIs.
Protolib is library/framework providing simple graphics, input and sound for prototyping games. It provides a subset of the complete Turbulenz Engine features with simple interfaces for:
To use Protolib you must create an instance using:
var protolibConfig = {
onIntialized: function onInitializedFn(protolib)
{
// Protolib has loaded requirements
}
};
var protolib = Protolib.create(protolibConfig);
You can then use functions provided by Protolib to load any files and set any configuration required before rendering:
protolib.setClearColor(bgColor);
protolib.setAmbientLightColor(ambientColor);
var mesh = protolib.loadMesh({
mesh: "models/mymesh.dae",
v3Position: meshPosition
});
var pointLight = protolib.addPointLight({
v3Position: lightPos,
radius: 300,
v3Color: color
});
Some functions will provide a wrapper to the object type you created. The wrapper is your reference to the instance of the type e.g. mesh, point light, spot light, sound. When the resource is available, the library will render/play them automatically.
To update properties of the library during a frame you should make calls between the beginFrame, endFrame functions:
if (protolib.beginFrame())
{
pointLight.setPosition(newLightPosition);
protolib.draw3DLine({
pos1: startPos,
pos2: endPos,
v3Color: lineColor
});
if (protolib.isKeyDown(protolib.keyCodes.UP))
{
protolib.moveCamera(cameraUpVector);
}
protolib.drawText({
text: "Hello World!",
position: textScreenPosition
});
protolib.endFrame();
}
The state of protolib will be updated by the functions called between these functions, then any rendering required will be done at the end of the frame. Functions like draw2DSprite will efficiently batch the function calls together drawing them together.
Protolib is made up of multiple files and all these files should be included for the library to work:
| protolib: | The core protolib file. Creation, destruction and configuration. |
|---|---|
| simplesprite: | The rendering for the 3D sprites. |
| simplefonts: | The rendering for the gui text. |
| sceneloader: | The loading utility for scenes, used by simplesceneloader. |
| simplesceneloader: | |
| The module for loading and managing meshes. | |
| debugdraw: | The debug drawing utility for lines, etc. |
| soundsourcemanager: | |
| The manager for handling sound sources. | |
| jqueryextend: | A minimal subset of jquery providing the extend functionality. |
| duimanager: | The game code side component of the dynamic UI. |
To use protolib you will need to include the following library code in your template file:
/*{{ javascript('jslib/aabbtree.js') }}*/
/*{{ javascript('jslib/assettracker.js') }}*/
/*{{ javascript('jslib/camera.js') }}*/
/*{{ javascript('jslib/draw2d.js') }}*/
/*{{ javascript('jslib/effectmanager.js') }}*/
/*{{ javascript('jslib/fontmanager.js') }}*/
/*{{ javascript('jslib/forwardrendering.js') }}*/
/*{{ javascript('jslib/geometry.js') }}*/
/*{{ javascript('jslib/indexbuffermanager.js') }}*/
/*{{ javascript('jslib/light.js') }}*/
/*{{ javascript('jslib/loadingscreen.js') }}*/
/*{{ javascript('jslib/material.js') }}*/
/*{{ javascript('jslib/observer.js') }}*/
/*{{ javascript('jslib/renderingcommon.js') }}*/
/*{{ javascript('jslib/requesthandler.js') }}*/
/*{{ javascript('jslib/resourceloader.js') }}*/
/*{{ javascript('jslib/scene.js') }}*/
/*{{ javascript('jslib/scenenode.js') }}*/
/*{{ javascript('jslib/shadermanager.js') }}*/
/*{{ javascript('jslib/shadowmapping.js') }}*/
/*{{ javascript('jslib/soundmanager.js') }}*/
/*{{ javascript('jslib/texturemanager.js') }}*/
/*{{ javascript('jslib/utilities.js') }}*/
/*{{ javascript('jslib/vertexbuffermanager.js') }}*/
/*{{ javascript('jslib/vmath.js') }}*/
/*{{ javascript('jslib/services/gamesession.js') }}*/
/*{{ javascript('jslib/services/mappingtable.js') }}*/
/*{{ javascript('jslib/services/turbulenzbridge.js') }}*/
/*{{ javascript('jslib/services/turbulenzservices.js') }}*/
/*{{ javascript('protolib/debugdraw.js') }}*/
/*{{ javascript('protolib/duimanager.js') }}*/
/*{{ javascript('protolib/jqueryextend.js') }}*/
/*{{ javascript('protolib/protolib.js') }}*/
/*{{ javascript('protolib/sceneloader.js') }}*/
/*{{ javascript('protolib/simplefonts.js') }}*/
/*{{ javascript('protolib/simplesceneloader.js') }}*/
/*{{ javascript('protolib/simplesprite.js') }}*/
/*{{ javascript('protolib/soundsourcemanager.js') }}*/
And the following assets in your mapping_table.json:
- shaders/debug.cgfx
- shaders/shadowmapping.cgfx
- shaders/zonly.cgfx
- shaders/font.cgfx
- shaders/forwardrendering.cgfx
- shaders/forwardrenderingshadows.cgfx
- shaders/simplesprite.cgfx
- textures/default_light.png
- textures/opensans-8_0.png
- textures/opensans-16_0.png
- textures/opensans-32_0.png
- textures/opensans-64_0.png
- textures/opensans-128_0.png
- fonts/opensans-8.fnt
- fonts/opensans-16.fnt
- fonts/opensans-32.fnt
- fonts/opensans-64.fnt
- fonts/opensans-128.fnt
Updated 0.1.1 - Now includes jslib/assettracker.js, jslib/loadingscreen.js and shaders/simplesprite.cgfx
Added 0.2.0
Summary
Property containing the version number for the Protolib API. Specified as an 3-dimensional array of integer numbers in the following format:
[ MAJOR, MINOR, REVISION ]
This can be used to determine the expected behaviour of the API arguments.
Syntax
var version = protolib.version;
if (version[0] < 1 && version[1] < 2)
{
// Version 1.2 required
console.log("WARNING: Protolib version is incorrect");
}
Note
This property is not available version 0.1.X so to test for versions < 0.2, check if the property is undefined.
Summary
Creates a protolib object.
Syntax
var that = this;
var onInitialized = function onInitializedFn()
{
that.initGame();
TurbulenzEngine.setInterval(function()
{
that.gameLoop();
},
1000/60);
};
var config =
{
onInitialized: onInitialized,
useShadows: true,
maxSoundSources: 50,
disableSound: false,
fonts: {
regular: "opensans"
},
defaultMappingSettings: {
mappingTablePrefix: 'staticmax/',
assetPrefix: 'missing/',
mappingTableURL: 'mapping_table.json',
urnMapping: {}
},
enableDynamicUI: false
};
var protolib = Protolib.create(config);
An object containing the fonts to load for use with the drawText function in the format:
{
FONTSTYLE: "FONTNAME"
}
Protolib will attempt to load the following variations of that font: 8, 16, 32, 64, 128 pixel height. If you want to use your own font you will need to provide the following files accessible from the mapping table:
If a font is not available or is missing a required pixel height, it will default to “opensans” 16 pixels, then the default Turbulenz font. Defaults to
{
regular: "opensans"
}
An object specifying the default mapping table settings to use. If a mapping table cannot be found, Protolib will attempt to use the mapping provided by urnMapping. See createMappingTable for more details on defaultMappingSettings. Defaults to
{
mappingTablePrefix: "staticmax/",
assetPrefix: "missing/",
mappingTableURL: "mapping_table.json",
urnMapping: {}
}
Summary
Signals the beginning of a new render frame.
This can fail if the host window is not visible, e.g. the browser is minimized or the window is not on the active tab.
Syntax
if (protolib.beginFrame())
{
drawScene();
protolib.endFrame();
}
Summary
Signals the end of the current render frame.
Syntax
if (protolib.beginFrame())
{
drawScene();
protolib.endFrame();
}
Protolib creates several device objects on creation. These getter methods provide access to them.
Syntax
var cameraPosition = md.v3Build(5, 10, 15);
protolib.setCameraPosition(cameraPosition);
Syntax
var cameraPosition = md.v3Build(0, 0, 0);
protolib.getCameraPosition(v3Position);
Syntax
var cameraDirection = md.v3Build(0, 0, -1);
protolib.setCameraDirection(cameraDirection);
Syntax
var cameraDirection = md.v3Build(0, 0, -1);
protolib.setCameraDirection(cameraDirection);
Summary
Gives the current up vector of the camera.
Syntax
var cameraUp = md.v3Build(0, 0, 0);
protolib.getCameraUp(cameraUp);
Summary
Gives the current right vector of the camera.
Syntax
var cameraRight = md.v3Build(0, 0, 0);
protolib.getCameraRight(cameraRight);
Summary
Moves the camera relative to its current position.
Syntax
var translateVec = md.v3Build(5, 5, 5);
protolib.moveCamera(translateVec);
Summary
Rotates the camera relative to its current orientation.
Syntax
protolib.rotateCamera(yawDelta, pitchDelta);
Syntax
protolib.setCameraFOV(fovX, fovY);
Syntax
var cameraFov = protolib.getCameraFOV();
var fovX = cameraFov[0];
var fovY = cameraFov[1];
Returns a JavaScript array of length 2, containing the horizontal and vertical field of view angle in radians.
Summary
Sets the near and far plane distances.
Syntax
var nearPlane = 5;
var farPlane = 1000;
protolib.setNearFarPlanes(nearPlane, farPlane);
Summary
Gets the near and far plane distances.
Syntax
var nearFarPlanes = protolib.getNearFarPlanes();
var nearPlane = nearFarPlanes[0];
var farPlane = nearFarPlanes[1];
Returns a JavaScript array of length 2 with the near and far plane distances respectively.
Summary
Draws the given texture to screen space.
Note
Only power-of-two textures are supported.
Syntax
protolib.draw2DSprite({
texture: "path/to/texture.png",
position: [x, y],
width: w,
height: h,
v3Color: color,
alpha: a,
rotation: angle
});
Summary
Draws the given text to screen space.
Updated 0.2.1
drawText renderers after draw2DSprite.
Syntax
protolib.drawText({
text: "Hello World!",
position: [x, y],
v3Color: color,
scale: 2,
horizontalAlign: protolib.textHorizontalAlign.CENTER,
verticalAlign: protolib.textVerticalAlign.MIDDLE
});
Added 0.2.0
Depricated 0.2.0
Summary
Draws a 3D Sprite.
Note
Only power-of-two textures are supported.
Syntax
protolib.draw3DSprite({
texture: "path/to/texture.png",
v3Position : spritePos,
size : params.size,
alpha : 0.5,
v3Color : color,
v3Out : params.v3Out,
rotation: Math.PI/4,
blendStyle : params.blendStyle
});
Summary
Loads a 3D mesh and adds it to the scene. Returns a MeshWrapper object to control the loaded mesh.
Syntax
var treeMesh = protolib.loadMesh({
mesh: "path/to/mesh.dae",
v3Position: treePos,
v3Size: treeSize
});
Returns a MeshWrapper object to control the loaded mesh.
Summary
Draws a line between two end-points in 3d space.
Syntax
protolib.draw3DLine({
pos1: p1,
pos2: p2,
v3Color : color
});
Summary
Draws 3 circles in world space representing a sphere.
Syntax
protolib.drawDebugSphere({
v3Position: spherePos,
radius: 10,
v3Color: color
});
Summary
Draws a wireframe cube.
Syntax
protolib.drawDebugCube({
v3Position: cubePos,
length: 10,
v3Color: color
});
Summary
Sets the ambient light color.
Syntax
protolib.setAmbientLightColor(ambientColor);
Summary
Gets the current ambient light color.
Syntax
protolib.getAmbientLightColor(ambientColor);
Summary
Adds a point light to the scene. Returns a PointLightWrapper to control the light.
Syntax
var pointLight = protolib.addPointLight({
v3Position: lightPos,
radius: 300,
v3Color: color
});
Returns a PointLightWrapper to control the light.
Summary
Adds a spotlight to the scene. Returns a SpotLightWrapper to control the light.
Syntax
var spotLight = protolib.addSpotLight({
v3Position: lightPos,
v3Direction: lightDir,
range: 300,
spreadAngle: Math.PI/2,
v3Color: color
});
Returns a SpotLightWrapper to control the light.
Summary
Plays the given sound. Returns a SoundWrapper object used to control playback of the sound.
Note
For the 3D positional audio to work, a mono sound must be used.
Syntax
var sound = protolib.playSound({
sound : "path/to/sound.mp3",
volume : 2,
pitch : 1,
looping : true,
v3Position : soundPos,
minDistance : 10,
maxDistance : 300,
rollOff : 0.9
});
The ratio that the sound will drop off as by the inverse square law of the distance to the listener.
A number in the range [0, 1].
0 results in no attenuation. 1 results in the volume being determined fully by attenuation.
Defaults to 1.
A boolean indicating the sound to be played is a background sound. If set to true, the v3Position, minDistance, maxDistance and rollOff properties should not be set. Stereo sounds are supported as background sounds.
Defaults to false
var bgsound = protolib.playSound({
sound : "path/to/sound.mp3",
background : true,
volume : 2,
pitch : 1,
looping : true
});
Returns a SoundWrapper object used to control the playback of the sound.
Summary
Returns true if the given key is currently pressed.
Syntax
protolib.isKeyDown(keyCode);
Summary
Returns true if the given key was pressed between the previous and the current frame.
Syntax
protolib.isKeyJustDown(keyCode);
Summary
Returns true if the given key was released between the previous and the current frame.
Syntax
protolib.isKeyJustUp(keyCode);
Summary
Returns true if the given mouse button is currently pressed.
Syntax
var isMouseDown = protolib.isMouseDown(mouseCode);
Summary
Returns true if the given mouse button was pressed between the previous and the current frame.
Syntax
var isMouseJustDown = protolib.isMouseJustDown(mouseCode);
Summary
Returns true if the given mouse button was released between the previous and the current frame.
Syntax
var isMouseJustUp = protolib.isMouseJustUp(mouseCode);
Syntax
var isMouseOnGame = protolib.isMouseOnGame();
Returns true if the mouse is currently over the game canvas.
Syntax
var mousePos = protolib.getMousePosition();
var mouseX = mousePos[0];
var mouseY = mousePos[1];
Returns an array of length 2 giving the coordinates of the mouse.
When the mouse is locked, the mouse position is handled by getMouseDelta instead.
Syntax
var mouseDelta = protolib.getMouseDelta();
var dx = mouseDelta[0];
var dy = mouseDelta[1];
Returns an array of length 2 giving the difference in position between the previous and current frame.
Syntax
var mouseWheelDelta = protolib.getMouseWheelDelta();
Returns a number representing the number of mouse wheel scrolls made between the previous and current frame.
This is equal to inputDevice.keyCodes.
This is equal to inputDevice.mouseCodes.
Added 0.2.0
A dictionary with values used to specify horizontal text alignment, for use with the drawText function.
Values are: LEFT, CENTER, RIGHT.
Added 0.2.0
A dictionary with values used to specify vertical text alignment, for use with the drawText function.
Values are: TOP, MIDDLE, BOTTOM.
A dictionary specifying the possible blend modes, used by draw2DSprite and draw3DSprite.
Values are: ALPHA, ADDITIVE.
A dictionary specifying the possible watch types, used by addWatchVariable and removeWatchVariable.
Values are: SLIDER.
Options are:
SLIDER
{
min: number, // The minimum value of the slider.
max: number, // The maximum value of the slider.
step: number // The amount to move the slider by when dragging.
}
Allows variables to be exposed and manipulated by the hosting page. The variable uses the “Dynamic User Interface” module to expose the variable. To manipulate/view the result, the page must include the “duiserver.js” and the associated “dynamicui.css”. If these are not available, the variable will not be controllable. For an example of this functionality in use, see the apps in the SDK.
Summary
Adds a watchable variable to the page that contains the Protolib app. Note: Requires enableDynamicUI to be true as a parameter to the create function.
Syntax
var variableOwner = {
variableName: 1
};
var watchID = protolib.addWatchVariable({
title: "Variable Title",
object: variableOwner,
property: "variableName",
group: "Variable Group",
type: protolib.watchTypes.SLIDER,
options: {
min: 0.1,
max: 10,
step: 0.1
}
});
Returns a watchID for removing the watch variable later. If any of the arguments are invalid the function will return -1.
Summary
Remove a watchable variable by watchID. This removes the control from the page that contains the Protolib app.
Syntax
// watchID returned by addWatchVariable
protolib.removeWatchVariable(watchID);
Returns a true if successfully removed. Returns false if the dynamic UI is not enabled or if the ID is not recognized.
Advanced functionality of Protolib is to give developers more control of how the library works if they need to operate beyond the default behaviour. These functions should only be used by advanced users who understand the behavior and need to extend it.
Updated 0.2.1
Summary
Set a function to call, before any 3D or 2D rendering has happened in a frame, but after the scene and camera update. This function allows you to modify any state before the clear screen. This function will be called during protolib.endFrame function, proceeding the setPreRendererDraw function call. Prior to 0.2.1 this function had the behavior described in setPreRendererDraw. Use setPreRendererDraw callback to use the previous behavior.
Syntax
function preDrawFn()
{
// Manipulate scene before rendering
postUpdate.process(protolib.globals.scene);
}
protolib.setPreDraw(preDrawFn);
Added 0.2.1
Summary
Set a function to call, between the renderer clear call and before the scene rendering. This function allows you to render before the 3D scene content. This function will be called during protolib.endFrame function, after the setPreDraw function call and proceeding the setPostRendererDraw function call.
Syntax
function preRendererDrawFn()
{
// A 2D sprite to manually draw after the clear screen and behind 3D content.
draw2D.begin();
draw2D.drawSprite(sprite);
draw2D.end();
}
protolib.setPreRendererDraw(preRendererDrawFn);
Added 0.1.1
Summary
Set a function to call, after the protolib has rendered the scene content, but before 2D sprites/text and before graphicsDevice.endFrame(). This function allows you to render on top of the 3D scene content, but under the 2D content. This function will be called after 3D rendering, but before graphicsDevice.endFrame(). This function will be called during protolib.endFrame function, after the setPreRendererDraw function call and proceeding the setPostDraw function call.
Syntax
function postRendererDrawFn()
{
// Draw a layer of content post scene renderering
postScene.draw();
}
protolib.setPostRendererDraw(postRendererDrawFn);
Summary
Set a function to call, after the protolib has rendered the current frame, but before graphicsDevice.endFrame(). This function allows you to render on top of the final scene content. This function will be called after 2D and 3D rendering, but before graphicsDevice.endFrame(). This function will be called during protolib.endFrame function, after the setPostRendererDraw function call.
Syntax
function postDrawFn()
{
// Draw a layer of debug on top of the scene
debug.draw();
}
protolib.setPostDraw(postDrawFn);
An object returned from protolib.loadMesh, for controlling the loaded mesh.
var mesh = protolib.loadMesh({...});
Syntax
mesh.setPosition(v3Position);
Syntax
mesh.getPosition(v3Position);
Syntax
mesh.setSize(v3Size);
Syntax
mesh.getPosition(v3Size);
Syntax
mesh.setEnabled(enabled);
Syntax
var isMeshEnabled = mesh.getEnabled();
Returns a boolean representing whether the mesh is enabled in the scene.
Summary
Sets the rotation matrix used to orient the mesh.
Syntax
//unitY === md.v3BuildYAxis();
mathDevice.m43SetAxisRotation(rotationMatrix, unitY, Math.PI/4);
mesh.setRotationMatrix(rotationMatrix);
An object returned from protolib.playSound, used to control the playback of the played sound.
var sound = protolib.playSound({...});
Summary
Stops playing the current sound. After this is called, this wrapper object becomes invalid, and should not be used.
Syntax
sound.stop();
Summary
Returns the current status of the sound playback.
Syntax
var soundstatus = sound.getStatus();
Returns a value in protolib.soundStatus.
Syntax
sound.setVolume(volume);
Syntax
sound.getVolume(volume);
Returns the volume amplification applied to the sound.
Syntax
sound.setPosition(v3Position);
Syntax
sound.getPosition(v3Position);
Syntax
sound.setMinDistance(minDistance);
Syntax
var minDistance = sound.getMinDistance();
Returns the distance after which sound attenuation will start to take place.
Syntax
sound.setMaxDistance(maxDistance);
Syntax
var maxDistance = sound.getMaxDistance();
Returns the maxDistance for sound attenuation.
Syntax
sound.setRollOff(rollOff);
The ratio that the sound will drop off as by the inverse square law of the distance to the listener.
A number in the range [0, 1].
0 results in no attenuation. 1 results in the volume being determined fully by attenuation.
Syntax
var rollOff = sound.getRollOff();
Returns the value of the rollOff ratio.
An object returned from protolib.addPointLight, used to control the created point light.
var pointLight = protolib.addPointLight({});
Syntax
pointLight.setPosition(v3Position);
Syntax
pointLight.getPosition(v3Position);
Syntax
pointLight.setColor(v3Color);
Syntax
pointLight.getColor(v3Color);
Syntax
light.setEnabled(enabled);
Syntax
var isMeshEnabled = light.getEnabled();
Returns a boolean representing whether the light is enabled in the scene.
An object returned from protolib.addSpotLight, for controlling the created spot light.
var spotLight = protolib.addSpotLight({});
Syntax
spotLight.setPosition(v3Position);
Syntax
spotLight.getPosition(v3Position);
Syntax
spotLight.setColor(v3Color);
Syntax
spotLight.getColor(v3Color);
Syntax
light.setEnabled(enabled);
Syntax
var isMeshEnabled = light.getEnabled();
Returns a boolean representing whether the light is enabled in the scene.