Note
PLEASE NOTE: This is a developer preview of software that is still being actively developed. Please report any bugs to the turbulenz-engine-users Google Group.
The Turbulenz Developer Client is a native implementation of some low-level components of the Turbulenz HTML5 Engine, which allows Turbulenz games to run on mobile devices, even when the installed browsers do not fully support HTML5 and related standards.
This technology can be applied to deploy specific games to the various app stores, and integrate those games with the underlying platform services, such as payment, user notifications, etc. However, the primary role of the Developer Client is to allow developers to quickly test and iterate their Turbulenz games on Android and iOS devices during development.
The recommended way to launch Turbulenz applications on the Developer Client is to use the .tzjs file links on the local development server. See the Getting Started Guide for details of how to build your application code and data.
Note
The local development server may need to be upgraded to support mobile platforms. This can be done by running this command in the python env
easy_install -Z -U turbulenz_local
Note
On Android, the Developer Client does not create an icon in the Android Launcher. This is intentional, since it is intended to be run in response to opening URLs, either via the browser or through the Android SDK Tools.
Diagnostic and log output is available via the system logs, and we recommend that developers install the Android SDK so that they can examine the log and run other development tools.
The development client requires the following permissions:
You will need:
The following is also recommended:
This allows you to launch the client via script or command line from a PC connected to your android device. It also allows you to view the log output from the android client.
On Android, generic URLs to .tzjs files and .tzo files can be opened from the browser and run in the Turbulenz Engine client.
Note
Depending on the version of the development server you are running, the .tzjs link may be of the form
http://192.168.1.2:8070/#/play/samples/animation.tzjs
which the browser will NOT run in the Turbulenz client. If the client fails to launch, your local development server may be out of date. Try removing the ‘#/’ characters from the URL
http://192.168.1.2:8070/play/samples/animation.tzjs
Applications that have been deployed to the Turbulenz HUB can also be launched by clicking on the ‘Play on Android’ button from the Android browser. The client will ask for login details the first time you launch a game from the HUB.
Ensure that the Android SDK is installed correctly, and adb is available from the command line.
To view the system log (including the output from window.console.log)
adb logcat
Clear the system log
adb logcat -c
Launch a URL on the device
adb shell am start http://192.168.1.2:8070/play/samples/animation.tzjs
See the documentation for the adb command for more information and uses of the adb command.
Note
iOS does not permit applications to take advantage of JIT compilation, the technology responsible for significant performance gains when executing Javascript code. For this reason, developers may see a noticable difference in performance between the same game running on Android and iOS. Note that the performance of hardware rendering operations is not affected by this.
We recommend that developers targetting mobile platforms check the performance of their games on target devices early and often during development.
On iOS, the Developer Client is distributed as an Xcode project that developers can build using their own provisioning profiles, in order to run on their own devices. See the Apple Developer documentation and related articles for details.
When run via Xcode, the debug console shows all output from the engine, including the results of Javascript calls to window.console.log.
You will need:
The Developer Client Xcode project will build and run using the iOS simulator, included in Xcode. In order to run on iOS devices (recommended for performance measurement), you will need:
On iOS, the Developer Client is not able to intercept arbitrary URLs in the same way as on Android. By default, it is configured to open in response to URLs with the tblz and tblzs schemes. Internally, these are translated into http and https. The Turbulenz servers automatically generate URLs of the appropriate form when viewed from the iOS browser.
Note
At this time, games deployed to the HUB and Gamesite cannot be opened by the iOS client.
Run the Developer Client from Xcode to capture the log output into the debug console.
Several development options are available from the appropriate section of the iOS Settings menu, including a in-app development menu.
It is possible to hard-code URLs into the Developer Client (see the comments at the top of the file ViewController.mm in the Xcode project). When this is done, the hard-coded URL will be used whenever the app is run from Xcode or and launched via the Turbulenz Developer Client icon in the home screen. This allows developers to create standalone apps that wrap a specific game.
(The information here relates to features that are not currently available in production. This material is provided as reference for developers who are interested in enabling in-app purchases in their Turbulenz applications, via 3rd party app stores).
Applications that have been packaged for distribution on mobile app stores can make use of the same payment API as they woudl when running in the browser, and the engine automatically forwards requests for payment to the underlying system.
For example, when running on an Android device, if the user attempts to purchase an offering called ‘grenade-pack’, the engine will call the underlying Google Play APIs and attempt to initiate a transaction for a Google Play SKU called ‘grenade-pack’. If purchase is successful, a signed receipt is passed to the Turbulenz back-end, the receipt is securely validated, and the set of items owned by the user is updated appropriately.
This system requires that developers register the set of in-app purchases for the app they are intending to distribute, with the platform holders developer console. For example, in the case above, a developer wishing to publish an Android APK called ‘com.gamestudio.gameapp’ with an in-app purchase called ‘grenade-pack’ would be required to register that the ‘grenade-pack’ purchase for the ‘com.gamestudio.gameapp’ application, as well as specifying the ‘grenade-pack’ offering to the Turbulenz back end in the usual way.
The Turbulenz servers require a table that translates between Turbulenz offerings and SKUs or Products on the native platform. in the example above, the Google Play billing system does not allow hyphen characters, so developers might create a SKU called ‘grenade_pack’ and pass the appropriate map to the Turbulenz back end.
Note
The details of this mapping and how it is specified have not been finalized at this time. For now, names are translated automatically by replacing hyphens with underscore characters.
Developers should use SKU names with hyphens replaced by underscores, as in the note above.
Developers should use Product IDs similar to those on Android, and prefixed with the application bundle ID, as recommended by Apple. e.g. ‘grenade-pack’ in the example application ‘com.gamestudio.gameapp’ can be purchased as the product ‘com.gamestudio.gameapp.grenade_pack’ via the iOS AppStore.