This project is a part of The SOOMLA Framework, which is a series of open source initiatives with a joint goal to help mobile game developers do more together. SOOMLA encourages better game design, economy modeling, social engagement, and faster development.

unity3d-levelup

unity3d-levelup is a library built for easily modeling game structure and user progression, and allows rapid protoyping using a standard and simplified model. It acts as sort of a 'blueprint' for the game, modeling worlds/levels, gates to levels, missions and rewards that can be completed and achieved. All this is backed by SOOMLA's core tools, and can be easily integrated with more SOOMLA modules, like unity3d-store for IAP, or unity3d-profile for social related functions.

unity3d-levelup is the implementation of the LevelUp module for Unity3d.

Contents

Model Overview

Generally, the SOOMLA sources contain detailed documentation on the different entities and how to use them, but here's a quick glance:

World / Level

A Level is pretty clear, and most games have them.
A simple example is an Angry Birds single level, where you need to knock out all the pigs.
It measures specific things, such as duration it takes to complete, and can be started and ended.

A World is a more general concept than a Level (a Level Is-a World), and can have innerWorlds to create hierarchies. Another example from Angry Birds is level pages and episodes, which contain the actual levels.

The Initial World is a container world for all worlds and levels in the game. We use the Initial World to intialize the LevelUp module.

Score

A Score is something which can be accumulated or measured within a World (or Level of course).
It can be incremented or decremented based on user actions, and recorded at the completion of the World / Level.

This, in turn, can later be applied to high scores or best times, or treated as collectibles that can be awarded upon completion.

Gate

A Gate is a closed portal from one World to the next. It can be unlocked in many different ways (according to Gate type), and can also be combined into a GatesList to build more complex Gates.

Mission/Challenge

A Mission is a single task a player can complete in a game, usually for a Reward.

A Challenge is a set of Missions that need to be completed, so it's a big Mission built out of several smaller Missions.

Reward

A Reward is some kind of perk or status a player can achieve in the game.
This can be either a badge, a virtual item from the game's economy (sword, coins etc.) or anything you can think of, really (unlocking game content or levels comes to mind).

Getting Started

NOTE: LevelUp depends on SOOMLA's other modules: Core, Store, and Profile. This document assumes that you are new to SOOMLA and have not worked with any of the other SOOMLA modules. If this is not the case, and you already have some or all of the other modules, please follow these directions only for the modules you are missing and of course, for the LevelUp module.

You can work with sources, or if you run deploy/create_deploys, it will create packages that you can use in your project.

On the menu bar click "Window -> Soomla -> Edit Settings" and change the value for "Soomla Secret" (also setup Public Key if you're building for Google Play):

Soomla Secret - is an encryption secret you provide that will be used to secure your data. (If you used versions before v1.5.2 this secret MUST be the same as Custom Secret)Choose the secret wisely. You can't change it after you launch your game!

Public Key - is the public key given to you from Google. (iOS doesn't have a public key).

Create your own Initial World which should contain all the 'blueprint' of the game (see Model Overview). Initialize LevelUp with the class you just created:

SoomlaLevelUp.Initialize (initialWorld);

Initialize LevelUp ONLY ONCE when your application loads.

Initialize LevelUp in the "Start()" function of a 'MonoBehaviour' and NOT in the "Awake()" function. SOOMLA has its own 'MonoBehaviour' and it needs to be "Awakened" before you initialize.

You'll need an event handler in order to be notified about LevelUp related events. refer to the Event Handling section for more information.

And that's it ! You have game architecture capabilities at your fingertips.

Using unit tests

To use SOOMLA unit tests in the Other Settings panel of the Player Settings, you will see the Scripting Define Symbols, enter the name “SOOMLA_TEST”. If you are using Unity version older 5.3.0, download NUnit and import to your project.

Integration with SOOMLA unity3d-store

Please follow the steps in unity3d-store for the Store part of the setup.
Then, you can use the store-related LevelUp classes, such as VirtualItemScore or VirtualItemReward or BalanceGate.

Integration with SOOMLA unity3d-profile

Please follow the steps in unity3d-profile for the Profile part of the setup.
Then, you can use the profile-related LevelUp classes, such as SocialLikeMission.

Event Handling

SOOMLA lets you subscribe to LevelUp events, get notified and implement your own application specific behavior to those events.

Your behavior is an addition to the default behavior implemented by SOOMLA. You don't replace SOOMLA's behavior.

The Events class is where all event go through. To handle various events, just add your specific behavior to the delegates in the Events class.

One thing you need to make sure is that you instantiate your EventHandler before LevelUp.So if you have:

private static Soomla.Example.ExampleEventHandler handler;

you'll need to do:

handler = new Soomla.Example.ExampleEventHandler();

before

Soomla.Levelup.SoomlaLevelUp.Initialize (initialWorld);

Debugging

If you want to see full debug messages from android-levelup and ios-levelup you just need to check the box that says "Debug Messages" in the SOOMLA Settings.
Unity debug messages will only be printed out if you build the project with Development Build checked.

Example Usages

Examples using virtual items are dependent on unity3d-store module, with proper SoomlaStore initialization and IStoreAssets definitions. See the unity3d-store integration section for more details.