CTrollaball is both a demonstration platform showcasing the CloudTurbine-based Mixed-Reality interface as well as a test-bed for developing this interface.  CloudTurbine provides an excellent vehicle for interjecting real-world data into Virtual Reality applications.  Originally based on the Unity tutorial Roll a Ball game, CTrollaball is an extensible platform in which virtual and real-world players can interact, facilitated by CloudTurbine stream-sharing features which support multiple networked players, in-game “instant replay” and observer mode, remote browser monitoring, and game archival/playback.  It has been compiled under Unity 2018 for Windows and Mac OS platforms.

CTrollaball is open source software, available on GitHub and released under the permissive Apache 2.0 license.  This post provides background information needed to participate in CTrollaball development.  A related post describes how to setup and play CTrollaball.

The general development steps are:

  • Setup/install software requirements (Unity IDE, GitHub account, Git client and Git LFS package)
  • Follow development procedures:
    • Fork the CTrollaball repository to your GitHub account
    • Clone your forked CTrollaball repository to your local machine
    • Setup Git remote
    • Open and build CTrollaball in the Unity IDE
    • Optionally issue Pull Requests for enhancements you would like to contribute
    • Keep your CTrollaball repository up-to-date

These steps are described in detail below. Once the software requirements are in place, you’ll be able to setup the development environment and build CTrollaball in about a half hour by following these instructions.

Requirements for CTrollaball development

  • Unity IDE
  • GitHub account
  • local Git client (the steps below use Git terminal commands, but tools such as GitHub Desktop can also be used for at least some of the steps)
  • Git LFS package must be installed with the local Git client (see notes below)

Git LFS

The CTrollaball project include the “GitHub for Unity” package, which uses Git Large File Storage (Git LFS) to store text pointers to binary resources (e.g., “png” files).  Instead of storing those binary files directly in the GitHub repository, a small text file containing a pointer to the resource is stored.  Your local Git client must have Git LFS installed prior to cloning the CTrollaball GitHub repository, otherwise you will only get the text pointer files instead of the de-referenced binary resource files.

As an example of a binary file stored using Git LFS, go to https://github.com/cycronix/CTrollaball/blob/master/Assets/Textures/gear.png. Notice the Stored with Git LFS indicated above the image window.

For information on installing Git LFS, see https://help.github.com/articles/installing-git-large-file-storage.  Select the platform of interest (Mac/Windows/Linux) to see the corresponding installation instructions.  For installation on Mac or Linux, note that you may need to use “sudo” when running “./install.sh”.  After installation, bring up a new Terminal/Command window and try running “git lfs install” to make sure installation was successful.

Installation and development procedures

CTrollaball is hosted under the Cycronix GitHub account at https://github.com/cycronix/CTrollaball.  You will “fork” the official repository to your own GitHub account and then “clone” it to your local machine.  Suggested CTrollaball changes can be issued in the form of a “Pull Request” from your forked repository.  (A similar process is explained for third-party CloudTurbine developers at http://www.cloudturbine.com/using-github-and-git/).

  1. Fork the Cycronix CTrollaball repository (https://github.com/cycronix/CTrollaball) to your own GitHub account; this is done via the GitHub web interface.
  2. Clone the forked repo located at your GitHub account to a local directory on your computer.  For example, I use the following to clone my forked repo to a local folder called “CTrollaball”:
  3. Go into your new local clone directory and add a Git “remote” that points to the upstream repo (i.e., that points to the “official” CTrollaball repo under the Cycronix GitHub account):
  4. Launch the Unity development environment; the official Cycronix CTrollaball project uses Unity 2018.3.0f2 (use that version for easiest collaboration). In Unity:
    1. Open the CTrollaball project.
    2. In the Project window of the Unity Editor, double-click on Assets/_Scenes/CTrollaball to load the CTrollaball scene.
    3. To edit a script file, double-click the desired file under Assets/Scripts in the Project window; this will launch a separate IDE (Visual Studio on Windows machines).
    4. To build your project: select “Build Settings…” from the File menu; make sure the “Target Platform” and “Architecture” are set as desired and click the Build button. Unity will prompt you to enter a location for the executable.
  5. Use the following steps to commit changes from your local clone to the official CTrollaball repo under the Cycronix GitHub account. The add/commit/push commands described here are accomplished using a Git client, such as the “GitHub for Unity” plugin (https://unity.github.com/) which is pre-installed in the CTrollaball project (located in the Assets/Plugins/GitHub folder); this tool provides a Git UI integrated in Unity.
    1. “add” changed files to stage them for local commit
    2. “commit” the changed files to your local repo
    3. “push” changes from your local repo to your remote fork (located under your GitHub account)
    4. At GitHub, issue a “Pull Request” from your forked CTrollaball project to request changes be integrated into the official CTrollaball repository. While the first 3 steps mentioned above can be done using your Git command line client or via “GitHub for Unity” (in the Unity IDE), this last step must be issued from the GitHub web interface.
  6. When other changes (i.e. not ones that you pushed) have been committed to the official CTrollaball repo, you may want to update the fork under your GitHub account as well as your local clone:
    1. Fetch changes from the “upstream” source (i.e., the official CTrollaball repo) to your local “upstream/master” branch:
    2. Switch to the “master” branch of your local repo:
    3. Merge changes from your “upstream/master” branch with your “master” branch:
    4. Push changes from “master” branch to the “master” branch of the forked repo under your GitHub account: