Welcome to the Turbulenz Hub User Guide! The aim of this guide is to show you how to use the Turbulenz Hub to upload, test and demo your game to team members, testers and other third parties around the world. This guide will take you through how to configure your game to be ‘Hub ready‘ and demonstrate the process of deploying your game to Turbulenz’ live staging server known as the ‘Hub’. The guide is structured around the processes that you are likely to need to be performing when using the Hub on a daily basis. It also includes a description of the controls available and a troubleshooter to help you avoid common pitfalls when getting started.
Here is a summary of the topics covered in each section:
Find out what the Hub is all about: An integral part of the Turbulenz publishing process; the Hub provides the stepping stone enabling you to get your content hosted online. This section describes the features the technology provides, at what stage of development to start using it and an overview of where it fits in with other Turbulenz technologies.
I need to perform a certain Hub task: You are using the Hub as an admin, developer, tester and need to configure/run a game you have access to. These step-by-step guides will help you to manage your project and account and find out information on how they are configured.
I can’t get it to work: If you are encountering problems when using the Hub, check out this section to see if you can find a solution to your problem. It covers the possible pitfalls you might encounter and offers you suggestions to help you get going again.
Some parts of this guide (e.g. How do I ... prepare my project for the Hub?) may require you to have an understanding how your application/game is structured including build processes and tools. The majority of this guide is intended for users of the Hub service, including third parties and will not require knowledge of development processes as a whole.
This section describes the Turbulenz technology known as the ‘Hub’, what its purpose is and how you can use it to make online games.
Read This Section
The Turbulenz Hub or ‘Hub’ is one of a number of products and services provided by Turbulenz to assist in developing and publishing games online with Turbulenz. Essentially it is a staging environment and management tool to give selected users access to your uploaded game and allowing them to test, demonstrate and evaluate versions of your game in a ‘real world’ scenario. The diagram above shows where the Hub is positioned within the family of Turbulenz products.
The Hub provides developers with:
Here is a summary of the process of using the Hub:
How does the Hub work with other Turbulenz products?
Here is a quick overview of the other Turbulenz services:
Turbulenz Local Server: Available as part of the Turbulenz SDK. The local development server, a combined package of APIs and web server, can be run on an individual’s machine or local company network allowing games to be developed and tested in-house. Turbulenz game site: (Represented by the red cloud) - The Turbulenz website, where users can log-on, play games, interact with other users and share their gaming experience.
The Hub exists as a stage between the local server and the game site. You can ‘Deploy’ from the local server to the Hub and ‘Publish’ from the Hub to the game site.
Deploying works by:
Version numbers need to be url-safe. Try a standard form such as 0.1.0 or a date 2007-03-13.
The details of the publishing process will be made available in the near future. Turbulenz intends to provide a mechanism for technically approving content, self-age rating, etc.
Who is the Hub intended for?
The Hub is the central location for accessing your game in development prior to releasing to the public. The projects that are hosted on the Hub only allow access to trusted parties for that have a role to play in developing the game. All user’s on the Hub can be invited to a take a role on a project by the owner. The role categories are as follows:
The overall administrators of a project (similar abilities as the project owner). They have overall responsibility of configuring and submitting the project for publishing. It is advised that the group of administrators is kept small. Most day-to-day activities can be done with a developer account.
Members of the main development team. They could be part of a central team or remote developers who require the ability to contribute to the project. They have the ability to maintain versions of the project, but are unable to add team members.
Testers is the group of users that require ‘read only’ access to the project. They can play all versions of the game without the management responsibilities. Their role on a project allows them to access uploaded versions to test and provide feedback. A useful role for remote testing teams; they require only access to the Hub to playtest a project version. They will require the Turbulenz Engine if they intend to test plugin configurations and a canvas (2D/3D) compatible browser to test canvas configurations.
Guests are the subset of people that you want to be able to allow pre-release access to your game, prior to launch. This could be to provide feedback, trial gameplay or just so they can see what you’ve been working on! Guests can be given access to specific versions and their access can be retracted whenever required.
Invites to a project can be made by email, but the recipient needs to have an account on the Hub to join the project. For more information see the How do I? section.
Info tab: Look at some basic information about your project.
Versions tab: Control and run any version uploaded to your project.
Feed tab: View the project activity.
Play Feed tab: View who played any of the versions on the Hub and for how long.
Members tab: View the project members and their roles.
Metrics tab: View and export game site metrics for your project at a game, version and test variation level.
Publish tab: Publish a teaser or project version to the game site, and set preview and default versions.
Preview tab: View and edit the list of game site users who will have access to the published game preview.
A/B Testing tab: Create and monitor A/B tests for your published game.
Feed Moderation tab: Delete flagged game feed posts, or clear the flag.
Add Member tab: Add a member to your Hub project.
Edit tab: Edit project information for the Hub and the game site.
Settings tab: Edit project settings for the Hub.
This section provides step-by-step walkthroughs designed to guide you through the process of performing certain tasks on the Hub. It starts with the basics of Hub usage and describes some of the more complex tasks later on. It is important to be aware that this information will be updated in the future. Please check back to find out if the steps are any different in newer releases.
Read This Section
In order to ‘Deploy’ your project on the Hub you will require:
The first stage of deployment is to make sure you are able to run your game on the local server. This will require you to configure the settings of your local project (the settings will be used in the deployment to the Hub). You will need to complete these steps locally:
Be aware that a slug that you use locally might not be available on the Hub e.g. sampleapp. Although you can select any unused slug locally, you should never rely on the naming of your slug in the running of your game. This slug must be unique and you must not use slugs that represent copyrighted names of other games.
Eventually you may want to include content for the Turbulenz Services such as leaderboards and badges. The deploy files is where you need to add this information to ensure they are uploaded to the Hub. See badges and leaderboards for an example of what to include.
Once you have created an account you can create new projects, be invited to existing ones and manage your account settings. Follow these steps to create an account:
On the Hub, a project represents an application or game that uses Turbulenz Technology that you are working on. The project encompasses the different versions of the game you are working on. Whether you are just using a working title or you already have the product name in mind, a project provides the flexibility for you to edit your game during the development process, while keeping a history of the activity and previous versions to refer back to.
To start a new project as an owner:
Log onto the Hub, https://hub.turbulenz.com
Select ‘New Project’.
You will be asked to provide the basic details of the project:
Title: This the name of the application/game and is what users will eventually see when you come to publish. For example “Robot Pirate Space Ducks”. Slug: This is part of the URL of your application/game on the site, that allows you to easily access your game. This string should be short, recognizable and use a limited set of characters. For example “rps-ducks”. This slug must be unique and you must not use slugs that represent copyrighted names of other games.
Your project has now been created. You can navigate the info, feed, manage members and configuration.
Assuming you have performed the following steps, you are now able to deploy to a project:
To deploy follow these steps:
Start the local server on a machine with access to your prepared game.
Select the project on local server to deploy.
Press the ‘Deploy to Hub’ button.
Sign in using your username and password.
You must use your username to log into your account currently. In the future you will be able to use your email instead.
In the following widget select the project on the Hub that you want to deploy to.
Press start to begin the deployment. This could initially take a few minutes for large projects as the file data is processed. The progress bar shows when the data is being uploaded. When the deployment is successful you will get a message popup to inform you.
The local server inspects your files and caches them during deployment. If the files have not changed since the last deployment then the upload process avoids re-sending the data. This saves bandwidth and should improve the speed of uploading new versions with common data in the future. This is especially true for any asset data.
To test the deployment, navigate to https://hub.turbulenz.com and login.
On the project you should be able to see your new version in the Versions tab.
Click on the ‘Play Canvas Mode’ () or ‘Play Plugin Mode’ () button to try your new version. The game should start immediately in a widget. If your game doesn’t play or the screen remains blank, see the Troubleshooting section.
You can also deploy a local version to a project on the Hub using the deploygame tool.
If you own a project or are a member of an existing project, you can invite other Hub users to take on roles within your project.
To do this:
See the previous section for a description of the possible roles.
To add a member follow these steps:
To do this:
You can request Turbulenz to approve your project to allow you to self-publish, or we can publish requested versions for you. You should only request publishing for versions that are ready for general public to see.
To publish, follow these steps:
If you do not see the version you want to publish listed, make sure it uploaded without any warnings. If there were any warnings you should see an Upload Infos icon next to the version in the Versions tab. Clicking on the Upload Infos icon should expand to list any errors and warnings.
If the button is disabled and you feel the version you’re publishing is ready for the game site, request Turbulenz to publish it for you.
To do this:
To set up the Preview, follow these steps:
When setting a new version as the Preview, if another version was already set up as the Preview then the new version will replace the existing as the Preview. Alternatively you can first unset your existing Preview, update your list of Preview members to be correct, and then set the new Preview.
To do this:
To release the game, follow these steps:
This will make the game visible to all Turbulenz game site users.
When setting a new version as the Default, if another version was already set up as the Default then the new version will replace the existing as the Default.
Once you have set your game as the active default, you may have to wait a minimum of 10 minutes before it becomes live on the site for users. This delay is due to the caching of content on the Turbulenz servers. It shouldn’t take long before all the content servers are updated with the correct version. If you are still unable to see your published game immediately, try clearing your browser’s cache or navigate to the site with a different browser. If you are still failing to see your default version after 1 hour, please contact Turbulenz.
To do this:
If you have not marked your game as multiplayer capable on the local server, the ‘Multiplayer Sessions’ icon will not be shown for your game.
If you are a Developer or Administrator you may delete sessions from the hub. This allows you to clean up any stale sessions that may be generated during testing.
It is possible to join a multiplayer session with any version of the game currently on the hub. This allows you to do compatibility testing between different versions of the game for example for A / B testing.
To do this:
The metrics displayed for a game on the Hub are gathered from the game site.
To view the metrics, follow these steps:
Metrics for published versions and A/B tests can also be viewed from the Publish tab and A/B Testing tab respectively, by clicking on the Metrics icon next to the version or test you want to see the metrics for.
To do this:
If you want to process the raw events beyond what the metrics provide, you can export events and anonymized user information.
To view them, use the exportevents tool in the SDK.
To do this:
To edit the project metadata, follow these steps:
When you have a published game, the changes made in the Edit tab are applied to both the Hub and the game site.
Changing the slug for a published game is a bad idea and should only be resorted to in extreme circumstances. Changing it will break any bookmarks users have kept and external links posted to the game page. It may also cause problems for users in the middle of a game.
To do this:
To run an A/B test, follow these steps:
Make sure to read up on A/B testing before performing any tests. A/B tests can be a powerful tool for iterating and improving a game. They can also be very destructive if used without fully understanding how to run them and analyze their results.
If a version of your game has saved some userdata then it will have a button () that you can open to see a list of userdata ‘files’. You can delete individual files, or all your userdata using the buttons provided. If you use userdata to keep a record of what badges have been awarded, or leaderboard details, make sure you also reset those along with deleting the userdata.
This feature should only be used to assist testing e.g. forcing a game to restart from scratch that otherwise cannot be restarted.
Depending on the size of the data, it will be stored (in order of increasing size) : in the database (DB), compressed in the database (DB(compressed)) or on Amazon S3 (S3).
Whenever the main file is selected to be a TZJS, deploying to the Hub results in the TZJS file being converted to a Turbulenz Object (TZO) file. Playing the game on the Hub then runs the TZO and not the uploaded TZJS. This conversion only takes place on the Hub and should not affect your local files.
One of the main advantages of TZO is encrypted communication between the game and the server. Secure HTTP connections only avoid eavesdropping by external parties, but do not avoid monitoring by someone controlling the browser. The game can request an additional encryption layer between the game and the server.
Using TZO also allows code hiding via encryption. Developers are often concerned about intellectual property and it is difficult to keep code from being seen or even understood/copied/modified by a user once the code is served on their machine. Encrypting the code does not offer as much security as often expected since the code and keys to decrypt that code also reside at some point on the user’s machine. It does however hide the code from the average user and, if implemented well, also from inexperienced cheaters. As a side benefit, it also keeps the average user from being curious when they see the code and from thinking how they could use it to their advantage (leading to cheating).
The main file can also be a canvas version of your game which is expected to be a release build and have the suffix .canvas.js. This will be the canvas mode equivalent of the TZJS file, but does not get converted into another format when uploaded. HTML5 is still a developing technology and though we have added support on the Hub to let you deploy and play canvas versions of your games, there is still no reasonable solution to the anti-cheat issue. It is therefore advised that any release builds of your game in canvas mode be compacted (see maketzjs for details). At a later stage we will address anti-cheat for canvas mode and improve anti-cheat for the plugin mode as well.
A HTML file as main is meant only for development purposes. Publishing a game therefore requires a game to have been deployed with a TZJS and/or a canvas file as main. Ideally you should publish with both the plugin and the canvas main specified to support a maximum number of browsers.
For every game on the game site, Turbulenz gathers a set of metrics that can be viewed from the Hub. Below is a list of the metrics currently gathered. To explain the behaviour of metrics in a simple way, let’s assume these metrics were gathered for Dec 31.
Total Play Count: This is the total number of times the Play button was clicked (includes page refresh on the play page) on Dec 31.
Average Play Duration (secs): The Total Play Duration (secs) divided by the Total Play Count, both for Dec 31.
Total Play Duration (secs): This is the total play time in seconds no Dec 31. The duration is calculated when the session completes so average play time should be tracked using (Total Duration / Sessions Completed) and not (Total Duration / Play Count).
The is NOT a true indicator of duration as people often leave the game idle on the menu screen and hibernate/sleep or just start doing other work in a separate tab. Games are advised to track some form of play duration from within the game.
Play Duration Sum of Squares: This is the sum of squares of each individual value aggregated for the Total Play Duration. This can be used to calculate the standard deviation for the average play duration. This metric is not displayed but included in the exported JSON or CSV.
Total Sessions Completed: This is the number of sessions that were completed successfully on Dec 31. This number is incremented when the Stop button in clicked, the page navigated away from, or the browser closed. The difference in number between this and the play count is the number of sessions that crashes along with sessions that were still running at the time of gathering the metric. For sessions that were still running, whenever the session does complete, it will go back and update the metric for Dec 31. Over a period of time this number should be fairly close to the Play Count, otherwise indicates frequent crashes.
Daily Unique Players: This is the unique number of people that started the game on Dec 31.
Weekly Unique Players: This is the unique number of people that started the game during Dec 25 to Dec 31 (7 days).
Monthly Unique Players: This is the unique number of people that started the game during Dec 02 to Dec 31 (30 days).
Engagement Ratio (Weekly): Daily Unique Players divided by Weekly Unique Players.
Engagement Ratio (Monthly): Daily Unique Players divided by Monthly Unique Players.
Daily User Retention: This indicates retention rate (ranging 0-1) calculated by: (Intersection length of unique players for the dates Dec 30 and Dec 31) / (Number of unique players on Dec 30).
Weekly User Retention: This indicates retention rate (ranging 0-1) calculated by: (Intersection length of unique players for the weeks Dec 18 to Dec 24 and Dec 25 to Dec 31) / (Number of unique players during Dec 18 to Dec 24).
Monthly User Retention: This indicates retention rate (ranging 0-1) calculated by: (Intersection length of unique players for the ‘months’ Nov 02 to Dec 01 and Dec 02 to Dec 31) / (Number of unique players during Nov 02 to Dec 02).
Users: Total number of unique users that have played the game up to Dec 31.
Cumulative Daily Retention: Game activation on day 0 has a retention of 1, subsequent days show the proportion of players from the previous day that also played on this day, up to the total number of days the game has been active.
Cumulative Weekly Retention: Game activation on week 0 has a retention of 1, subsequent weeks show the proportion of players from the previous week that also played on this week, up to the total number of weeks the game has been active.
Cumulative Monthly Retention: Game activation on month 0 has a retention of 1, subsequent months show the proportion of players from the previous month that also played on this month, up to the total number of months the game has been active.
Feed Add Count: This is the number of comments posted on the game feed on Dec 31.
Feed Reply Count: This is the number of replies posted on the game feed Dec 31.
Followed Count: This is the number of times the Follow button was clicked for the game on Dec 31. This does not take into account the automatic following of a game when a user first plays the game. This number may be falsely increased by a user by constant switching between Follow/Unfollow.
Unfollowed Count: This is the number of times the Unfollow button was clicked for the game on Dec 31. This number may be falsely increased by a user by constant switching between Follow/Unfollow.
Turbulenz also allows you to track custom events you define within your game.
Custom Metrics: For each unique event key the game uses, this is calculated in three parts. For every occurrence (with the specified event key) of the custom metric the game sends on Dec 31:
EventKey : Count: This is the number of times the event took place (calculated as the number of requests made to update the specified key).
EventKey : Total Value: This is the total value (aggregate) for each time the event took place. The average value is calculated as (Total Value / Count)
EventKey : Value Sum of Squares: This is the sum of squares of each individual value aggregated for the Total Value. This can be used to calculate the standard deviation for the average value. This metric is not displayed but included in the exported JSON or CSV.
Custom events allow tracking numbers and arrays of numbers as values, but metrics are only tracked for events with numbers as values.
The custom metrics, along with the feed and follow metrics, are always up-to-date when viewed on the Hub. The remaining metrics are currently updated for a 24-hour period after UTC midnight.
To carry out useful A/B testing, you should know what pitfalls to avoid and how to best interpret the data. It would be a good idea to read up on A/B testing before running your first test.
Unlike traditional websites, where A/B testing goals can be as simple to track as clicks on a certain link, it is much more complex setting up flexible goals within games. Turbulenz only provides metrics gathered during the tests. It is up to the developer to determine when to terminate the test and which variation won. Developers can use custom events to track the behaviour they want to observe as their goal for the test.
Before running a real test, you should first carry out a Null Test, where the control and the variation are both the same version. Observing the data from this test and how closely each variation performs against the other, you should be able to get an idea of how big your sample size needs to be and for how long the test needs to run before you can consider a test to be valid. It is important to be confident in the result of a test. Often a follow-up test which is identical, should confirm if the results from the original test were accurate or just due to noise.
You may want to run tests quickly so that you are not running a poorly performing game for longer than you need to. However, there is a tradeoff between speed and certainty. The cost of doing A/B tests quickly is that you will make wrong decisions more frequently. That can be ok if mistakes are cheap.
When running a test, you need to keep in mind that as the number of variations tested simultaneously increases, to get useful results you either need to increase the sample size for the test or increase the duration the test is run for. Similarly, if you are measuring something that does not happen very often, it will take much longer to find the most effective variation.
You need to keep in mind that a test should never be run at the cost of user experience. You should always maintain gameplay balance between variations being tested so some users do not have an advantage over others. You also need to ensure that if your game supports a multiplayer mode, then variations should be compatible. This is because user distribution on tests is random and the user is not aware they are on a test. A user SHOULD NOT be put in a state where they are playing the same game as their friend but unable to join them for no apparent reason.
Simple examples of A/B tests that can be useful include things like:
A/B tests are most suitable for small iterative changes to continually improve a game. If you want to test bigger and breaking changes which would be incompatible with the released version of the game, you should use the Preview functionality. Preview will allow you to give selected game site users access to the new version of the game without affecting the already released version. Users added to a preview will be able to see both, the preview and the released versions of the game.
This section is broken down into an FAQ with answers to some common questions you might have about the technology. If you are looking for a solution to a particular issue, try the Helpful Hints section with suggestions of things to check before getting in contact with the Turbulenz team.
Read This Section
This section contains a list of frequently asked questions (FAQ) relating the use of the Hub. If you are trying to troubleshoot a problem, try checking this section before requesting support from Turbulenz.
|How do I get access to the Hub?:|
If you do not already have an account, you need to register at https://hub.turbulenz.com under ‘Registration’ and create an account. Once you have an account you can log in at https://hub.turbulenz.com, where you’ll see the projects you have created and any you have been invited to.
|Can I publish my game without the Hub?:|
Not to the Turbulenz game site. The Hub provides the infrastructure and services that are required to test in a live environment before distributing your game online. This service is to ensure that your game behaves the way you expect it to, before you put it in the hands of users. If you want to discuss the possibility of distributing your game from your own website, please contact Turbulenz directly.
|What are the requirements for deploying to the Hub?:|
Your project must:
Ideally you should deploy and publish with both the plugin and the canvas main specified.
It is not necessary to have unique filenames across versions of your game. Turbulenz file hosting services deal with the unique identification of assets across multiple versions of your project.
The requirements for the local server, Hub and game site are designed to be more relaxed at the early stages of development to allow you to explore the technology. As you come closer to publishing your title, you are encouraged to start using the services that Turbulenz services require. The level of requirements are as follows:
Turbulenz Local Server: Minimal - You can run your game similar to most webservers. Use of mapping tables, is recommended, not required. Hub: Moderate - Some APIs such as mapping tables are mandatory. Both debug and release versions are allowed. Turbulenz game site: Strict - Your game will be available directly to the public. The requirements focus on ensuring the quality of experience for the users.
These hints are to help you come un-stuck when using the Hub:
|My game won’t deploy from the local server to the Hub!:|
Try checking each of the following items:
|The ‘Deploy to Hub’ button is unavailable!:|
|I’ve uploaded my game to the Hub, but it doesn’t work when I try to play it!:|
This could be because any number of reasons from incorrect use of API, to path referencing issues. Start by making sure you check the following:
If all the other checks pass correctly and as a last resort before contacting Turbulenz for support, try find the answers to the following, which will help us solve your issue: