turbulenz/turbulenz_engine

================ Turbulenz Engine

Turbulenz is an HTML5 game engine and server-side APIs available in JavaScript and TypeScript for building and distributing 2D and 3D games that run on platforms that support HTML5 features such as modern browsers without the need for plugins.

.. contents:: :local:

Examples using the Turbulenz Engine

Games

• Polycraft <https://turbulenz.com/games/polycraft>__ - 3D
• Save the day <https://turbulenz.com/games/save-the-day>__ - 2D
• Denki Blocks! <https://turbulenz.com/games/denkiblocks>__ - 2D
• Denki Word Quest <https://turbulenz.com/games/denkiwordquest>__ - 2D
• Score Rush <https://turbulenz.com/games/scorerush>__ - 2D
• Score Rush MP <https://turbulenz.com/games/scorerush-mp>__ - multiplayer
• Space Ark <https://turbulenz.com/games/space-ark>__ - 3D
• Apathy <http://apathy.plankhead.com/>__ - src <https://github.com/Zacqary/Apathy>__ - 2D
• Salty Dogs - src <https://github.com/zacqary/salty-dogs>__
• Gargantia Sky Courier <http://fly.gargantia.jp>__ - src <https://github.com/turbulenz/gargantia_editor>__ - 3D

Apps

• Sample app - src <apps/sampleapp/scripts/sampleappmain.js>__
• Touch, keyboard, mouse and pad controller input app - src <apps/inputapp/tsscripts/inputapp>__
• Viewer - src <apps/viewer/scripts/viewer.js>__
• Realtime multiplayer worm app - src <apps/multiworm/tsscripts/worm>__
• Asynchronous turn based multiplayer tic-tac-toe app - src <apps/tictactoe/tsscripts/tictactoe>__

Prototyping

• Prototyping basic app - jsfiddle <http://jsfiddle.net/jamesaustin/WF47C/>__
• Prototyping sample app - src <apps/protolibsampleapp/scripts/protolibsampleapp.js>__
• Prototyping template app - src <apps/protolibtemplateapp/scripts/app.js>__

Samples

• Setup:

  • Device Initialization <http://biz.turbulenz.com/sample_assets/device_initialization.canvas.release.html>__ - src <samples/tsscripts/templates/device_initialization.ts>__
  • Basic Loop <http://biz.turbulenz.com/sample_assets/basic_loop.canvas.release.html>__ - src <samples/tsscripts/templates/basic_loop.ts>__

• 2D Rendering:

  • 2D Canvas <http://biz.turbulenz.com/sample_assets/2dcanvas.canvas.release.html>__ - src <samples/tsscripts/templates/2dcanvas.ts>__ - jsfiddle <http://jsfiddle.net/jamesaustin/HRAw7/>__
  • Draw2D <http://biz.turbulenz.com/sample_assets/draw2d.canvas.release.html>__ - src <samples/tsscripts/templates/draw2d.ts>__
  • TextureEffects <http://biz.turbulenz.com/sample_assets/textureeffects.canvas.release.html>__ - src <samples/tsscripts/templates/textureeffects.ts>__
  • Immediate Mode Rendering <http://biz.turbulenz.com/sample_assets/immediate_mode_rendering.canvas.release.html>__ - src <samples/tsscripts/templates/immediate_mode_rendering.ts>__
  • Loading - src <samples/tsscripts/templates/loading.ts>__
  • SVG - src <samples/tsscripts/templates/svg.ts>__

• 3D Rendering:

  • Camera <http://biz.turbulenz.com/sample_assets/camera.canvas.release.html>__ - src <samples/tsscripts/templates/camera.ts>__
  • Material <http://biz.turbulenz.com/sample_assets/material.canvas.release.html>__ - src <samples/tsscripts/templates/material.ts>__
  • Forward rendering <http://biz.turbulenz.com/sample_assets/forward_rendering.canvas.release.html>__ - src <samples/tsscripts/templates/forward_rendering.ts>__
  • Morphing <http://biz.turbulenz.com/sample_assets/morphing.canvas.release.html>__ - src <samples/tsscripts/templates/morphing.ts>__
  • Post effects <http://biz.turbulenz.com/sample_assets/postfx.canvas.release.html>__ - src <samples/tsscripts/templates/postfx.ts>__
  • Particles <http://biz.turbulenz.com/sample_assets/particles.canvas.release.html>__ - src <samples/tsscripts/templates/particles.ts>__
  • Deferred Rendering - src <samples/tsscripts/templates/deferred_rendering.ts>__
  • Load model - src <samples/tsscripts/templates/load_model.ts>__
  • Scene loading - src <samples/tsscripts/templates/scene_loading.ts>__

• Animation:

  • Animation <http://biz.turbulenz.com/sample_assets/animation.canvas.release.html>__ - src <samples/tsscripts/templates/animation.ts>__
  • Multiple animations <http://biz.turbulenz.com/sample_assets/multiple_animations.canvas.release.html>__ - src <samples/tsscripts/templates/multiple_animations.ts>__

