Getting Started With Game Framework for Unity – Part 7 – GameItems, Lives, Health and Stars

Skill level: Beginner / Intermediate
Tutorial time: 15 minutes
Implementing in your projects: 5 minutes

Part 1 – The Basics, Audio, Settings and Localisation
Part 2 – Level Setup and Selection
Part 3 – Game Loop, Score and Coins
Part 4 – Unlocking and In App Purchase
Part 5 – Applying a Theme
Part 6 – Worlds and Resources
Part 7 – GameItems, Lives, Health and Stars
Part 8 – Messaging essentials
Part 9 – A Better Game

In this part of the tutorial we will take a closer look at what GameItems are before moving on to look at lives, health and stars. The below shows the goal for this part of the tutorial.


Game Items

Before moving on further, it is a good idea to understand further what GameItems are and how they can be used. The GameItem class forms the bases for several of the entities that we have already met including Player, World and Level. GameItem gives us some standard functionality that allows us to treat all derived classes in a standard manner including the fields that we have seen previously in the world and level configuration items in addition to diverse score related information (coins, score, …), unlock and IAP, per GameItem preferences through the GetSettingXXX() and SetSettingXXX() functions that are saved across restarts and more. The below figure shows how such preferences are stored and can be useful to help debug your game.


The ‘Prefs Editor’ asset that is also included in the extras bundle (under Windows | Prefs Editor).

Entities that inherit from GameItem often add their own specific features such as Level adds ‘stars won’ support. We encourage you to view the Game Structure documentation to understand these concepts further.

The GameItem that you will use most is probably Level. The currently selected Level can be accessed through GameManager.Instance.Levels.Selected or if you have added a LevelManager component to your scene then also through LevelManager.Instance.Level. Try referencing this and see the options you have available.


Most games have the concept of lives, and they are fully supported in Game Framework. The number of lives a player has (default 3) is set on the GameManager, but can be modified and changed as you see fit.

LevelManager has some support for certain game over conditions so go to your Game scene and on _SceneScope | Level Manager enable Game Over When Lives Is Zero. You can also optionally enter a delay in seconds before the GameOver dialog is shown e.g. if you have an explosion effect you want to complete first.


Run your game and in the Cheat Functions Window under the Player tab, use the lives buttons to decrease the number of lives. When the lives reach zero you should see that the gameover window is automatically shown.

With the game still running, navigate to the Menu scene and then back to the Game scene. The game over dialog shows straight away! We somehow need to reset the number of lives as they are still 0 and the game over condition is triggering immediately (you can verify the current number of lives in the Cheat Functions window).

Drag the Game Framework | Game Structure | Player | Set Lives component onto _SceneScope and select the Use Global Life Count option. Now when we re-enter our game the number of lives will be reset to the global default.


Finally we want some way of actually showing the lives to the user in our game. There are a couple of components that will help us out which basically allow us to set this up however we want. They are under Game Framework | Game Structure | Player:

  • Enable Based Upon Number Of Lives – allows us to show one of 2 different gameobjects based upon whether the player still has available a given life.
  • Create Lives Icons – creates a given number of instances of a prefab (representing a life) based upon the total number of lives. If the prefab contains the above Enable Based Upon Number Of Lives component then its life number will be automatically set.

There are already created 2 prefabs that use the above components (LifeIcon and Lives) that make use of the above. These lie under GameFramework\Prefabs\GameStructure\Player and there are both standard and themed versions available. As mentioned above we can create n LifeIcon prefab instances manually (1 for each life the user can have), or use the Lives prefab to automatically set them up.

On our Game scene, drag the Lives prefab under the Canvas gamebject, set Pos X  to 180 and Pos Y  to -55 to position the prefab to the right of the home button. Run the game and you should now have life icons that update when lives change.


From your own code you would want to call GameManager.Instance.Player.Lives -= 1 to decrease the number of lives, or access the same variable to get the current number of lives.

Camera Shake (Beautiful Transitions / Extras Bundle Only)

If you don’t have the extras bundle then you may skip to the next part on Health.

Occasionally we might want to shake the camera when we lose a life such as if it is caused by a crash or being hit by something. We can add this very simply using two components. First add the Shake Camera component (Add Component->Beautiful Transitions-> Shake Camera) to your Main Camera gameobject. Set Duration to 0.3 and each of the Range (X/Y/Z) values to 0.2. Next to _SceneScope, add the ShakeScreenWhenLivesLost component (Add Component->Game Framework->Game Structure->Players) and drag across your Main Camera gameobject into the Shake Camera field. Now whenever a  LivesChangedMessage message is generated (see part 8) due to a life being lost the screen will shake.


Health follows a similar concept to lives, and the two can be either linked together, or work independently.

