Overview

Rainbow

Rainbow is a scriptable, cross-platform, 2D game engine written in C++.

Copyright © 2010-14 Bifrost Entertainment AS and Tommy Nguyen.

Distributed under the MIT License (see accompanying file LICENSE or copy at http://opensource.org/licenses/MIT). Licenses for third-party software can be found in file THIRDPARTY.

Features

Platforms

  • Android
  • iOS
  • Linux
  • Mac OS X
  • Windows

Audio

Rainbow integrates FMOD Studio. Its API is available at the scripting layer.

A custom solution based on OpenAL and OpenSL ES (Android-only) is also available, with support for the following formats:

Graphics

Uses mostly OpenGL ES 2.0 compatible features:

  • Shaders
  • Sprites-based rendering with implicit batching
  • Text rendering (supports TrueType and OpenType through FreeType)
  • Texture atlas (PNG and PVRTC)

Input

  • Accelerometer (Android and iOS)
  • Keyboard and mouse (Linux/Mac OS X/Windows)
  • Microphone (Android and iOS)
  • Touch (Android and iOS)

Others

  • Lua scripting language with debugging console and hot reloading
  • Physics (Box2D)
  • Scene graph
  • TestFlight integration

Structure

  • build - Contains compilation-related files.
  • demos - Demos.
  • doc - Documentation.
  • lib - Libraries necessary to compile Rainbow.
  • lua - Convenience libraries for implementing apps or games.
  • src - Rainbow source files.
  • tests - Rainbow unit tests.
  • tools - Tools such as the build script.

Building

First of all, clone the repository:

$ git clone --recursive https://bitbucket.org/tido/rainbow.git

The repository only includes some of the libraries required to build Rainbow. The remaining requisites is listed on each platform's section. They must be installed or copied into the repository before you can start building Rainbow.

Easiest way to build Rainbow is to use the provided build scripts:

$ mkdir rainbow-build
$ cd rainbow-build
$ /path/to/rainbow/tools/build.sh [platform] [options]

Run build.sh help to get an overview of options and configurations. platform can be omitted if compiling a native build (i.e. not cross-compiling).

If you have problems running build.sh, please make sure it has execution permission:

$ chmod +x /path/to/rainbow/tools/build.sh

Windows-users have to use build.bat instead. For iOS builds, see the corresponding section.

Building with FMOD Studio

The default audio backend for desktop builds is currently FMOD Studio. Download and extract/install it, then copy the header files to rainbow/lib/FMOD/inc/ and the libraries to rainbow/lib/FMOD/lib/.

If you don't want to use FMOD Studio, run build.sh with -DUSE_FMOD_STUDIO=0.

Android

Once you've installed both, open rainbow/tools/build-android.sh and change NDK_HOME to point at the NDK. The build script will create a debuggable and installable APK but is currently only available on Linux/Mac OS X. You can still compile for Android on Windows, it just requires some manual labour.

Follow the steps outlined earlier and specify android for platform:

$ /path/to/rainbow/tools/build.sh android [options]

iOS

Use the provided Xcode project under rainbow/build/xcode4/.

Linux (and cross-compiling for Windows)

You can install most of these using your favourite package manager. For SDL, download the source code and extract its content to rainbow/lib/SDL/.

Clang is the default compiler but you can use GCC, or any other compiler for that matter, by prefixing CC=gcc CXX=g++.

Windows builds can be built using MinGW or MinGW-w64 by issuing windows as platform. However, this method hasn't been maintained in quite some time and may no longer work.

Mac OS X

CMake and Ogg Vorbis can be installed through Homebrew or MacPorts. Download SDL source code and extract its content to rainbow/lib/SDL/. Xcode's Command Line Tools must be installed.

Windows

Download OpenAL Soft and place the files under rainbow\build\windows\include\ and rainbow\build\windows\lib\. Finally, download SDL development libraries and move its content to rainbow\lib\SDL\.

Alternatively, see "Linux" for cross-compilation.

Learning

See documentation under doc, and the demos under demos. Note: In order to run a demo, you'll need to copy some files into the folder of the demo you want to run:

  • lua/* (you may not need all but it's easier to just copy everything)
  • src/Graphics/Shaders (copy the folder, not needed for Android/iOS)

Some demos may use resources that (unfortunately) cannot be distributed with Rainbow.

Once you've copied all the necessary files, run rainbow inside the folder:

$ cd /path/to/demo
$ rainbow

Or with the path as argument:

$ rainbow /path/to/demo