Getting Started With Game Framework for Unity – Part 6 – Worlds and Resources

Skill level: Beginner / Intermediate
Tutorial time: 20 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, Level Configuration 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 look into the concept of worlds. The use of worlds is entirely optional however for certain games it can be useful to group levels into different ‘categories’.

World Creation

Worlds are based upon the same GameItem base as levels, players and characters and so follow a similar setup and structure. Like we did with levels in part 1 we will let the framework automatically create some worlds for us, although you can manually create through scripting if you have special requirements.

Note: Consider whether you want to make a copy of the getting started tutorial so far in case you later decide you don’t need worlds.

In our Title scene, find the GameManager component on the _GameScope gameobject and set the properties as shown in the picture below (ignore any differences if you see slightly different options). This will give us 3 worlds and we have divided our levels out from before across the different worlds (the level number ranges part).


Click Apply at the top of the inspector window to apply the prefab changes.

Next on _SceneScope, find the OnMouseClickOrTapLoadLevel component and change Scene Name to Worlds which is a scene that we will create next.

World Select Scene – Basic setup

Our world select scene will be similar in many respects to our level select scene, so create a copy of the Menu scene (select it and Menu | Edit | Duplicate) and rename it to Worlds.

In our new Worlds scene, rename LevelButtons to WorldButtons and on the child Buttons gameobject, delete the CreateLevelButtons component and instead add a CreateWorldButtons  component (Add Component->Game Framework->GameStructure->Worlds). Onto this drag the WorldButton prefab that you want to use either from  \FlipwebApps\GameFramework\Prefabs\GameStructure\LevelButton, or one of the themed versions. finally on the GridLayoutGroup change Child Alignment to Upper Center and set the Cell Size to X – 400 and Y – 500 to give us slightly bigger buttons.

Also on the Canvas | UnlockButton gameobject. Delete the UnlockLevelButton component and add instead an UnlockWorldButton component (Add Component->Game Framework->GameStructure->Worlds). 

To link everything in correctly, go to the Menu scene. On _SceneScope | OnEscapeLoadLevel set Scene Name to Worlds. Also, on Canvas | HomeButton | OnButtonClickLoadScene set Scene Name to Worlds.

Add the new scene to build settings and you can now run the game and should be able to browse through the different screens and the levels will be split across the worlds as we specified. You may see a warning and that is because we chose a setup mode of From Resources but haven’t yet created any configuration files. We will look into that next.

Custom World Configuration

We have seen previously with Levels how we can add configuration files and we will do the same with Worlds. It might also be the case that you need your own per Level, World, Character etc. custom configuration data so we will show how that can be done here.

Create a new folder in your project named Scripts and into this create a new C# script (Right click the Scripts folder -> Create -> C# Script). Name this script CustomWorld, open it and enter the following code:

using UnityEngine;
using GameFramework.GameStructure.Worlds.ObjectModel;

[CreateAssetMenu(fileName = "World_x", menuName = "Game Framework/Custom World")]
public class CustomWorld : World
    public string Difficulty;

This code will create a new subclass of World with an additional configuration string parameter called Difficulty (you can add whatever extra variables you need). The CreateAssetMenu line adds a new menu entry for creating instances of these.

Important: It is vital that the script name and the class are both the same (in this case CustomWorld). If they are different then Unity will not be able to associate the script with the configuration items and show a missing script message.

As we did for Levels, create a folder Resources\World, right click this folder and select Create->Game Framework->Custom World and create 3 instances of our new configuration files for each of our 3 worlds. Name these World_1, World_2, World_3.

If you click on the configuration items you will see that they correctly show our new field where you can enter suitable values.


In game you can use code similar to the following to access our custom property or any other values.

# Get a reference to the current world cast to our new CustomWorld type
var world = GameManager.Instance.Worlds.Selected as CustomWorld;
# Do something with it

In this tutorial we won’t actually use our additional configuration values so here you could just as well use the standard World configurations however we demonstrate this for illustration purposes. For our simple difficulty variable you could also have added a custom variable to the Variables section of the World configuration file and accessed these through the GameItem Variables property.

# Get a reference to the value of the GameItem Variable named Difficulty.
var difficulty = GameManager.Instance.Worlds.Variables.GetString("Difficulty").Value;
# Do something with it

In addition to the above there are also other ways of providing configuration for various different requirements as discussed in the documentation on Game Structure. This includes using Json configuration files and also manual loading of in game data so that you don’t hold complex configuration for all items in memory unnecessarily.

As we did for levels, in the world configuration files set the first with Start Unlocked enabled and the others to Unlock With Coins and a Value to Unlock of your choosing. Finally we will add a custom name to each configuration item. Add the following to the localisation file that you created earlier and then in each world configuration item select the globe icon and enter the corresponding localisation key (W1.Name, …).


You can also add some images as we did previously for levels to the folder Resources\World in the format World_<number> and make them of type Sprite.

You should now have something similar to the image below. Here we have also add a new UI | Text component with the text World Select to show this is the world select screen.


World Select Scene – Completion

As a final touch we will add the world name onto the level select screen.

Go to the Menu scene and add two UI text components to get the effect shown in the image below. To the first of these gameobjects, add a ShowWorldInfo component (Add Component->Game Framework->GameStructure->Worlds) and for Text enter World {0} – {1} to show the number and name (ideally we would enter this as an entry in our localisation file and refer to that). The text should now update to show the correct world number and name.


Multiple Scenes Per Item or Just One

Up until now we have reused the same scene for multiple items and adjusted the configuration; The same level select (Menu) scene for different worlds and the same Game scene for all levels. There are different possibilities on how to set this up, from having a separate scene for each item, or by dynamically reacting to the current state as we have done so far. The choice depends a lot on how different the scenes need to be for each item and to what extent you can use things like prefabs for common elements.

For our world and level select buttons, the WorldButton and LevelButton components respectively have a field ClickUnlockedScene. By default this is just a fixed scene, however you can also add the text {0} to have the current items number inserted. E.g. on WorldButton if you entered Menu{0} then the scene Menu1 would be loaded for world 1, scene Menu2 for world 2 etc.. If you are automatically setting up the buttons then you would need to make this change on the button prefab (or a copy if using the standard prefabs so changes don’t get overwritten when you upgrade).  We won’t do that in this example, but the below diagram illustrated how this might look.


You can also subclass WorldButton and override the ClickUnlocked() method to provide your own custom handling. Such features are in place across the framework to allow for easy customisation. If in doubt check the source code of a relevant component for more information.

Wrap Up

That completes our look at worlds and how they can be implemented and tested.

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

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 samples and assets. This also helps support our efforts to develop and maintain this framework.

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