Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 1081 lines (782 sloc) 44.873 kb
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
1 ================
2 Turbulenz Engine
3 ================
4
5 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.
aabcd6f Blake Maltby Add the design goals of the Turbulenz Engine to the readme
bmaltby authored
6
7 .. contents::
8 :local:
9
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
10
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
11 Examples using the Turbulenz Engine
12 ===================================
13
14 Games
15 -----
16
e43f523 James Austin Correct rST markup.
jamesaustin authored
17 * `Polycraft <https://turbulenz.com/games/polycraft>`__ - 3D
18 * `Save the day <https://turbulenz.com/games/save-the-day>`__ - 2D
19 * `Denki Blocks! <https://turbulenz.com/games/denkiblocks>`__ - 2D
20 * `Denki Word Quest <https://turbulenz.com/games/denkiwordquest>`__ - 2D
21 * `Score Rush <https://turbulenz.com/games/scorerush>`__ - 2D
22 * `Score Rush MP <https://turbulenz.com/games/scorerush-mp>`__ - multiplayer
23 * `Space Ark <https://turbulenz.com/games/space-ark>`__ - 3D
24 * `Apathy <http://apathy.plankhead.com/>`__ - `src <https://github.com/Zacqary/Apathy>`__ - 2D
25 * Salty Dogs - `src <https://github.com/zacqary/salty-dogs>`__
f525c97 James Austin [+] Add reference to Gargantia project
jamesaustin authored
26 * `Gargantia Sky Courier <http://fly.gargantia.jp>`__ - `src <https://github.com/turbulenz/gargantia_editor>`__ - 3D
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
27
28 Apps
29 ----
30
e43f523 James Austin Correct rST markup.
jamesaustin authored
31 * Sample app - `src <apps/sampleapp/scripts/sampleappmain.js>`__
32 * Touch, keyboard, mouse and pad controller input app - `src <apps/inputapp/tsscripts/inputapp>`__
33 * Viewer - `src <apps/viewer/scripts/viewer.js>`__
34 * Realtime multiplayer worm app - `src <apps/multiworm/tsscripts/worm>`__
35 * Asynchronous turn based multiplayer tic-tac-toe app - `src <apps/tictactoe/tsscripts/tictactoe>`__
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
36
37 Prototyping
38 -----------
39
483c773 James Austin Add two jsfiddle samples.
jamesaustin authored
40 * Prototyping basic app - `jsfiddle <http://jsfiddle.net/jamesaustin/WF47C/>`__
e43f523 James Austin Correct rST markup.
jamesaustin authored
41 * Prototyping sample app - `src <apps/protolibsampleapp/scripts/protolibsampleapp.js>`__
42 * Prototyping template app - `src <apps/protolibtemplateapp/scripts/app.js>`__
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
43
44 Samples
45 -------
46
47 * Setup:
48
e43f523 James Austin Correct rST markup.
jamesaustin authored
49 * `Device Initialization <http://biz.turbulenz.com/sample_assets/device_initialization.canvas.release.html>`__ - `src <samples/tsscripts/templates/device_initialization.ts>`__
50 * `Basic Loop <http://biz.turbulenz.com/sample_assets/basic_loop.canvas.release.html>`__ - `src <samples/tsscripts/templates/basic_loop.ts>`__
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
51
52 * 2D Rendering:
53
483c773 James Austin Add two jsfiddle samples.
jamesaustin authored
54 * `2D Canvas <http://biz.turbulenz.com/sample_assets/2dcanvas.canvas.release.html>`__ - `src <samples/tsscripts/templates/2dcanvas.ts>`__ - `jsfiddle <http://jsfiddle.net/jamesaustin/HRAw7/>`__
e43f523 James Austin Correct rST markup.
jamesaustin authored
55 * `Draw2D <http://biz.turbulenz.com/sample_assets/draw2d.canvas.release.html>`__ - `src <samples/tsscripts/templates/draw2d.ts>`__
56 * `TextureEffects <http://biz.turbulenz.com/sample_assets/textureeffects.canvas.release.html>`__ - `src <samples/tsscripts/templates/textureeffects.ts>`__
57 * `Immediate Mode Rendering <http://biz.turbulenz.com/sample_assets/immediate_mode_rendering.canvas.release.html>`__ - `src <samples/tsscripts/templates/immediate_mode_rendering.ts>`__
58 * Loading - `src <samples/tsscripts/templates/loading.ts>`__
59 * SVG - `src <samples/tsscripts/templates/svg.ts>`__
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
60
61 * 3D Rendering:
62
e43f523 James Austin Correct rST markup.
jamesaustin authored
63 * `Camera <http://biz.turbulenz.com/sample_assets/camera.canvas.release.html>`__ - `src <samples/tsscripts/templates/camera.ts>`__
64 * `Material <http://biz.turbulenz.com/sample_assets/material.canvas.release.html>`__ - `src <samples/tsscripts/templates/material.ts>`__
65 * `Forward rendering <http://biz.turbulenz.com/sample_assets/forward_rendering.canvas.release.html>`__ - `src <samples/tsscripts/templates/forward_rendering.ts>`__
66 * `Morphing <http://biz.turbulenz.com/sample_assets/morphing.canvas.release.html>`__ - `src <samples/tsscripts/templates/morphing.ts>`__
67 * `Post effects <http://biz.turbulenz.com/sample_assets/postfx.canvas.release.html>`__ - `src <samples/tsscripts/templates/postfx.ts>`__
68 * `Particles <http://biz.turbulenz.com/sample_assets/particles.canvas.release.html>`__ - `src <samples/tsscripts/templates/particles.ts>`__
69 * Deferred Rendering - `src <samples/tsscripts/templates/deferred_rendering.ts>`__
70 * Load model - `src <samples/tsscripts/templates/load_model.ts>`__
71 * Scene loading - `src <samples/tsscripts/templates/scene_loading.ts>`__
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
72
73 * Animation:
74
e43f523 James Austin Correct rST markup.
jamesaustin authored
75 * `Animation <http://biz.turbulenz.com/sample_assets/animation.canvas.release.html>`__ - `src <samples/tsscripts/templates/animation.ts>`__
76 * `Multiple animations <http://biz.turbulenz.com/sample_assets/multiple_animations.canvas.release.html>`__ - `src <samples/tsscripts/templates/multiple_animations.ts>`__
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
77
78 * 2D Physics:
79
e43f523 James Austin Correct rST markup.
jamesaustin authored
80 * `2D Physics <http://biz.turbulenz.com/sample_assets/physics2d.canvas.release.html>`__ - `src <samples/tsscripts/templates/physics2d.ts>`__
81 * `2D Physics constraints <http://biz.turbulenz.com/sample_assets/physics2d_constraints.canvas.release.html>`__ - `src <samples/tsscripts/templates/physics2d_constraints.ts>`__
82 * `2D Physics callbacks <http://biz.turbulenz.com/sample_assets/physics2d_callbacks.canvas.release.html>`__ - `src <samples/tsscripts/templates/physics2d_callbacks.ts>`__
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
83
84 * 3D Physics:
85
e43f523 James Austin Correct rST markup.
jamesaustin authored
86 * `3D Physics <http://biz.turbulenz.com/sample_assets/physics.canvas.release.html>`__ - `src <samples/tsscripts/templates/physics.ts>`__
87 * `3D Physics <benchmark(http://biz.turbulenz.com/sample_assets/physics_benchmark.canvas.release.html>`__ - `src <samples/tsscripts/templates/physics_benchmark.ts>`__
88 * `3D Physics collision mesh <http://biz.turbulenz.com/sample_assets/physics_collisionmesh.canvas.release.html>`__ - `src <samples/tsscripts/templates/physics_collisionmesh.ts>`__
89 * 3D Physics constraints - `src <samples/tsscripts/templates/physics_constraints.ts>`__
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
90
91 * Sound:
92
e43f523 James Austin Correct rST markup.
jamesaustin authored
93 * `Sound <http://biz.turbulenz.com/sample_assets/sound.canvas.release.html>`__ - `src <samples/tsscripts/templates/sound.ts>`__
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
94
95 * Video:
96
e43f523 James Austin Correct rST markup.
jamesaustin authored
97 * `Video playback <http://biz.turbulenz.com/sample_assets/video.canvas.release.html>`__ - `src <samples/tsscripts/templates/video.ts>`__
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
98
99 * Services:
100
e43f523 James Austin Correct rST markup.
jamesaustin authored
101 * Leaderboards - `src <samples/tsscripts/templates/leaderboards.ts>`__
102 * Multichat - `src <samples/tsscripts/templates/multichat.ts>`__
103 * Payments - `src <samples/tsscripts/templates/payments.ts>`__
104 * Userdata - `src <samples/tsscripts/templates/userdata.ts>`__
ae42836 James Austin Add lists of samples, apps and games.
jamesaustin authored
105
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
106 Features
107 ========
108
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
109 Low-level API
110 -------------
111
112 **Graphics**
113
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
114 - Simple shader-based immediate mode API:
27fb0ad James Austin Correct list layout.
jamesaustin authored
115
116 - A Shader may contain multiple Techniques, either single or multi-pass.
117 - Once a shader Technique is set on the Device, the parameters required by the program code can be updated by a TechniqueParameter object:
118 - TechniqueParameter objects hold multiple references to Textures, TechniqueParameterBuffers or individual values.
119 - Multiple TechniqueParameters can be set on the Device at once.
120
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
121 - Vertex buffers, Index buffers and Textures can be created, updated and destroyed dynamically.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
122 - Multiple Streams of Vertex buffers can be used at the same time.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
123 - Support for 1D, 2D, 3D and Cube textures: Any pixel format supported by the hardware.
124 - Asynchronous resource loading: multiple resource files can be downloaded on the fly, JavaScript code will be notified when resource is available for usage.
125 - Multiple image file formats: DDS, JPG, PNG and TGA.
126 - Support for textures archives containing multiple image files: less flexibility than individual files but better for optimal bandwidth usage.
127 - Occlusion queries:
27fb0ad James Austin Correct list layout.
jamesaustin authored
128
129 - Number of pixels rendered can be queried for a section of rendering.
130 - Available in plugin mode only.
131
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
132 - Fullscreen support (Supported platforms).
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
133 - Take screenshot feature:
134 - Video playback support:
27fb0ad James Austin Correct list layout.
jamesaustin authored
135
136 - WebM, MP4.
137 - Render video as texture.
138 - Playback controls play, pause, stop, resume, rewind.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
139
140 **Math**
141
142 - Math types:
27fb0ad James Austin Correct list layout.
jamesaustin authored
143
144 - *Vector2* *Vector3*, *Vector4*
145 - *Matrix33*, *Matrix34*, *Matrix43*, *Matrix44*
146 - *Quaternion*, *QuatPos*
147 - *AABB*
148
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
149 - Storage format optimized based on available support
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
150 - Optimized operations support *destination parameters*, reducing object allocation.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
151 - Array to/from Math type conversion utilities.
152
153 **Physics**
154
155 **3D**
156
157 - Easy-to-use efficient physics simulation.
27fb0ad James Austin Correct list layout.
jamesaustin authored
158
159 - Optimized JavaScript implementation.
160 - In plugin mode, this is a lightweight wrapper around the Bullet Physics Library http://bulletphysics.org/wordpress/
161
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
162 - Rigid bodies and collision objects: Plane, Box, Sphere, Capsule, Cylinder, Cone, Triangle Mesh, Convex Hull.
163 - Constraints: Point to Point, Hinge, Cone Twist, 6DOF, Slider.
164 - Ray and convex sweep queries: Returning closest point of impact and surface normal.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
165 - Character representation.
27fb0ad James Austin Correct list layout.
jamesaustin authored
166
167 - For use with 1st/3rd person games.
168 - Includes properties for velocity, position, crouch, jump height, death, on ground.
169
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
170 - Contact callbacks.
27fb0ad James Austin Correct list layout.
jamesaustin authored
171
172 - Rigidbodies, characters, collision objects.
173 - Called on presolve, added, processed, removed.
174 - Filter responses by mask.
175 - Triggers with no collision response.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
176
177 **2D**
178
179 - Efficient 2D physics simulation written specifically for JavaScript.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
180 - Shapes:
27fb0ad James Austin Correct list layout.
jamesaustin authored
181
182 - Circle, Box, Rectangle, Regular Polygon, Custom Polygon.
183 - Create shapes as sensors.
184 - Shape grouping and mask interactions.
185
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
186 - Collision detection:
27fb0ad James Austin Correct list layout.
jamesaustin authored
187
188 - Sweep & Prune, Box Tree Broadphases.
189 - Utilities for Raytest, Signed Distance, Intersection, Contains Point, Sweep Test.
190
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
191 - Simulation world:
27fb0ad James Austin Correct list layout.
jamesaustin authored
192
193 - Multiple simulation groups.
194 - Optional gravity.
195 - Customisable simulation iterations.
196
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
197 - Rigid body simulation: Dynamic, Static, Kinematic objects.
198 - Materials: Elasticity, Static/Dynamic/Rolling Friction, Density.
199 - Arbiters:
27fb0ad James Austin Correct list layout.
jamesaustin authored
200
201 - Contact grouping.
202 - Contact information: Position, Penetration, Normal/Tangent Impulse
203
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
204 - Constraints: Point to Point, Distance, Weld, Angle, Motor, Line, Pulley, Custom Constraint.
205 - Debug rendering:
27fb0ad James Austin Correct list layout.
jamesaustin authored
206
207 - Rigid Bodies, Constraints, Worlds, Lines, Curves, Rectangles, Circles, Spirals, Linear/Spiral Springs.
208 - Enabling and disabling of rendering types.
209 - Scaling for Draw2D viewport.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
210
211 **Sound**
212
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
213 - Easy-to-use efficient wrapper of hardware audio features: Utilizes Web Audio, <Audio> tag, `OpenAL <http://connect.creativelabs.com/openal/default.aspx>`__ dependent on platform support.
214 - 3D sound sources: Position, Direction, Velocity, Gain, Pitch, Loop.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
215 - Emulated 3D sound for stereo setups.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
216 - Asynchronous sound files loading: Multiple resource files can be downloaded on the fly, JavaScript code will be notified when resource is available for usage.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
217 - Uncompress audio dynamically.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
218 - Multiple sound file formats: OGG, WAV, MP3.
219 - Supported query for platform capabilities: Load the best audio format for the platform.
220 - Effect/Filter support: Reverb, Echo, Low Pass
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
221
222 **Networking**
223
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
224 - Bi-directional, full-duplex communications channels, over a TCP socket:
27fb0ad James Austin Correct list layout.
jamesaustin authored
225
226 - Utilizes browser Websocket support.
227 - Efficient native implementation of WebSockets for platforms without support:
228
229 - http://en.wikipedia.org/wiki/WebSocket
230 - http://dev.w3.org/html5/websockets/
231
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
232 - HTTP-compatible handshake so that HTTP servers can share their default HTTP and HTTPS ports (80 and 443) with a WebSocket server.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
233 - Support for secure connections as part of the standard.
234 - Support for data compression with the extension `deflate-frame`.
235
236 **Input**
237
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
238 - Access to input types: Keyboard, Mouse, Xbox360 Pad, Joysticks, Wheels, Touch, Multi-touch
239 - Asynchronous event system when state changes:
27fb0ad James Austin Correct list layout.
jamesaustin authored
240
241 - JavaScript code is notified when input changes.
242 - Events for keydown, keyup, mousedown, mouseup, mousewheel, mousemove,
243 mouseover, mouseenter, mouseleave, paddown, padup, focus, blur, mouselocklost,
244 touchstart, touchend, touchmove, touchmove, touchenter, touchleave, touchcancel.
245
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
246 - Additional mouse features: hiding/showing platform icon, locking/unlocking (supported platforms).
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
247 - Language independent keymapping.
248
249 High-level API
250 --------------
251
252 **Scene Graph**
253
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
254 - Flexible JSON file format: Could describe either a whole scene or individual meshes.
255 - Asynchronous loading of external references:
27fb0ad James Austin Correct list layout.
jamesaustin authored
256
257 - If a scene contains references to external meshes they are all loaded in parallel and attached to the main scene when ready.
258 - Support for optimal reuse of same mesh on different locations.
259
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
260 - Pluggable renderer system:
27fb0ad James Austin Correct list layout.
jamesaustin authored
261
262 - Links between geometries, effects and materials are resolved at
263 runtime.
264 - Easy swap of multiple rendering techniques for same assets.
265
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
266 - Geometry sharing: Geometry information can be optimally reused on multiple scene locations with different rendering effects.
267 - Flexible scene hierarchy nodes: Lights, Geometries, Animation, Physics.
268 - Visibility queries: Portals, Frustum, Overlapping Box.
269 - Sorting and grouping: Visible nodes are sorted and grouped for optimal rendering: Opaque, Transparent, Decal.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
270 - Lazy evaluation of node updates.
271
272 **Animation**
273
274 - 3D animation for scene geometry.
275 - Skeleton/Skinning animation.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
276 - Animation controllers:
27fb0ad James Austin Correct list layout.
jamesaustin authored
277
278 - Interpolation, Overloaded Node, Reference, Transition, Blend, Mask, Pose, Skin, GPU Skin, Skinned Node.
279 - Controllers can be combined for desired effect.
280
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
281 - Dynamically update scene data.
282
283 **Resource Manager**
284
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
285 - Asynchronous loading avoiding duplicates: Additional remapping layer for easy URL redirection.
286 - Provide default resources if missing: Game can provide custom default resource to be used when a required one is missing or still loading.
287 - Multiple managers for individual needs: Animations, Effects, Fonts, Shaders, Sounds, Textures.
288 - Bandwidth and hardware scaling by selecting different assets and effects depending on machine and Internet connection performance.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
289 - Client-side asset cache for optimizing and reusing requests.
290
291 **Server Requests**
292
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
293 - HTTP & AJAX request functionality:
27fb0ad James Austin Correct list layout.
jamesaustin authored
294
295 - Automatic retry and error handling.
296 - Cross-browser support.
297 - Encrypted API support.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
298
299 **Deferred Renderer**
300
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
301 - Unlimited number of lights: Point, Spot, Directional, Ambient.
302 - Texture based light falloff: Allows multi-colored lights and cheap fake shadows, for example the typical fan under a light source.
303 - Materials with multiple texture maps: Specular color and intensity, Normal vector, Glow color, Alpha.
304 - Pluggable post effects:
27fb0ad James Austin Correct list layout.
jamesaustin authored
305
306 - Easy set-up for full screen post effects as part of the final deferred shading.
307 - Copy, Fade in, Modulate, Bicolor, Blend.
308
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
309 - Exponential shadow maps:
27fb0ad James Austin Correct list layout.
jamesaustin authored
310
311 - Reuse of texture shadow maps to save video memory.
312 - Gaussian blur for smooth results.
313 - Exponential depth information to avoid light bleeding.
314
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
315 - Volumetric fog.
316 - 4 weight GPU skinning.
317 - UV animation.
318 - Wireframe mode.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
319 - Callbacks for additional passes: decals, transparency, debug
320 - Available in plugin mode only until draw buffers are added to WebGL http://www.khronos.org/registry/webgl/extensions/WEBGL_draw_buffers/
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
321
322 **Forward Renderer**
323
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
324 - Unlimited number of lights: Point, Spot, Directional, Ambient.
325 - Texture based light falloff: Allows multi-colored lights and cheap fake shadows, for example the typical fan under a light source.
326 - Materials with multiple texture maps: Specular color and intensity, Normal vector, Glow color, Alpha.
327 - Pluggable post effects:
27fb0ad James Austin Correct list layout.
jamesaustin authored
328
329 - Easy set-up for full screen post effects as part of the final
330 deferred shading.
331 - Copy, Fade in, Modulate, Bicolor, Blend.
332
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
333 - Exponential shadow maps:
27fb0ad James Austin Correct list layout.
jamesaustin authored
334
335 - Reuse of texture shadow maps to save video memory.
336 - Gaussian blur for smooth results.
337 - Exponential depth information to avoid light bleeding.
338
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
339 - 4 weight GPU skinning.
340 - UV animation.
341 - Wireframe mode.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
342 - Callbacks for additional passes: decals, transparency, debug
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
343
344 **Default Renderer**
345
346 - Single point and ambient light.
347 - Pixel-based lighting.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
348 - Materials with multiple texture maps: Specular color and intensity, Normal vector, Glow color, Alpha.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
349 - Optimzed for speed and compatibility on a wide range of hardware.
350 - 4 weight GPU skinning.
351 - UV animation.
352 - Wireframe mode.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
353 - Callbacks for additional passes: decals, transparency, debug
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
354
355 **Simple Renderer**
356
357 - Single point and ambient light.
358 - Vertex-based lighting.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
359 - Materials with multiple texture maps: Specular color and intensity, Normal vector, Glow color, Alpha.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
360 - Optimzed for speed and compatibility on a wide range of hardware.
361 - 4 weight GPU skinning.
362 - UV animation.
363 - Wireframe mode.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
364 - Callbacks for additional passes: decals, transparency, debug
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
365
366 **2D Rendering**
367
368 **Draw2D**
369
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
370 - 2D sprite-based renderer: Batches sprites for efficiency.
8952426 James Austin Tidy Draw.
jamesaustin authored
371 - Draw modes:
372
373 - **Draw:** Draw object literal,
374 - **DrawRaw:** Draw buffer data,
375 - **DrawSprite:** Draw sprite reference.
376
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
377 - Scalable viewport: Input coordinate mapping.
378 - Sort modes: Immediate, Deferred, Texture.
379 - Blend modes: Opaque, Additive, Alpha.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
380 - Custom shader support.
381 - Render-to-target support.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
382 - Texture effects: Distort, Gaussian Blur, Bloom, Color, Grey Scale, Sepia, Negative, Saturation, Hue, Brightness, Contrast.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
383 - Recording performance data.
384
385 **Canvas2D**
386
387 - Accelerated implementation of `canvas 2D API <http://www.w3.org/html/wg/drafts/2dcontext/html5_canvas/>`__.
388 - Runs on WebGL/OpenGL depending on platform.
389 - SVG rendering.
390 - Text rendering via FontManager.
391 - For complete implementation see `canvas element specification <http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#the-canvas-element>`__
392
393 **Utilities**
394
27fb0ad James Austin Correct list layout.
jamesaustin authored
395 - Allocation and management of graphics buffers: Vertex buffers, Index buffers.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
396 - API controlled JavaScript profiling:
27fb0ad James Austin Correct list layout.
jamesaustin authored
397
398 - Per-function millisecond accuracy timing.
399 - Record top-down or bottom-up function trees.
400 - Calculate the time spent by an individual function or
401 the total spent by sub-functions.
402 - Identify the source file and line number of problematic areas.
403
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
404 - Memory usage identification:
27fb0ad James Austin Correct list layout.
jamesaustin authored
405
406 - Retrieve the object count of constructed object types.
407 - Take snapshots and compare memory fluctuations.
408
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
409 - Encryption and decryption of server-side requests for TZO formats.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
410 - Debug utility with function stripping for performance:
27fb0ad James Austin Correct list layout.
jamesaustin authored
411
412 - assert, log, abort.
413 - Complete stacktrace.
414 - Supports adding custom functions.
415
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
416 - Network Simulator:
27fb0ad James Austin Correct list layout.
jamesaustin authored
417
418 - Simulates latency and network behaviour.
419 - Client-side manipulation of multiplayer session messages.
420 - Simulates spikes in network traffic.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
421
422 Turbulenz Service API
423 ---------------------
424
425 **Leaderboards**
426
427 - Submitting/retrieving ranked friend/global leaderboards.
61d23c0 David Fooks Added more features to the leaderboards in the readme
davidfooks authored
428 - Sort by either higher or lower scores.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
429 - Infinitely scrollable scoreboards.
430 - Friend's score notifications.
61d23c0 David Fooks Added more features to the leaderboards in the readme
davidfooks authored
431 - Aggregate scores.
432 - Default score entries.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
433
434 **Badges**
435
436 - Achievement system for awarding game progress.
437 - Custom badge shape and design
438 - Progression badges.
439 - Achievement notification.
440
441 **Payments**
442
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
443 - Payments API: In game, On website, App stores.
444 - Payment methods: Single purchase, Micro transactions.
445 - Purchasable items: Ownable, Consumeable.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
446
447 **Userdata**
448
449 - Per-user save game information.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
450 - Key-value pair data storage: Settings, Preferences, Personal items.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
451
452 **Userprofile**
453
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
454 - Game player's profile information: Username, Display name, Language, Age, Country, Guest user.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
455
456 **Gameprofile**
457
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
458 - Game status of a player:
27fb0ad James Austin Correct list layout.
jamesaustin authored
459
460 - Viewable by other players a game.
461 - Custom field information decided by game.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
462
463 **Multiplayer**
464
465 - Real-time session match-making between friends and public users.
466 - Session creation/joining.
467 - Multiplayer session invite and notification.
468
1c02c74 David Fooks Release notes and general docs changes
davidfooks authored
469 **Datashares**
470
471 - Shared key-value store for turn based games and user generated content.
472 - Read only and read and write access.
473 - Find other users public shares or filter by username.
474
475 **Notifications**
476
477 - Send delayed notifications to the current user.
478 - Send instant notifications to other users.
479 - Notification types: Email, website pop-up and in-game.
480
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
481 **Metrics**
482
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
483 - Custom event submission:
27fb0ad James Austin Correct list layout.
jamesaustin authored
484
485 - Can be used to gather progress during game.
486 - Exportable from developer services.
487 - Events identifiable by custom key.
488 - Allows additional numerical data.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
489
490 **Bridge**
402414b Ian Ballantyne Fixed bridge typo.
ianballantyne authored
491
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
492 - Bi-directional communication channel between game and webpage.
493 - Allows messages to be exchanged.
771d8d5 James Austin Compact the features list to save space.
jamesaustin authored
494 - Live updating: Badge progress, notifications, loading/saving status.
714ceb8 Ian Ballantyne Added files lost during merge from split. Docs changes.
ianballantyne authored
495
496 **Utilities**
497
498 - Mapping between game resources references and content distribution network.
499 - Uniquely identifiable gamesession.
500 - Service availability notification.
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
501
aabcd6f Blake Maltby Add the design goals of the Turbulenz Engine to the readme
bmaltby authored
502 What Are the Design Goals of the Turbulenz Engine
503 =================================================
504
505 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.
506
507 To achieve this target the Turbulenz team followed these rules when writing code:
508
509 **Modularity**
510
511 - Users should be able to pick what they want and replace what they don't.
512 - When possible new functionality should be orthogonal to existing one.
513
514 **High performance**
515
516 - Strict coding standards to keep code efficient.
517 - Keep memory allocations to minimum, reuse existing objects or arrays whenever possible, use scratch pads, combine multiple separate objects into a single one.
518 - Use most efficient storage for each data, Typed Arrays when possible.
519 - 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.
520 - Be aware of performance differences between browsers.
521 - Profile often.
522
523 **Asynchronous loading**
524
525 - No API should block waiting for a response from the server, avoid polling whenever possible, use callbacks or Promises, to notify of data availability.
526
527 **Data driven**
528
529 - The target should be to make the game a simple dumb player of data, all functionality defined by simple data files.
530
531 **Simple well documented file formats**
532
533 - Define simple, easy to create asset formats that can trivially be connected to any tool chain.
534
535 **Scalability**
536
537 - Design interfaces that can be implemented with different level of detail or quality settings in order to scale from mobile to desktops.
538
539 **Power without control is nothing**
540
541 - Make sure users can do exactly what they want, with a helper layer put on top if required, document performance implications at every level.
542
543 **Fault tolerant**
544
545 - 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.
546
547 **Fast loading**
548
549 - Reduce amount of data to be downloaded, compress data efficiently.
550 - Use the browser cache efficiently, use unique file names based on content and tell the browser to cache forever.
551
552 **Maintainability**
553
554 - Strict coding standards to keep code readable, easy to maintain and debug.
555 - Write unit tests, samples and documentation for every new code path.
556
557 **Targeted**
558
559 - This is a game engine, for games.
560
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
561
562 History
563 =======
564
565 The Engine was created and is maintained by `Turbulenz Limited <http://biz.turbulenz.com>`__ and was open sourced
566 in April 2013.
567
e031420 Blake Maltby Fix release version numbering and update readme for tarballs
bmaltby authored
568 The latest release is 1.3.1 which is tagged in the repository or a tarball/zip can be can be downloaded from
569 `here <https://github.com/turbulenz/turbulenz_engine/archive/release_1.3.1.tar.gz>`__
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
570
cdbfa71 Blake Maltby Change README links to relative urls
bmaltby authored
571 A full history of changes can be found in the `Changelog <docs/source/changelog.rst>`__
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
572
573
04a3308 Blake Maltby Move the dependencies section of the README to before the setup section ...
bmaltby authored
574 Pre-Requisites
575 ==============
576
577 The pre-requisites for the open source version of the Turbulenz Engine allowing you to use the various
578 commands are
579
580 - Python 2.7.x.
581
582 - For Windows we recommend a 32bit install of Python.
583 - If you have multiple Python versions installed e.g. 3.x you may need to run commands with ``python2.7``
fb68654 Blake Maltby Fix section link and windows python path
bmaltby authored
584 - On Windows if you didn't add Python to your path in the installer you may need to run ``C:\Python27\python.exe``
04a3308 Blake Maltby Move the dependencies section of the README to before the setup section ...
bmaltby authored
585 You can check your version with
586 ::
587
588 $ python --version
589 Python 2.7.3
590
591 - VirtualEnv - version 1.9.1 or higher recommended
592 You can check your version with
593 ::
594
595 $ virtualenv --version
596 1.9.1
597
598 - UglifyJS, turbulenz_build, DefinitelyTyped and NvTriStrip which are included via Git submodules contained
599 within the Turbulenz Engine repository.
600
601 - Additional Python packages which will be automatically installed during the initial environment creation
602 using a Python package manager.
603
604 Pre-requisites for building the tools cgfx2json and NvTriStrip via ``python manage.py tools``
605
606 - Compiler Toolchain
607
608 - Windows : Any one of
609
610 - Microsoft Visual Studio 2008 with SP1
611 - Microsoft Visual Studio 2010
6f73ce3 Blake Maltby Updated for building tools with Visual Studio express editions
bmaltby authored
612 - Visual C++ 2010 Express
04a3308 Blake Maltby Move the dependencies section of the README to before the setup section ...
bmaltby authored
613 - Microsoft Visual Studio 2012 with update 2
6f73ce3 Blake Maltby Updated for building tools with Visual Studio express editions
bmaltby authored
614 - Microsoft Visual Studio Express 2012 for Windows Desktop with update 2
04a3308 Blake Maltby Move the dependencies section of the README to before the setup section ...
bmaltby authored
615
616 - Mac OSX : Xcode with the command line tools
617
618 - Linux : GCC 4.6.x or higher
619
0f8a1b8 Blake Maltby Minor doc change for clarity on cgtoolkit requirements
bmaltby authored
620 - `NVIDIA CgToolkit <https://developer.nvidia.com/cg-toolkit>`__ version 3.1 or higher. The repository
621 includes the binaries for Windows, if you're developing on Mac OSX or Linux please download and install it.
04a3308 Blake Maltby Move the dependencies section of the README to before the setup section ...
bmaltby authored
622
623 - OpenGL development libraries, these are included on Windows and Mac OSX with the compiler toolchains. For
624 debian based linux distributions the libgl1-mesa-dev package will provide the required files (e.g. ``sudo
088f3a3 Ian Ballantyne Fixed minor typo in linux docs for libgl
ianballantyne authored
625 apt-get install libgl1-mesa-dev``), for other linux distributions find the package supplying GL/gl.h and libGL.so
04a3308 Blake Maltby Move the dependencies section of the README to before the setup section ...
bmaltby authored
626
627
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
628 Setup Guide
629 ===========
630
631 There are two ways to get up and running with the Turbulenz Engine, you can downloaded a packaged fully QA'd
632 snapshot release from the `Turbulenz Hub <https://hub.turbulenz.com>`__. These installers are available for
633 Windows, Mac OSX and Linux and will install all the required packages and dependencies to get started,
68927a6 Blake Maltby Update setup guide styling
bmaltby authored
634 a full guide can be found at `<http://docs.turbulenz.com/installing.html>`__
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
635
636 *Note: SDK versions prior to 0.26.0 were released under a non open source license.*
637
638 If you want to run with the latest version or would like to contribute to the open source project the steps for
639 getting setup are included below. Use of the open source repository is tested against Windows, Mac OSX and Linux
640 but may also work on other unix-like operating systems.
641
642 Setup
643 -----
644
645 1. Clone the repository `<http://github.com/turbulenz/turbulenz_engine>`__ (or if you wish you can fork the repository
68927a6 Blake Maltby Update setup guide styling
bmaltby authored
646 on GitHub and clone that). To clone the repository maintained by Turbulenz use
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
647 ::
68927a6 Blake Maltby Update setup guide styling
bmaltby authored
648
7523207 Blake Maltby Update readme and .gitmodules to use git read only links rather than SSH...
bmaltby authored
649 $ git clone git://github.com/turbulenz/turbulenz_engine.git
68927a6 Blake Maltby Update setup guide styling
bmaltby authored
650
651 2. The Turbulenz Engine submodules the following technology in the external folder
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
652
d264001 Blake Maltby Fix styling in readme setup guide
bmaltby authored
653 + tzbuild: https://github.com/turbulenz/turbulenz_build
654 + DefinitelyTyped: https://github.com/borisyankov/DefinitelyTyped
655 + UglifyJS: https://github.com/mishoo/UglifyJS.git
68927a6 Blake Maltby Update setup guide styling
bmaltby authored
656
657 Initialize the Git submodules with
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
658 ::
92377bd Blake Maltby More layout changes for readme
bmaltby authored
659
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
660 $ git submodule update --init
68927a6 Blake Maltby Update setup guide styling
bmaltby authored
661
04a3308 Blake Maltby Move the dependencies section of the README to before the setup section ...
bmaltby authored
662 3. Check you have the `pre-requisites`_ installed
68927a6 Blake Maltby Update setup guide styling
bmaltby authored
663
664 4. From the cloned repository create a VirtualEnv environment to install the required Python packages and NodeJS,
cc5b4d9 Blake Maltby Add a note about maybe needing to specify a full path to python on the e...
bmaltby authored
665 allowing you to use all the features of the Turbulenz Engine. Note if Python is not on your shell's path you
666 will need to specify the full path for this first command.
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
667 ::
68927a6 Blake Maltby Update setup guide styling
bmaltby authored
668
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
669 $ python manage.py env
68927a6 Blake Maltby Update setup guide styling
bmaltby authored
670
671 5. Activate the environment in your shell.
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
672 ::
68927a6 Blake Maltby Update setup guide styling
bmaltby authored
673
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
674 $ source env/bin/activate - for bash and similar shells
675 > env\scripts\activate.bat - for Windows
68927a6 Blake Maltby Update setup guide styling
bmaltby authored
676
677 6. If you want to move onto the API tutorial section next then your final command is to build the JavaScript sources
678 from the TypeScript sources. The next section will detail some of the additional actions you can perform or you
679 can move onto `Getting Started With The API`_
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
680 ::
68927a6 Blake Maltby Update setup guide styling
bmaltby authored
681
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
682 $ python manage.py jslib
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
683
684 Working With The Open Source Project
685 ------------------------------------
686
687 The manage.py script at the top level of the repository provides a set of commands for managing the Engine, the
688 script should be run as ``python manage.py command`` on Windows but can usually be shortcut to ``./manage.py command``
689 on unix shells. Running the script with ``--help`` will give a list of commands available, most of these are
690 described below. All the commands other than the env command expect to have the VirtualEnv environment activated
691 as described in the setup section.
692
693 - **JavaScript Sources** - The Turbulenz Engine source is written in TypeScript. To generate the JavaScript version
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
694 of the engine source run the command
695 ::
696
697 $ python manage.py jslib
698
8efade3 Blake Maltby Add tools command and compiler dependencies
bmaltby authored
699 - **Tools** - The Turbulenz Engine includes a number of Python tools which are installed during the env command.
700 In addition the Engine includes a CGFX shader conversion tool which can be built with the following command.
fb68654 Blake Maltby Fix section link and windows python path
bmaltby authored
701 See the `pre-requisites`_ section for details of required compiler toolchains.
8efade3 Blake Maltby Add tools command and compiler dependencies
bmaltby authored
702 ::
703
704 $ python manage.py tools
705
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
706 - **Documentation** - The Turbulenz Engine documentation is based on restructured text sources. To build the html
707 documentation run the command
708 ::
709
710 $ python manage.py docs
711
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
712 - **Samples** - Various samples are included with the Turbulenz Engine. These can be built from their TypeScript
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
713 sources with the command below. This generates a set of html files, JavaScript and asset JSON files which can
714 be served with a web server such as the Turbulenz Local Development Server.
715 ::
716
717 $ python manage.py samples
718
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
719 - **Applications** - The Turbulenz Engine project includes a few larger applications and some templates for building
720 your own application. These can be found in the apps folder, and can be built with the command
982d104 Blake Maltby Tweak the indentation in the setup guide and make the following commands...
bmaltby authored
721 ::
722
723 $ python manage.py apps
724
725 You can also build individual apps by specifying their name e.g.
726 ::
727
728 $ python manage.py apps multiworm
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
729
730 - **Command Line Tools** - Various command line tools for processing code and assets are installed as part of the
731 virtual environment. These are available at the command line e.g. running ``dae2json`` will execute the dae2json
732 tool used to convert Collada assets to a Turbulenz Engine JSON asset format. See the
733 `tools <http://docs.turbulenz.com/tools/index.html>`__ section in the documentation for more details on the tools.
914a328 David Fooks Small README changes
davidfooks authored
734
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
735 - **Local Development Server** - Setting up the environment also includes a locally hosted web server which can be
736 used for development of HTML5 games and applications. See the
0599bec David Fooks Added how to start the local server to docs for open source repo
davidfooks authored
737 `Local Server <https://github.com/turbulenz/turbulenz_local>`__ repository for more details.
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
738
739
740 Getting Started With The API
741 ============================
742
743 To try the Turbulenz APIs requires only a text editor and a browser such as Google Chrome or Mozilla Firefox.
914a328 David Fooks Small README changes
davidfooks authored
744 Create an HTML file with the following content and place it in the root of the Turbulenz directory::
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
745
746 <html>
747 <head>
748 <title>Turbulenz - API - Clear Screen Example</title>
749 <script src="jslib/debug.js"></script>
750 <script src="jslib/webgl/turbulenzengine.js"></script>
751 <script src="jslib/webgl/graphicsdevice.js"></script>
752 </head>
753 <body>
754 <canvas id="canvas" width="640px" height="480px"/>
755 <script>
756 TurbulenzEngine = WebGLTurbulenzEngine.create({
757 canvas: document.getElementById("canvas")
758 });
759 var graphicsDevice = TurbulenzEngine.createGraphicsDevice({});
760
761 var bgColor = [1.0, 1.0, 0.0, 1.0];
762
763 function update() {
764 if (graphicsDevice.beginFrame()) {
765 graphicsDevice.clear(bgColor, 1.0);
766 graphicsDevice.endFrame();
767 }
768 }
769
770 TurbulenzEngine.setInterval(update, 1000 / 60);
771 </script>
772 </body>
773 </html>
774
775 After defining a <canvas> element of 640x480 pixels, this code will create the TurbulenzEngine and request the GraphicDevice module.
e24039d Ian Ballantyne Readme update typo.
ianballantyne authored
776 Using an update function called at a frequency of 60fps, the GraphicsDevice will clear the screen yellow.
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
777 To run the example, open the HTML file in your browser.
778 You should see a yellow rectangle.
779
780 To use assets such as images you will need to host a HTML file and assets on a webserver.
781 Any webserver will work, a quick way to try is to activate the Turbulenz environment in the root of the Turbulenz directory and run::
782
783 python -m SimpleHTTPServer
784
785 This command will host the contents of the Turbulenz directory on your machine as a webserver.
786
787 To demonstrate loading an asset you can try loading an image file and drawing it as a textured sprite using the Draw2D API.
914a328 David Fooks Small README changes
davidfooks authored
788 Create another HTML file with the following content and also place it in the root of the Turbulenz directory::
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
789
790 <html>
791 <head>
792 <title>Turbulenz - API - Textured Sprite Example</title>
793 <script src="jslib/debug.js"></script>
794 <script src="jslib/webgl/turbulenzengine.js"></script>
795 <script src="jslib/webgl/graphicsdevice.js"></script>
796 <script src="jslib/draw2d.js"></script>
797 </head>
798 <body>
799 <canvas id="canvas" width="640px" height="480px"/>
800 <script>
8c27b4e Ian Ballantyne Minor corrections to the readme.
ianballantyne authored
801 TurbulenzEngine = WebGLTurbulenzEngine.create({
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
802 canvas: document.getElementById("canvas")
803 });
804 var graphicsDevice = TurbulenzEngine.createGraphicsDevice({});
805 var draw2D = Draw2D.create({
806 graphicsDevice: graphicsDevice
807 });
808
809 var bgColor = [1.0, 1.0, 0.0, 1.0];
810
811 var sprite = Draw2DSprite.create({
812 width: 100,
813 height: 100,
814 x: graphicsDevice.width / 2,
815 y: graphicsDevice.height / 2,
816 color: [1.0, 1.0, 1.0, 1.0],
817 rotation: Math.PI / 4
818 });
819
820 var texture = graphicsDevice.createTexture({
821 src: "assets/textures/crate.jpg",
822 mipmaps: true,
823 onload: function (texture)
824 {
825 if (texture)
826 {
827 sprite.setTexture(texture);
828 sprite.setTextureRectangle([0, 0, texture.width, texture.height]);
829 }
830 }
831 });
832
833 var PI2 = Math.PI * 2;
834 var rotateAngle = PI2 / 360; // 1 deg per frame
835
836 function update() {
837
838 sprite.rotation += rotateAngle;
839 sprite.rotation %= PI2; // Wrap rotation at PI * 2
840
8c27b4e Ian Ballantyne Minor corrections to the readme.
ianballantyne authored
841 if (graphicsDevice.beginFrame()) {
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
842 graphicsDevice.clear(bgColor, 1.0);
843
844 draw2D.begin();
845 draw2D.drawSprite(sprite);
846 draw2D.end();
847
848 graphicsDevice.endFrame();
849 }
850 }
851
852 TurbulenzEngine.setInterval(update, 1000 / 60);
853 </script>
854 </body>
855 </html>
856
857 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.
858 You should see a spinning textured box in the middle of a yellow rectangle.
859
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
860 The next step is render a simple textured mesh in 3D.
861 To do this you will need to build some assets from their source files.
862 Make sure you have run the *tools* command to build the tools for your platform::
863
864 $ python manage.py tools
865
b8da471 Ian Ballantyne Typo fix for readme deps link and trys -> tries
ianballantyne authored
866 *Note: The requirements for building the tools is different per platform. See the* `Pre-Requisites`_ *section.*
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
867
868 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.
869 You will need these assets::
870
871 - models/duck.dae
872 - textures/duck.png
873 - textures/default_light.png
874 - shaders/shadowmapping.cgfx
875 - shaders/zonly.cgfx
876 - shaders/forwardrendering.cgfx
877 - shaders/forwardrenderingshadows.cgfx
878 - shaders/debug.cgfx
879 - shaders/font.cgfx
930cf79 Ian Ballantyne Updated README steps for protolib spinning duck section
ianballantyne authored
880 - shaders/simplesprite.cgfx
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
881 - fonts/opensans-8.fnt
882 - fonts/opensans-16.fnt
883 - fonts/opensans-32.fnt
884 - fonts/opensans-64.fnt
885 - fonts/opensans-128.fnt
886 - textures/opensans-8_0.png
887 - textures/opensans-16_0.png
888 - textures/opensans-32_0.png
889 - textures/opensans-64_0.png
890 - textures/opensans-128_0.png
891
892 Copy this text into a file called "deps.yaml" and place it in the root of the Turbulenz directory.
893 Having built the tools you can now run this command with the Turbulenz environment activated::
894
3286ed9 David Fooks Fix for wrong slash in README python command
davidfooks authored
895 $ python scripts/buildassets.py --root . --assets-path assets
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
896
897 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.
b8da471 Ian Ballantyne Typo fix for readme deps link and trys -> tries
ianballantyne authored
898 When a library tries to request one of these files, it will be able to find it in the staticmax directory.
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
899 Now you can create the mesh example HTML file and place it at the root of the Turbulenz directory::
900
901 <html>
902 <head>
903 <title>Turbulenz - API - Textured Mesh Example</title>
904 <script>
905 var TurbulenzEngine = {};
906 </script>
907 <script src="jslib/debug.js"></script>
908 <script src="jslib/webgl/turbulenzengine.js"></script>
909 <script src="jslib/webgl/graphicsdevice.js"></script>
910 <script src="jslib/webgl/inputdevice.js"></script>
911 <script src="jslib/webgl/sounddevice.js"></script>
e6af889 Added missing mathdevice.js.
David Galeano authored
912 <script src="jslib/webgl/mathdevice.js"></script>
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
913
930cf79 Ian Ballantyne Updated README steps for protolib spinning duck section
ianballantyne authored
914 <script src="jslib/aabbtree.js"></script>
915 <script src="jslib/assettracker.js"></script>
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
916 <script src="jslib/camera.js"></script>
930cf79 Ian Ballantyne Updated README steps for protolib spinning duck section
ianballantyne authored
917 <script src="jslib/draw2d.js"></script>
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
918 <script src="jslib/effectmanager.js"></script>
919 <script src="jslib/fontmanager.js"></script>
930cf79 Ian Ballantyne Updated README steps for protolib spinning duck section
ianballantyne authored
920 <script src="jslib/forwardrendering.js"></script>
921 <script src="jslib/geometry.js"></script>
922 <script src="jslib/indexbuffermanager.js"></script>
923 <script src="jslib/light.js"></script>
924 <script src="jslib/loadingscreen.js"></script>
925 <script src="jslib/material.js"></script>
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
926 <script src="jslib/observer.js"></script>
930cf79 Ian Ballantyne Updated README steps for protolib spinning duck section
ianballantyne authored
927 <script src="jslib/renderingcommon.js"></script>
928 <script src="jslib/requesthandler.js"></script>
929 <script src="jslib/resourceloader.js"></script>
930 <script src="jslib/scene.js"></script>
931 <script src="jslib/scenenode.js"></script>
932 <script src="jslib/shadermanager.js"></script>
933 <script src="jslib/shadowmapping.js"></script>
934 <script src="jslib/soundmanager.js"></script>
935 <script src="jslib/texturemanager.js"></script>
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
936 <script src="jslib/utilities.js"></script>
930cf79 Ian Ballantyne Updated README steps for protolib spinning duck section
ianballantyne authored
937 <script src="jslib/vertexbuffermanager.js"></script>
938 <script src="jslib/vmath.js"></script>
939
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
940 <script src="jslib/services/turbulenzbridge.js"></script>
941 <script src="jslib/services/turbulenzservices.js"></script>
942 <script src="jslib/services/gamesession.js"></script>
943 <script src="jslib/services/mappingtable.js"></script>
944
945 <script src="protolib/duimanager.js"></script>
946 <script src="protolib/jqueryextend.js"></script>
947 <script src="protolib/simplesprite.js"></script>
948 <script src="protolib/simplefonts.js"></script>
949 <script src="protolib/simplesceneloader.js"></script>
950 <script src="protolib/debugdraw.js"></script>
951 <script src="protolib/sceneloader.js"></script>
952 <script src="protolib/soundsourcemanager.js"></script>
953 <script src="protolib/protolib.js"></script>
954
955 </head>
956 <body>
957 <canvas id="canvas" width="640px" height="480px"/>
958 <script>
8c27b4e Ian Ballantyne Minor corrections to the readme.
ianballantyne authored
959 TurbulenzEngine = WebGLTurbulenzEngine.create({
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
960 canvas: document.getElementById("canvas")
961 });
962 var mathDevice = null;
963
964 var mesh = null;
965 var rotationMatrix = null;
966 var rotationAngleMatrix = null;
967
968 var protolib = Protolib.create({
969 onInitialized: function onIntializedFn(protolib)
970 {
971 mathDevice = protolib.getMathDevice();
972 protolib.setCameraPosition(mathDevice.v3Build(0, 1, -2));
973 protolib.setCameraDirection(mathDevice.v3Build(0, 0, 1));
974 protolib.setAmbientLightColor(mathDevice.v3Build(1, 1, 1));
975 protolib.addPointLight({
976 v3Position: mathDevice.v3Build(-1, 1, -1),
977 v3Color: mathDevice.v3Build(1, 1, 1),
978 radius: 10
979 });
980 mesh = protolib.loadMesh({
981 mesh: "models/duck.dae"
982 });
983 rotationMatrix = mathDevice.m43BuildIdentity();
984 rotationAngleMatrix = mathDevice.m43BuildIdentity();
985 mathDevice.m43SetAxisRotation(rotationAngleMatrix,
986 mathDevice.v3Build(0, 1, 0),
987 (Math.PI * 2) / 360);
988 }
989 })
990
991 function update() {
992
993 if (protolib.beginFrame())
994 {
995 if (mesh)
996 {
997 mesh.getRotationMatrix(rotationMatrix);
998 mathDevice.m43Mul(rotationMatrix, rotationAngleMatrix, rotationMatrix);
999 mesh.setRotationMatrix(rotationMatrix);
1000 }
1001 protolib.endFrame();
1002 }
1003 }
1004
1005 TurbulenzEngine.setInterval(update, 1000 / 60);
1006 </script>
1007 </body>
1008 </html>
1009
1010 This file is quite similar to the previous examples, but it requires a few more Turbulenz libraries to run.
1011 This time you should see a spinning duck with a yellow texture on a white background and lit by a static point light.
1012
1013 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.
1014
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
1015 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.
1016
1017 For more information on the various APIs, see the following links:
1018
1019 * `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>`__
1020 * `High-level API <http://docs.turbulenz.com/jslibrary_api/high_level_api.html>`__
1021 * `Turbulenz Services API <http://docs.turbulenz.com/turbulenz_services/index.html>`__
a674be9 Ian Ballantyne Added protolib to the README. Including links to protolib, assets etc.
ianballantyne authored
1022 * `Protolib API <http://docs.turbulenz.com/protolib/protolib_api.html>`__
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
1023
e0dc1ae Blake Maltby Add a known issues section relating to issues with the open source repos...
bmaltby authored
1024
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
1025 Documentation
1026 =============
1027
1028 Full documentation for the Turbulenz Engine can be found at `<http://docs.turbulenz.com/index.html>`__
1029
1030 This documentation is built from the source restructured text in the docs/source folder of the repository, the latest
1031 version online is maintained from the latest release tag in the repository. If you wish to build up to date
1032 documentation follow the setup guide and the run the ``manage.py docs`` command, this will generate html docs in the
1033 build/docs/html folder.
1034
1035
e0dc1ae Blake Maltby Add a known issues section relating to issues with the open source repos...
bmaltby authored
1036 Known Issues
1037 ============
1038
1039 The following known issues exist with using the open source repository version of the Turbulenz Engine,
1040 additional known issues also existing in the SDK releases of the engine can be found here
1041 `<http://docs.turbulenz.com/known_issues/index.html>`__
1042
1043 * The application and JavaScript build process will currently fail if the repository is cloned to a path with
1044 spaces in it.
1045
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
1046
1047 Licensing
1048 =========
1049
cdbfa71 Blake Maltby Change README links to relative urls
bmaltby authored
1050 The Turbulenz Engine is licensed under the `MIT license <LICENSE>`__
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
1051
1052
1053 Contributing
1054 ============
1055
cdbfa71 Blake Maltby Change README links to relative urls
bmaltby authored
1056 Our contributors are listed `here <docs/source/contributors.rst>`__
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
1057
1058 Contributions are always encouraged whether they are small documentation tweaks, bug fixes or suggestions for larger
1059 changes. You can check the `issues <http://github.com/turbulenz/turbulenz_engine/issues>`__ or `discussion forums
1060 <https://groups.google.com/group/turbulenz-engine-users>`_ first to see if anybody else is undertaking similar changes.
1061
1062 If you'd like to contribute any changes simply fork the project on Github and send us a pull request or send a Git
1063 patch to the discussion forums detailing the proposed changes. If accepted we'll add you to the list of contributors.
1064
1065 We include a .pylintrc file in the repository which allows you to check your code conforms to our standards. Our
1066 documentation is built from restructured text sources in the docs folder so please consider how your changes may affect
1067 the documentation.
1068
1069 Note: by contributing code to the Turbulenz Engine project in any form, including sending a pull request via Github,
1070 a code fragment or patch via private email or public discussion groups, you agree to release your code under the
cdbfa71 Blake Maltby Change README links to relative urls
bmaltby authored
1071 terms of the MIT license that you can find in the `LICENSE <LICENSE>`__ file included in the source distribution.
fe22ffc Blake Maltby Initial commit for Open Source release
bmaltby authored
1072
1073
1074 Links
1075 =====
1076
1077 | Turbulenz game site - `turbulenz.com <https://turbulenz.com>`__
1078 | Turbulenz developer service and SDK download - `hub.turbulenz.com <https://hub.turbulenz.com>`__
1079 | Documentation for this module and the SDK - `docs.turbulenz.com <http://docs.turbulenz.com>`__
1080 | About Turbulenz - `biz.turbulenz.com <http://biz.turbulenz.com>`__
Something went wrong with that request. Please try again.