As we did for lives, go to your Game scene and on _SceneScope | Level Manager enable Game Over When Health Is Zero. So that the health is reset, also add the Set Health component (Add Component->Game Framework->Game Structure->Players) onto _SceneScope and ensure Health is set to 1 (health should be in the range 0 to 1).

You can now run the game and using the Cheat Functions Window, use the health buttons to decrease the health and see that if the health reaches 0 the game ends. From your own code you would want to call GameManager.Instance.Player.Health -= 0.1f or similar to decrease the health You can  access the same variable to get the current health.


At this stage, we could chose to remove the lives functionality if we just wanted a health based system, but shortly we will look at how we can link the two together.

As with lives there are some components and prefabs that will help us out. They are also under Game Framework | Game Structure | Player. The ShowHealthImage component can be added to a gameobject that contains a UI Image component, where Image Type is set to Filled. This component also allows for changing the color of this image as the health changes (leave to the default white for no color change).

The HealthBar prefab (under GameFramework\Prefabs\GameStructure\Player) shows how you can use the ShowHealthImage component and again comes in both standard and themed versions.

On our Game scene, drag the HealthBar prefab under the Canvas gamebject, set Pos X  to 230 and Pos Y  to -120 to position the prefab below the life icons. Run the game and you should now have a health bar that changes.


As mentioned above, we can easily link health and lives together so loss of health involves the loss of a life. First on _SceneScope | Level Manager disable Game Over When Health Is Zero as we no longer want the game to exit on this condition. Next add the component DecreaseLivesWhenHealthIsZero (Add Component->Game Framework->Game Structure->Players) onto _SceneScope. That is all that is needed; if you run the game now and decrease health, you will see that when the health reaches zero, a life is lost. If you look at the source code of this component you will see that it is pretty simple and draws upon the power of the Game Framework messaging system to easily connect together different actions. You can use this system to also react to various conditions and we will discuss this further in a later tutorial.


Lastly in this part of the tutorial we will look at level ‘stars’. Stars are a great way of getting people coming back to your game and can be used to give experienced players an extra challenge. Star information can be shown automatically shown on level select buttons (if the correct child gameobjects exits) and the game over dialog and anywhere else we want through the components that we will look at below or the API.

The number of stars defaults to 3, but can be set either through the configuration files or code. Level also contains a number of methods for manipulating and handling stars so it is worth checking out the level class for a fuller understanging.

As our game stands, we can use the Stars buttons under the Level tab in the Cheat Functions Window to set what stars are won for the selected level (note: due to caching, you may notice this doesn’t always update in certain conditions).


Similar to lives there are 2 components that will let us show this in game. They are under Game Framework | Game Structure | Level:

  • Enable Based Upon Number Of Stars Won – allows us to show one of 2 different gameobjects based upon whether the specified star is won.
  • Create Star Icons – creates a given number of instances of a prefab (representing a star) based upon the global or level specific number of stars.

There are already created 2 prefabs that use the above components (StarIcon and Stars that make use of the above. These lie under GameFramework\Prefabs\GameStructure\Level and there are both standard and themed versions available. As mentioned above we can create n StarIcon instances manually (1 for each star the user can have), or use Stars to automatically set them up.

On our Game scene, drag the Stars prefab under the Canvas gamebject, set Pos X  to -10and Pos Y  to –125 to position the prefab under the score in the top right of the display. Run the game use the cheat functions to update the stars won and verify the display updates.


Finally we want to have some way of setting when stars are won. If we want to build this ourselves on predefined conditions, we can access the currently selected level and use the level.StarWon(starNumber, isWon) method. We can do this in game, or by extending GameOver and overriding the GetNewStarsWon method.

For this example we will do this in game and by using one of the StarsWonHandlerXxx components under Game Framework | Game Structure | Level.

Drag the component StarsWonHandlerCoins onto _SceneScope keeping the default values. Run the game and use the cheat functions window to increase the level coins – noticing how stars are won and updated. This component uses the power of messaging which we will look at in the next part of this tutorial series and reacts to any LevelCoinsChangedMessage to see whether new stars are won. If the Targets From Level Config option is selected then the threshold levels are as specified in the level configuration files allowing us to set different values for each level (the same applies for the StarsWonHandlerScore component).


As a final note, there is also support for animations in the game over dialog when new stars are won to give a nice effect – we will come back to this in a later tutorial.

Wrap Up

That completes our look at GameItems, lives, health and stars. For more information it is worth browsing through the components and prefabs mentioned above, the files under the GameStructure folder and checking out the samples in the extras bundle for more information.

If you are using the free version please consider small price for the extras bundle for access to the tutorial files, themes and lots of other useful assets and samples. This also helps support our efforts to develop and maintain this framework.

If you like the framework then please leave a rating in the asset store.

If you have any questions or feature requests then let us know below.