• 2D Physics:

  • 2D Physics <http://biz.turbulenz.com/sample_assets/physics2d.canvas.release.html>__ - src <samples/tsscripts/templates/physics2d.ts>__
  • 2D Physics constraints <http://biz.turbulenz.com/sample_assets/physics2d_constraints.canvas.release.html>__ - src <samples/tsscripts/templates/physics2d_constraints.ts>__
  • 2D Physics callbacks <http://biz.turbulenz.com/sample_assets/physics2d_callbacks.canvas.release.html>__ - src <samples/tsscripts/templates/physics2d_callbacks.ts>__

• 3D Physics:

  • 3D Physics <http://biz.turbulenz.com/sample_assets/physics.canvas.release.html>__ - src <samples/tsscripts/templates/physics.ts>__
  • 3D Physics <benchmark(http://biz.turbulenz.com/sample_assets/physics_benchmark.canvas.release.html>__ - src <samples/tsscripts/templates/physics_benchmark.ts>__
  • 3D Physics collision mesh <http://biz.turbulenz.com/sample_assets/physics_collisionmesh.canvas.release.html>__ - src <samples/tsscripts/templates/physics_collisionmesh.ts>__
  • 3D Physics constraints - src <samples/tsscripts/templates/physics_constraints.ts>__

• Sound:

  • Sound <http://biz.turbulenz.com/sample_assets/sound.canvas.release.html>__ - src <samples/tsscripts/templates/sound.ts>__

• Video:

  • Video playback <http://biz.turbulenz.com/sample_assets/video.canvas.release.html>__ - src <samples/tsscripts/templates/video.ts>__

• Services:

  • Leaderboards - src <samples/tsscripts/templates/leaderboards.ts>__
  • Multichat - src <samples/tsscripts/templates/multichat.ts>__
  • Payments - src <samples/tsscripts/templates/payments.ts>__
  • Userdata - src <samples/tsscripts/templates/userdata.ts>__

Features

Low-level API

Graphics

• Simple shader-based immediate mode API:

  • A Shader may contain multiple Techniques, either single or multi-pass.
  • Once a shader Technique is set on the Device, the parameters required by the program code can be updated by a TechniqueParameter object:
  • TechniqueParameter objects hold multiple references to Textures, TechniqueParameterBuffers or individual values.
  • Multiple TechniqueParameters can be set on the Device at once.

• Vertex buffers, Index buffers and Textures can be created, updated and destroyed dynamically.

• Multiple Streams of Vertex buffers can be used at the same time.

• Support for 1D, 2D, 3D and Cube textures: Any pixel format supported by the hardware.

• Asynchronous resource loading: multiple resource files can be downloaded on the fly, JavaScript code will be notified when resource is available for usage.

• Multiple image file formats: DDS, JPG, PNG and TGA.

• Support for textures archives containing multiple image files: less flexibility than individual files but better for optimal bandwidth usage.

• Occlusion queries:

  • Number of pixels rendered can be queried for a section of rendering.
  • Available in plugin mode only.

• Fullscreen support (Supported platforms).

• Take screenshot feature:

• Video playback support:

  • WebM, MP4.
  • Render video as texture.
  • Playback controls play, pause, stop, resume, rewind.

Math

• Math types:

  • Vector2 Vector3, Vector4
  • Matrix33, Matrix34, Matrix43, Matrix44
  • Quaternion, QuatPos
  • AABB

• Storage format optimized based on available support

• Optimized operations support destination parameters, reducing object allocation.

• Array to/from Math type conversion utilities.

Physics

3D

• Easy-to-use efficient physics simulation.

  • Optimized JavaScript implementation.
  • In plugin mode, this is a lightweight wrapper around the Bullet Physics Library http://bulletphysics.org/wordpress/

• Rigid bodies and collision objects: Plane, Box, Sphere, Capsule, Cylinder, Cone, Triangle Mesh, Convex Hull.

• Constraints: Point to Point, Hinge, Cone Twist, 6DOF, Slider.

• Ray and convex sweep queries: Returning closest point of impact and surface normal.

• Character representation.

  • For use with 1st/3rd person games.
  • Includes properties for velocity, position, crouch, jump height, death, on ground.

• Contact callbacks.

  • Rigidbodies, characters, collision objects.
  • Called on presolve, added, processed, removed.
  • Filter responses by mask.
  • Triggers with no collision response.

2D

• Efficient 2D physics simulation written specifically for JavaScript.

• Shapes:

  • Circle, Box, Rectangle, Regular Polygon, Custom Polygon.
  • Create shapes as sensors.
  • Shape grouping and mask interactions.

• Collision detection:

  • Sweep & Prune, Box Tree Broadphases.
  • Utilities for Raytest, Signed Distance, Intersection, Contains Point, Sweep Test.

• Simulation world:

  • Multiple simulation groups.
  • Optional gravity.
  • Customisable simulation iterations.

• Rigid body simulation: Dynamic, Static, Kinematic objects.

• Materials: Elasticity, Static/Dynamic/Rolling Friction, Density.

• Arbiters:

  • Contact grouping.
  • Contact information: Position, Penetration, Normal/Tangent Impulse

• Constraints: Point to Point, Distance, Weld, Angle, Motor, Line, Pulley, Custom Constraint.

• Debug rendering:

  • Rigid Bodies, Constraints, Worlds, Lines, Curves, Rectangles, Circles, Spirals, Linear/Spiral Springs.
  • Enabling and disabling of rendering types.
  • Scaling for Draw2D viewport.

Sound

• Easy-to-use efficient wrapper of hardware audio features: Utilizes Web Audio, tag, OpenAL <http://connect.creativelabs.com/openal/default.aspx>__ dependent on platform support.
• 3D sound sources: Position, Direction, Velocity, Gain, Pitch, Loop.
• Emulated 3D sound for stereo setups.
• Asynchronous sound files loading: Multiple resource files can be downloaded on the fly, JavaScript code will be notified when resource is available for usage.
• Uncompress audio dynamically.
• Multiple sound file formats: OGG, WAV, MP3.
• Supported query for platform capabilities: Load the best audio format for the platform.
• Effect/Filter support: Reverb, Echo, Low Pass

Networking

• Bi-directional, full-duplex communications channels, over a TCP socket:

  • Utilizes browser Websocket support.

  • Efficient native implementation of WebSockets for platforms without support:

    • http://en.wikipedia.org/wiki/WebSocket
    • http://dev.w3.org/html5/websockets/

• HTTP-compatible handshake so that HTTP servers can share their default HTTP and HTTPS ports (80 and 443) with a WebSocket server.

• Support for secure connections as part of the standard.

• Support for data compression with the extension deflate-frame.

Input

• Access to input types: Keyboard, Mouse, Xbox360 Pad, Joysticks, Wheels, Touch, Multi-touch

• Asynchronous event system when state changes:

  • JavaScript code is notified when input changes.
  • Events for keydown, keyup, mousedown, mouseup, mousewheel, mousemove, mouseover, mouseenter, mouseleave, paddown, padup, focus, blur, mouselocklost, touchstart, touchend, touchmove, touchmove, touchenter, touchleave, touchcancel.

• Additional mouse features: hiding/showing platform icon, locking/unlocking (supported platforms).

• Language independent keymapping.

High-level API

Scene Graph

• Flexible JSON file format: Could describe either a whole scene or individual meshes.

• Asynchronous loading of external references:

  • If a scene contains references to external meshes they are all loaded in parallel and attached to the main scene when ready.
  • Support for optimal reuse of same mesh on different locations.

• Pluggable renderer system:

  • Links between geometries, effects and materials are resolved at runtime.
  • Easy swap of multiple rendering techniques for same assets.

• Geometry sharing: Geometry information can be optimally reused on multiple scene locations with different rendering effects.

• Flexible scene hierarchy nodes: Lights, Geometries, Animation, Physics.

• Visibility queries: Portals, Frustum, Overlapping Box.

• Sorting and grouping: Visible nodes are sorted and grouped for optimal rendering: Opaque, Transparent, Decal.

• Lazy evaluation of node updates.

Animation

• 3D animation for scene geometry.

• Skeleton/Skinning animation.

• Animation controllers:

  • Interpolation, Overloaded Node, Reference, Transition, Blend, Mask, Pose, Skin, GPU Skin, Skinned Node.
  • Controllers can be combined for desired effect.

• Dynamically update scene data.

Resource Manager

• Asynchronous loading avoiding duplicates: Additional remapping layer for easy URL redirection.
• Provide default resources if missing: Game can provide custom default resource to be used when a required one is missing or still loading.
• Multiple managers for individual needs: Animations, Effects, Fonts, Shaders, Sounds, Textures.
• Bandwidth and hardware scaling by selecting different assets and effects depending on machine and Internet connection performance.
• Client-side asset cache for optimizing and reusing requests.

Server Requests

• HTTP & AJAX request functionality:

  • Automatic retry and error handling.
  • Cross-browser support.
  • Encrypted API support.

Deferred Renderer

• Unlimited number of lights: Point, Spot, Directional, Ambient.

• Texture based light falloff: Allows multi-colored lights and cheap fake shadows, for example the typical fan under a light source.

• Materials with multiple texture maps: Specular color and intensity, Normal vector, Glow color, Alpha.

• Pluggable post effects:

  • Easy set-up for full screen post effects as part of the final deferred shading.
  • Copy, Fade in, Modulate, Bicolor, Blend.

• Exponential shadow maps:

  • Reuse of texture shadow maps to save video memory.
  • Gaussian blur for smooth results.
  • Exponential depth information to avoid light bleeding.

• Volumetric fog.

• 4 weight GPU skinning.

• UV animation.

• Wireframe mode.

• Callbacks for additional passes: decals, transparency, debug

• Available in plugin mode only until draw buffers are added to WebGL http://www.khronos.org/registry/webgl/extensions/WEBGL_draw_buffers/

Forward Renderer

• Unlimited number of lights: Point, Spot, Directional, Ambient.

• Texture based light falloff: Allows multi-colored lights and cheap fake shadows, for example the typical fan under a light source.

• Materials with multiple texture maps: Specular color and intensity, Normal vector, Glow color, Alpha.

• Pluggable post effects:

  • Easy set-up for full screen post effects as part of the final deferred shading.
  • Copy, Fade in, Modulate, Bicolor, Blend.

• Exponential shadow maps:

  • Reuse of texture shadow maps to save video memory.
  • Gaussian blur for smooth results.
  • Exponential depth information to avoid light bleeding.

• 4 weight GPU skinning.

• UV animation.

• Wireframe mode.

• Callbacks for additional passes: decals, transparency, debug

Default Renderer

• Single point and ambient light.
• Pixel-based lighting.
• Materials with multiple texture maps: Specular color and intensity, Normal vector, Glow color, Alpha.
• Optimzed for speed and compatibility on a wide range of hardware.
• 4 weight GPU skinning.
• UV animation.
• Wireframe mode.
• Callbacks for additional passes: decals, transparency, debug

Simple Renderer

• Single point and ambient light.
• Vertex-based lighting.
• Materials with multiple texture maps: Specular color and intensity, Normal vector, Glow color, Alpha.
• Optimzed for speed and compatibility on a wide range of hardware.
• 4 weight GPU skinning.
• UV animation.
• Wireframe mode.
• Callbacks for additional passes: decals, transparency, debug

2D Rendering

Draw2D

• 2D sprite-based renderer: Batches sprites for efficiency.

• Draw modes:

  • Draw: Draw object literal,
  • DrawRaw: Draw buffer data,
  • DrawSprite: Draw sprite reference.

• Scalable viewport: Input coordinate mapping.

• Sort modes: Immediate, Deferred, Texture.

• Blend modes: Opaque, Additive, Alpha.

• Custom shader support.

• Render-to-target support.

• Texture effects: Distort, Gaussian Blur, Bloom, Color, Grey Scale, Sepia, Negative, Saturation, Hue, Brightness, Contrast.

• Recording performance data.

Canvas2D

• Accelerated implementation of canvas 2D API <http://www.w3.org/html/wg/drafts/2dcontext/html5_canvas/>__.
• Runs on WebGL/OpenGL depending on platform.
• SVG rendering.
• Text rendering via FontManager.
• For complete implementation see canvas element specification <http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#the-canvas-element>__

Utilities

• Allocation and management of graphics buffers: Vertex buffers, Index buffers.

• API controlled JavaScript profiling:

  • Per-function millisecond accuracy timing.
  • Record top-down or bottom-up function trees.
  • Calculate the time spent by an individual function or the total spent by sub-functions.
  • Identify the source file and line number of problematic areas.

• Memory usage identification:

  • Retrieve the object count of constructed object types.
  • Take snapshots and compare memory fluctuations.

• Encryption and decryption of server-side requests for TZO formats.

• Debug utility with function stripping for performance:

  • assert, log, abort.
  • Complete stacktrace.
  • Supports adding custom functions.

• Network Simulator:

  • Simulates latency and network behaviour.
  • Client-side manipulation of multiplayer session messages.
  • Simulates spikes in network traffic.

Turbulenz Service API

Leaderboards

• Submitting/retrieving ranked friend/global leaderboards.
• Sort by either higher or lower scores.
• Infinitely scrollable scoreboards.
• Friend's score notifications.
• Aggregate scores.
• Default score entries.

Badges

• Achievement system for awarding game progress.
• Custom badge shape and design
• Progression badges.
• Achievement notification.

Payments

• Payments API: In game, On website, App stores.
• Payment methods: Single purchase, Micro transactions.
• Purchasable items: Ownable, Consumeable.

Userdata

• Per-user save game information.
• Key-value pair data storage: Settings, Preferences, Personal items.

Userprofile

• Game player's profile information: Username, Display name, Language, Age, Country, Guest user.

Gameprofile

• Game status of a player:

  • Viewable by other players a game.
  • Custom field information decided by game.

Multiplayer

• Real-time session match-making between friends and public users.
• Session creation/joining.
• Multiplayer session invite and notification.

Datashares

• Shared key-value store for turn based games and user generated content.
• Read only and read and write access.
• Find other users public shares or filter by username.

Notifications

• Send delayed notifications to the current user.
• Send instant notifications to other users.
• Notification types: Email, website pop-up and in-game.

Metrics

• Custom event submission:

  • Can be used to gather progress during game.
  • Exportable from developer services.
  • Events identifiable by custom key.
  • Allows additional numerical data.

Bridge

• Bi-directional communication channel between game and webpage.
• Allows messages to be exchanged.
• Live updating: Badge progress, notifications, loading/saving status.

Utilities

• Mapping between game resources references and content distribution network.
• Uniquely identifiable gamesession.
• Service availability notification.

What Are the Design Goals of the Turbulenz Engine

The main design goals of the Turbulenz Engine are performance, modularity and customizability. Users of the engine should be able to build any kind of game without limitations, in an efficient manner and with an end product that performs optimally when loading and during play.

To achieve this target the Turbulenz team followed these rules when writing code:

Modularity

• Users should be able to pick what they want and replace what they don't.
• When possible new functionality should be orthogonal to existing one.

High performance

• Strict coding standards to keep code efficient.
• Keep memory allocations to minimum, reuse existing objects or arrays whenever possible, use scratch pads, combine multiple separate objects into a single one.
• Use most efficient storage for each data, Typed Arrays when possible.
• Reduce function calls when possible: write functions that handle arrays of objects instead of loops that make a function call per element, games rarely do a single thing to a single object.
• Be aware of performance differences between browsers.
• Profile often.

Asynchronous loading

• No API should block waiting for a response from the server, avoid polling whenever possible, use callbacks or Promises, to notify of data availability.

Data driven

• The target should be to make the game a simple dumb player of data, all functionality defined by simple data files.

Simple well documented file formats

• Define simple, easy to create asset formats that can trivially be connected to any tool chain.

Scalability

• Design interfaces that can be implemented with different level of detail or quality settings in order to scale from mobile to desktops.

Power without control is nothing

• Make sure users can do exactly what they want, with a helper layer put on top if required, document performance implications at every level.

Fault tolerant

• The engine should keep going even if any type of asset fails to load. The application is able to provide sensible defaults for all asset types making it easier to stay productive and diagnose issues.

Fast loading

• Reduce amount of data to be downloaded, compress data efficiently.
• Use the browser cache efficiently, use unique file names based on content and tell the browser to cache forever.

Maintainability

• Strict coding standards to keep code readable, easy to maintain and debug.
• Write unit tests, samples and documentation for every new code path.

Targeted

• This is a game engine, for games.

History

The Engine was created and is maintained by Turbulenz Limited <http://biz.turbulenz.com>__ and was open sourced in April 2013.

The latest release is 1.3.2 which is tagged in the repository or a tarball/zip can be can be downloaded from here <https://github.com/turbulenz/turbulenz_engine/archive/release_1.3.2.tar.gz>__

A full history of changes can be found in the Changelog <docs/source/changelog.rst>__

Pre-Requisites

The pre-requisites for the open source version of the Turbulenz Engine allowing you to use the various commands are

• Python 2.7.x.

  • For Windows we recommend a 32bit install of Python.

  • If you have multiple Python versions installed e.g. 3.x you may need to run commands with python2.7

  • On Windows if you didn't add Python to your path in the installer you may need to run C:\Python27\python.exe You can check your version with ::

    $ python --version
    Python 2.7.3
    

• VirtualEnv - version 1.9.1 or higher recommended You can check your version with ::

    $ virtualenv --version
    1.9.1
  

• UglifyJS, turbulenz_build, DefinitelyTyped and NvTriStrip which are included via Git submodules contained within the Turbulenz Engine repository.

• Additional Python packages which will be automatically installed during the initial environment creation using a Python package manager.

Pre-requisites for building the tools cgfx2json and NvTriStrip via python manage.py tools

• Compiler Toolchain

  • Windows : Any one of

    • Microsoft Visual Studio 2008 with SP1
    • Microsoft Visual Studio 2010
    • Visual C++ 2010 Express
    • Microsoft Visual Studio 2012 with update 2
    • Microsoft Visual Studio Express 2012 for Windows Desktop with update 2

  • Mac OSX : Xcode with the command line tools

  • Linux : GCC 4.6.x or higher

• NVIDIA CgToolkit <https://developer.nvidia.com/cg-toolkit>__ version 3.1 or higher. The repository includes the binaries for Windows, if you're developing on Mac OSX or Linux please download and install it.

• OpenGL development libraries, these are included on Windows and Mac OSX with the compiler toolchains. For debian based linux distributions the libgl1-mesa-dev package will provide the required files (e.g. sudo apt-get install libgl1-mesa-dev), for other linux distributions find the package supplying GL/gl.h and libGL.so

Setup Guide

There are two ways to get up and running with the Turbulenz Engine, you can downloaded a packaged fully QA'd snapshot release from the Turbulenz Hub <https://hub.turbulenz.com>. These installers are available for Windows, Mac OSX and Linux and will install all the required packages and dependencies to get started, a full guide can be found at <http://docs.turbulenz.com/installing.html>

Note: SDK versions prior to 0.26.0 were released under a non open source license.

If you want to run with the latest version or would like to contribute to the open source project the steps for getting setup are included below. Use of the open source repository is tested against Windows, Mac OSX and Linux but may also work on other unix-like operating systems.

Setup

1. Clone the repository <http://github.com/turbulenz/turbulenz_engine>__ (or if you wish you can fork the repository on GitHub and clone that). To clone the repository maintained by Turbulenz use ::

    $ git clone git://github.com/turbulenz/turbulenz_engine.git
   

2. The Turbulenz Engine submodules the following technology in the external folder

   • tzbuild: https://github.com/turbulenz/turbulenz_build
   • DefinitelyTyped: https://github.com/borisyankov/DefinitelyTyped
   • UglifyJS: https://github.com/mishoo/UglifyJS.git

   Initialize the Git submodules with ::

    $ git submodule update --init
   

3. Check you have the pre-requisites_ installed

4. From the cloned repository create a VirtualEnv environment to install the required Python packages and NodeJS, allowing you to use all the features of the Turbulenz Engine. Note if Python is not on your shell's path you will need to specify the full path for this first command. ::

    $ python manage.py env
   

5. Activate the environment in your shell. ::

    $ source env/bin/activate - for bash and similar shells
    > env\scripts\activate.bat - for Windows
   

6. If you want to move onto the API tutorial section next then your final command is to build the JavaScript sources from the TypeScript sources. The next section will detail some of the additional actions you can perform or you can move onto Getting Started With The API_ ::

    $ python manage.py jslib
   

Working With The Open Source Project

The manage.py script at the top level of the repository provides a set of commands for managing the Engine, the script should be run as python manage.py command on Windows but can usually be shortcut to ./manage.py command on unix shells. Running the script with --help will give a list of commands available, most of these are described below. All the commands other than the env command expect to have the VirtualEnv environment activated as described in the setup section.

• JavaScript Sources - The Turbulenz Engine source is written in TypeScript. To generate the JavaScript version of the engine source run the command ::

  $ python manage.py jslib

• Tools - The Turbulenz Engine includes a number of Python tools which are installed during the env command. In addition the Engine includes a CGFX shader conversion tool which can be built with the following command. See the pre-requisites_ section for details of required compiler toolchains. ::

  $ python manage.py tools

• Documentation - The Turbulenz Engine documentation is based on restructured text sources. To build the html documentation run the command ::

  $ python manage.py docs

• Samples - Various samples are included with the Turbulenz Engine. These can be built from their TypeScript sources with the command below. This generates a set of html files, JavaScript and asset JSON files which can be served with a web server such as the Turbulenz Local Development Server. ::

  $ python manage.py samples

• Applications - The Turbulenz Engine project includes a few larger applications and some templates for building your own application. These can be found in the apps folder, and can be built with the command ::

  $ python manage.py apps

  You can also build individual apps by specifying their name e.g. ::

  $ python manage.py apps multiworm

• Command Line Tools - Various command line tools for processing code and assets are installed as part of the virtual environment. These are available at the command line e.g. running dae2json will execute the dae2json tool used to convert Collada assets to a Turbulenz Engine JSON asset format. See the tools <http://docs.turbulenz.com/tools/index.html>__ section in the documentation for more details on the tools.

• Local Development Server - Setting up the environment also includes a locally hosted web server which can be used for development of HTML5 games and applications. See the Local Server <https://github.com/turbulenz/turbulenz_local>__ repository for more details.

Getting Started With The API

To try the Turbulenz APIs requires only a text editor and a browser such as Google Chrome or Mozilla Firefox. Create an HTML file with the following content and place it in the root of the Turbulenz directory::

<html>
<head>
    <title>Turbulenz - API - Clear Screen Example</title>
    <script src="jslib/debug.js"></script>
    <script src="jslib/webgl/turbulenzengine.js"></script>
    <script src="jslib/webgl/graphicsdevice.js"></script>
</head>
<body>
    <canvas id="canvas" width="640px" height="480px"/>
    <script>
        TurbulenzEngine = WebGLTurbulenzEngine.create({
            canvas: document.getElementById("canvas")
        });
        var graphicsDevice = TurbulenzEngine.createGraphicsDevice({});

        var bgColor = [1.0, 1.0, 0.0, 1.0];

        function update() {
            if (graphicsDevice.beginFrame()) {
                graphicsDevice.clear(bgColor, 1.0);
                graphicsDevice.endFrame();
            }
        }

        TurbulenzEngine.setInterval(update, 1000 / 60);
    </script>
</body>
</html>

After defining a element of 640x480 pixels, this code will create the TurbulenzEngine and request the GraphicDevice module. Using an update function called at a frequency of 60fps, the GraphicsDevice will clear the screen yellow. To run the example, open the HTML file in your browser. You should see a yellow rectangle.

To use assets such as images you will need to host a HTML file and assets on a webserver. Any webserver will work, a quick way to try is to activate the Turbulenz environment in the root of the Turbulenz directory and run::

python -m SimpleHTTPServer

This command will host the contents of the Turbulenz directory on your machine as a webserver.

To demonstrate loading an asset you can try loading an image file and drawing it as a textured sprite using the Draw2D API. Create another HTML file with the following content and also place it in the root of the Turbulenz directory::

<html>
<head>
    <title>Turbulenz - API - Textured Sprite Example</title>
    <script src="jslib/debug.js"></script>
    <script src="jslib/webgl/turbulenzengine.js"></script>
    <script src="jslib/webgl/graphicsdevice.js"></script>
    <script src="jslib/draw2d.js"></script>
</head>
<body>
    <canvas id="canvas" width="640px" height="480px"/>
    <script>
        TurbulenzEngine = WebGLTurbulenzEngine.create({
            canvas: document.getElementById("canvas")
        });
        var graphicsDevice = TurbulenzEngine.createGraphicsDevice({});
        var draw2D = Draw2D.create({
            graphicsDevice: graphicsDevice
        });

        var bgColor = [1.0, 1.0, 0.0, 1.0];

        var sprite = Draw2DSprite.create({
            width: 100,
            height: 100,
            x: graphicsDevice.width / 2,
            y: graphicsDevice.height / 2,
            color: [1.0, 1.0, 1.0, 1.0],
            rotation: Math.PI / 4
        });

        var texture = graphicsDevice.createTexture({
            src: "assets/textures/crate.jpg",
            mipmaps: true,
            onload: function (texture)
            {
                if (texture)
                {
                    sprite.setTexture(texture);
                    sprite.setTextureRectangle([0, 0, texture.width, texture.height]);
                }
            }
        });

        var PI2 = Math.PI * 2;
        var rotateAngle = PI2 / 360; // 1 deg per frame

        function update() {

            sprite.rotation += rotateAngle;
            sprite.rotation %= PI2; // Wrap rotation at PI * 2

            if (graphicsDevice.beginFrame()) {
                graphicsDevice.clear(bgColor, 1.0);

                draw2D.begin();
                draw2D.drawSprite(sprite);
                draw2D.end();

                graphicsDevice.endFrame();
            }
        }

        TurbulenzEngine.setInterval(update, 1000 / 60);
    </script>
</body>
</html>

This time, instead of opening the file in the browser, navigate your browser to http://127.0.0.1:8000 or http://localhost:8000 and select the HTML file you created. You should see a spinning textured box in the middle of a yellow rectangle.

The next step is render a simple textured mesh in 3D. To do this you will need to build some assets from their source files. Make sure you have run the tools command to build the tools for your platform::

$ python manage.py tools

Note: The requirements for building the tools is different per platform. See the Pre-Requisites_ section.

For this example you should use the Protolib <http://docs.turbulenz.com/protolib/protolib_api.html>__ library, which is ideal for prototyping games using Turbulenz. You will need these assets::

- models/duck.dae
- textures/duck.png
- textures/default_light.png
- shaders/shadowmapping.cgfx
- shaders/zonly.cgfx
- shaders/forwardrendering.cgfx
- shaders/forwardrenderingshadows.cgfx
- shaders/debug.cgfx
- shaders/font.cgfx
- shaders/simplesprite.cgfx
- fonts/opensans-8.fnt
- fonts/opensans-16.fnt
- fonts/opensans-32.fnt
- fonts/opensans-64.fnt
- fonts/opensans-128.fnt
- 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

Copy this text into a file called "deps.yaml" and place it in the root of the Turbulenz directory. Having built the tools you can now run this command with the Turbulenz environment activated::

$ python scripts/buildassets.py --root . --assets-path assets

This will build the assets listed in the deps.yaml and output a "staticmax" directory and "mapping_table.json" file containing the processed assets and a mapping to them for the webserver. When a library tries to request one of these files, it will be able to find it in the staticmax directory. Now you can create the mesh example HTML file and place it at the root of the Turbulenz directory::

<html>
<head>
    <title>Turbulenz - API - Textured Mesh Example</title>
    <script>
        var TurbulenzEngine = {};
    </script>
    <script src="jslib/debug.js"></script>
    <script src="jslib/vmath.js"></script>
    <script src="jslib/webgl/turbulenzengine.js"></script>
    <script src="jslib/webgl/graphicsdevice.js"></script>
    <script src="jslib/webgl/inputdevice.js"></script>
    <script src="jslib/webgl/sounddevice.js"></script>
    <script src="jslib/webgl/mathdevice.js"></script>

    <script src="jslib/aabbtree.js"></script>
    <script src="jslib/assettracker.js"></script>
    <script src="jslib/camera.js"></script>
    <script src="jslib/draw2d.js"></script>
    <script src="jslib/effectmanager.js"></script>
    <script src="jslib/fontmanager.js"></script>
    <script src="jslib/forwardrendering.js"></script>
    <script src="jslib/geometry.js"></script>
    <script src="jslib/indexbuffermanager.js"></script>
    <script src="jslib/light.js"></script>
    <script src="jslib/loadingscreen.js"></script>
    <script src="jslib/material.js"></script>
    <script src="jslib/observer.js"></script>
    <script src="jslib/renderingcommon.js"></script>
    <script src="jslib/requesthandler.js"></script>
    <script src="jslib/resourceloader.js"></script>
    <script src="jslib/scene.js"></script>
    <script src="jslib/scenenode.js"></script>
    <script src="jslib/shadermanager.js"></script>
    <script src="jslib/shadowmapping.js"></script>
    <script src="jslib/soundmanager.js"></script>
    <script src="jslib/texturemanager.js"></script>
    <script src="jslib/utilities.js"></script>
    <script src="jslib/vertexbuffermanager.js"></script>

    <script src="jslib/services/turbulenzbridge.js"></script>
    <script src="jslib/services/turbulenzservices.js"></script>
    <script src="jslib/services/gamesession.js"></script>
    <script src="jslib/services/mappingtable.js"></script>

    <script src="protolib/duimanager.js"></script>
    <script src="protolib/jqueryextend.js"></script>
    <script src="protolib/simplesprite.js"></script>
    <script src="protolib/simplefonts.js"></script>
    <script src="protolib/simplesceneloader.js"></script>
    <script src="protolib/debugdraw.js"></script>
    <script src="protolib/sceneloader.js"></script>
    <script src="protolib/soundsourcemanager.js"></script>
    <script src="protolib/protolib.js"></script>

</head>
<body>
    <canvas id="canvas" width="640px" height="480px"/>
    <script>
        TurbulenzEngine = WebGLTurbulenzEngine.create({
            canvas: document.getElementById("canvas")
        });
        var mathDevice = null;

        var mesh = null;
        var rotationMatrix = null;
        var rotationAngleMatrix = null;

        var protolib = Protolib.create({
            onInitialized: function onIntializedFn(protolib)
            {
                mathDevice = protolib.getMathDevice();
                protolib.setCameraPosition(mathDevice.v3Build(0, 1, -2));
                protolib.setCameraDirection(mathDevice.v3Build(0, 0, 1));
                protolib.setAmbientLightColor(mathDevice.v3Build(1, 1, 1));
                protolib.addPointLight({
                    v3Position: mathDevice.v3Build(-1, 1, -1),
                    v3Color: mathDevice.v3Build(1, 1, 1),
                    radius: 10
                });
                mesh = protolib.loadMesh({
                    mesh: "models/duck.dae"
                });
                rotationMatrix = mathDevice.m43BuildIdentity();
                rotationAngleMatrix = mathDevice.m43BuildIdentity();
                mathDevice.m43SetAxisRotation(rotationAngleMatrix,
                                              mathDevice.v3Build(0, 1, 0),
                                              (Math.PI * 2) / 360);
            }
        })

        function update() {

            if (protolib.beginFrame())
            {
                if (mesh)
                {
                    mesh.getRotationMatrix(rotationMatrix);
                    mathDevice.m43Mul(rotationMatrix, rotationAngleMatrix, rotationMatrix);
                    mesh.setRotationMatrix(rotationMatrix);
                }
                protolib.endFrame();
            }
        }

        TurbulenzEngine.setInterval(update, 1000 / 60);
    </script>
</body>
</html>

This file is quite similar to the previous examples, but it requires a few more Turbulenz libraries to run. This time you should see a spinning duck with a yellow texture on a white background and lit by a static point light.

For more information on how to build your own assets see the assets section <http://docs.turbulenz.com/starter/getting_started_guide.html#assets>__ in the getting started guide.

If you would like to learn more or work through this example step-by-step (with troubleshooting hints), see the Getting Started Guide <http://docs.turbulenz.com/starter/getting_started_guide.html>__ in the documentation.

For more information on the various APIs, see the following links:

• Low-level API <http://docs.turbulenz.com/jslibrary_api/low_level_api.html>, 2D Physics API <http://docs.turbulenz.com/jslibrary_api/physics2d_api.html>, 3D Physics API <http://docs.turbulenz.com/jslibrary_api/physics3d_api.html>__
• High-level API <http://docs.turbulenz.com/jslibrary_api/high_level_api.html>__
• Turbulenz Services API <http://docs.turbulenz.com/turbulenz_services/index.html>__
• Protolib API <http://docs.turbulenz.com/protolib/protolib_api.html>__

Documentation

Full documentation for the Turbulenz Engine can be found at <http://docs.turbulenz.com/index.html>__

This documentation is built from the source restructured text in the docs/source folder of the repository, the latest version online is maintained from the latest release tag in the repository. If you wish to build up to date documentation follow the setup guide and the run the manage.py docs command, this will generate html docs in the build/docs/html folder.

Known Issues

The following known issues exist with using the open source repository version of the Turbulenz Engine, additional known issues also existing in the SDK releases of the engine can be found here <http://docs.turbulenz.com/known_issues/index.html>__

• The application and JavaScript build process will currently fail if the repository is cloned to a path with spaces in it.

Licensing

The Turbulenz Engine is licensed under the MIT license <LICENSE>__

Contributing

Our contributors are listed here <docs/source/contributors.rst>__

Contributions are always encouraged whether they are small documentation tweaks, bug fixes or suggestions for larger changes. You can check the issues <http://github.com/turbulenz/turbulenz_engine/issues>__ or discussion forums <https://groups.google.com/group/turbulenz-engine-users>_ first to see if anybody else is undertaking similar changes.

If you'd like to contribute any changes simply fork the project on Github and send us a pull request or send a Git patch to the discussion forums detailing the proposed changes. If accepted we'll add you to the list of contributors.

We include a .pylintrc file in the repository which allows you to check your code conforms to our standards. Our documentation is built from restructured text sources in the docs folder so please consider how your changes may affect the documentation.

Note: by contributing code to the Turbulenz Engine project in any form, including sending a pull request via Github, a code fragment or patch via private email or public discussion groups, you agree to release your code under the terms of the MIT license that you can find in the LICENSE <LICENSE>__ file included in the source distribution.

Links

| Turbulenz game site - turbulenz.com <https://turbulenz.com>__ | Turbulenz developer service and SDK download - hub.turbulenz.com <https://hub.turbulenz.com>__ | Documentation for this module and the SDK - docs.turbulenz.com <http://docs.turbulenz.com>__ | About Turbulenz - biz.turbulenz.com <http://biz.turbulenz.com>__