For each level in your game there is a lot to think about, not just the gameplay itself, but level selection, unlocking, data, scoring, win conditions and more. Game Framework provides the framework for managing all these details.

Level functionality is based upon GameItem and it’s related classes and so it inherits all features such as the ability to use in app purchase, unlocking, selection screens, saving of information and so forth. It is worth reviewing the Game Structure overview page first as this page will focus on additions and differences from those documented there.


You can setup levels automatically through GameManager or manually through scripting. When using GameManager, you specify the number of levels that you want and then the Levels will then be initialised based upon localisation strings and resource files as documented in the information about GameItems.


Level Setup Options

You can then access all levels through the GameItemManager available through GameManager.Instance.Levels.


The LevelManager component should be added to your game scene and holds information about run time state of the level including such things as whether is is started, running time and other options. From code you can access LevelManager through LevelManager.Instance.


LevelManager gives you a number of optional conditions for ending the level in either a win or lose state that you can enable and which are then automatically handled. You can also call the methods on LevelManager directly such as LevelManager.Instance.GameOver(bool isWon) to end the game based upon your own logic, or the LevelStarted() and LevelFinished() methods to set status.

Object Model

The Level class represents an instance of a level and inherits from GameItem exposing all of the same properties and methods. Level overrides IdentifierBase to ‘Level’ and IdentifierBasePrefs to ‘L’ to distinguish it from other GameItems. Level also contains a number of additional properties including:

  • Stars Won Support
    • StarTotalCount – A total count of stars that can be won
    • StarsWon – A bitmask of stars won (automatically saved across plays). Generates a message of type StarsWonMessage when changed
    • StarsWonCount – The total stars that have been won for this level
    • Star1Target – A value for holding a target for the first star
    • Star2Target – A value for holding a target for the first star
    • Star3Target – A value for holding a target for the first star
    • Star4Target – A value for holding a target for the first star
    • Progress – A field for recording the current progress
    • ProgressBest – The best progress (automatically saved across plays)
    • TimeTarget – A target time
    • TimeBest – A field for recording the best time (automatically saved across plays)
    • ScoreTarget – A target score
  • Lives – The number of lives that the current player has. Generates a message of type LivesChangedMessage when changed
  • Health – The players current health in the range 0..1. Generates a message of type HealthChangedMessage when changed
  • IsGameWon – Whether the player has won the whole game. Generates a message of type GameWonMessage when changed

There are also several new methods on Level available for working with the above.

Configuration files should be placed into the Resources\Level\ folder with the name Level_<ID> where ID corresponds to the level’s ID.

In addition Level sends out custom messages when the score, highscore and coins change so that you can easily subscribe to changes of these values for the player. These messages are LevelScoreChangedMessage, LevelHighScoreChangedMessage and LevelCoinsChangedMessage respectively.

Level Selection

Non-Linear Layout

A Level Selection Screen

CreateLevelButtons and LevelButton behave in a similar to their base components for laying out the character selection display. LevelButton additionally handles display of Stars and listens for messages of type LevelPurchasedMessage to update the display automatically if they are purchased through in app purchasing. To display stars the button prefab should have a gameobject named ‘StarsWon’ that has child gameobjects ‘StarxWon’ and ‘StarxNotWon’ that represent the different won / not won display and where x is the star number e.g. ‘1’

The selected Level is always available through the GameManager.Instance.Levels.Selected property or through LevelManager is that is added to the scene.

Level Display

The selected Level is available through the GameManager.Instance.Level property and so through this you can access things such as the currently selected levels name, description, stars won, extension data etc.

The ShowLevelInfo component can be added to a gameobject with a UI Text component to automatically update the Text display with customisable information about the currently selected level.


Level Coins and Stars

Coins and Score

The ShowLevelCoins, ShowLevelScore and ShowLevelHighScore components provide ways of displaying the current levels coins, score and high score respectively. These components make use of the ShowValueAnimatedMessaging abstract component for automatically updating the display when updates occur. Updates can be aggregated in variety of different ways and any changes animated using a custom or predefined animation. (see the Animation\ValueChanges demo in the extras bundle)


The EnableBasedUponNumberOfStarsWon component allows you to shows one of two gameobjects based upon the stars the player has won and a property indicating which star the component represents. You could create multiple gameobjects for each star and use this to selectively enable child gameobjects representing whether the star has been won or not. It will also automatically react to changes. Instead of manually creating multiple such gameobjects for each life you could instead use the CreateStarIcons component to do this automatically based upon a prefab that represents what you want created for each available life and either the global or a specified life count.



Prefabs associated with Levels can be setup and retrieved as discussed in the description on GameItem.

The Level specific InstantiateLevelPrefab component is an implementation of InstantiatePrefab that will use prefabs from the currently selected Level.


Prefabs associated with Levels can be setup and retrieved as discussed in the description on GameItem.

The Level specific SetImageToLevelSprite and SetSpriteRendererToLevelSprite components behave in a similar to their base components for setting sprites from the currently selected Level.

Making Changes

You can modify these values directly through scripting. In addition there are various components that you can use for displaying and working with the different properties.

StarsWonhandlerCoins and StarsWonHandlerScore allow for automatically setting stars that have been won based upon the levels StarTarget values for either level coins or level score. You can also chose to explicitely specify values if you so wish.

In addition you can use the health collider for changing these values automatically based upon Physics collisions.


Like all GameItems you can have Levels in a locked status. Unlocking can be done through code, by collecting coins and adding a UI button with the UnlockLevelButton attached or through in app purchase.

Game Over

When a game is finished (either won or lost) using LevelManager then the standard GameOver dialog will be displayed. This can be configured to show different properties, settings and features. See the UI documentation for further details.


Game Over Dialog

Cheat Functions

Using the Cheat Functions window (Window Menu | Game Framework | Cheat Functions Window) you can manipulate the current level to aid with testing of your game.

See also

If you have any thoughts or suggestions on improvements or additions to the level features then please let us know!