Added SDK 0.26.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/camera.js') }}*/
/*{{ javascript('jslib/requesthandler.js') }}*/
/*{{ javascript('jslib/texturemanager.js') }}*/
/*{{ javascript('jslib/shadermanager.js') }}*/
/*{{ javascript('jslib/soundmanager.js') }}*/
/*{{ javascript('jslib/effectmanager.js') }}*/
/*{{ javascript('jslib/fontmanager.js') }}*/
/*{{ javascript('jslib/observer.js') }}*/
/*{{ javascript('jslib/utilities.js') }}*/
/*{{ javascript('jslib/services/turbulenzbridge.js') }}*/
/*{{ javascript('jslib/services/turbulenzservices.js') }}*/
/*{{ javascript('jslib/services/gamesession.js') }}*/
/*{{ javascript('jslib/services/mappingtable.js') }}*/
/*{{ javascript('jslib/scene.js') }}*/
/*{{ javascript('jslib/light.js') }}*/
/*{{ javascript('jslib/material.js') }}*/
/*{{ javascript('jslib/geometry.js') }}*/
/*{{ javascript('jslib/aabbtree.js') }}*/
/*{{ javascript('jslib/scenenode.js') }}*/
/*{{ javascript('jslib/vertexbuffermanager.js') }}*/
/*{{ javascript('jslib/indexbuffermanager.js') }}*/
/*{{ javascript('jslib/resourceloader.js') }}*/
/*{{ javascript('jslib/vmath.js') }}*/
/*{{ javascript('jslib/renderingcommon.js') }}*/
/*{{ javascript('jslib/forwardrendering.js') }}*/
/*{{ javascript('jslib/shadowmapping.js') }}*/
/*{{ javascript('jslib/draw2d.js') }}*/
/*{{ javascript('protolib/duimanager.js') }}*/
/*{{ javascript('protolib/jqueryextend.js') }}*/
/*{{ javascript('protolib/simplesprite.js') }}*/
/*{{ javascript('protolib/simplefonts.js') }}*/
/*{{ javascript('protolib/simplesceneloader.js') }}*/
/*{{ javascript('protolib/debugdraw.js') }}*/
/*{{ javascript('protolib/sceneloader.js') }}*/
/*{{ javascript('protolib/soundsourcemanager.js') }}*/
/*{{ javascript('protolib/protolib.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
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: {}
}
};
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.
Syntax
protolib.drawText({
text: "Hello World!",
position: [x, y],
v3Color: color,
scale: 2,
spacing: 1,
alignment: protolib.textAlignment.LEFT
});
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.
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.
A dictionary with values used to specify text alignment, for use with the drawText function.
Values are: LEFT, CENTER, RIGHT.
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.
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.
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.