World Variables

Core GameKit has the super flexible concept of World Variables. These can represent in-game integers (whole numbers) and floating point numbers (decimals) such as score, health or game currency. Core GameKit ships with these and a couple others, although the list is completely customizable by you to include as many as you like. These values are managed by Core GameKit using a cached version of PlayerPrefs that has very fast performance on mobile devices, although it's not used on certain Consoles that don't allow it.

 
 

There are 4 topics:

  1. Using World Variable Value For Settings: Most fields in Inspectors have the option to use a World Variable current value instead of a static number.
  2. Creating World Variables: This explains all the options for World Variables and how to create them.
  3. Persistence Options: This explains how to persist the World Variables you want.
  4. Misconfigured Variables: Core GameKit will tell you if you've selected a World Variable that has been deleted / renamed.
  5. World Variable Modifiers: Several Inspectors in various Core GameKit scripts let you modify any number of World Variables by adding / setting values, and more.

 

Using World Variable Value For Settings

World Variable are not just for displayed stats like score and currency. You can use these to control and manipulate any integer or float field in any of the Core GameKit Inspectors! Notice below the blue dropdown with the word "Value" in the below image. Think of this as a "setting source" dropdown. That means it will get the value (for Start Hit Points let's say) from what you enter into the number field to the left. The green "I" or "F" denotes whether the World Variable is an int or a float.

 

 

If you now choose "Variable" from the blue dropdown, the number entry field will change to a World Variable selection dropdown, showing only the World Variables of the same type (int or float). See that I have now selected the "Game Currency" Variable for the Start Hit Points in the next image.

 

 

This means that whenever the Start Hit Points of this Game Object is evaluated, it will use the selected World Variable's current value! Powerful stuff, considering that every Wave beat, Killable killed, Wave spawned and tons of other events can modify the World Variable values without any coding.

Note: At runtime, the current value of the selected World Variable will be displayed in the Inspector to the left of the I or F.

 

Creating World Variables

Under the LevelWaveSettings Game Object, there is a child prefab called WorldVariables. Click on it. Now in the Inspector pane is a summary of the World Variables you have to start with. The type of each Variable is shown in yellow near the right and a button to delete the World Variable. Also, at runtime, the value of each World Variable is displayed in the title bar and there are controls to change the Variable value at any time. It looks like this:

 

 

There are a few controls in the top section:

     
  1. Variable Creation Area: Type a New Variable Name, pick New Variable Type (int or float). If you only need whole numbers, choose integer. If you need decimal points, choose float. Now click "Create Variable" and it will show up below with the rest of its settings.
    2.  
  2. Show Integers / Floats: Here you can choose to show floats / ints and filter out the rest in the grid below.

 

Each World Variable has the following settings:

     
  1. Name: This is important to establish early on. If you rename it later after other scripts are using it, you will need to reselect it in the other scripts. I recommend first setting up all the World Variables you think you will need, then using them elsewhere.
    2.  
  2. Persistence Mode: There are 2 modes to choose from:
       
    • Reset To Starting Value: This will reset the Variable to the value in the next field (Starting Value) when the scene starts. A Variable like score may or may not want to be set this way. The Unity engine can't tell whether you are starting a new game, or just progressing to level 2 for instance. They both are just a Scene change. You will see how to control this in either case shortly.
      •  
    • Keep From Previous: This will allow the Variable to be carried over from the previous Scene or game. You may want experience points or game currency to be set like this. If it happens that you have Keep From Previous selected, but there is no previous value, the Start Value will be used (next field).
    3.  
  3. Modifications Allowed: Controls how the variable can be modified. Choose from the following:
       
    • Any: No restrictions.
      •  
    • Only Increase: The Variable can only be increased. Useful for something like a high score.
      •  
    • Only Decrease: The Variable can only be decreased.
    4.  
  4. Starting Value: This is the value the Variable will be set to initially on the current Scene, if you have "Keep From Previous" selected as the Persistence Mode. Otherwise the Starting Value will not be used unless the variable doesn't exist yet when you play the Scene. This would only happen the first time any Scene with the Variable was played (first game on a device).
    5.  
  5. Allow Negative: Check this if you want to allow the Variable to go below zero, otherwise any modifications to the Variable that result in a negative number will instead set the Variable to zero.
    6.  
  6. Has Max Value: This defaults to off. If you check this box, you can choose a maximum value for the Variable. This is useful for things like making sure health never goes over 100.
       
    • Max Value: The maximum value for the Variable.
    7.  
  7. Triggers Game Over: Check this if a certain value (or range of values) of the Variable can end the game. For example, zero health or zero lives. You must set the range in the next field.
       
    • G.O. Min/Max Value: G.O. stands for Game Over. This pair of values defines a range of the Variable that will trigger Game Over. When Game Over occurs, LevelSettings.IsGameOver will be set to true, shutting off most of Core GameKit (although you can prevent this with the Game Over Behavior setting on some scripts).
    8.  
  8. Custom Events: You can enable this section and add one or more already created Custom Events to fire whenever the World Variable's value changes.
    9.  
  9. Value Changed Sound: This plays a Sound Group of your choice when the World Variable's value changes.
    10.  
  10. Listener: Here you can drag in a WorldVariableListener to hook into key events and do customized coding, so it could update the score display for example. There are included completed ones for uGUI, NGUI and TextMeshPro one. For more about Listeners go here.

 

Persistence Options

After you’re satisfied with your set of World Variable, let’s see how to reset some of them when the game starts.

     
  1. The easiest way is if you have a separate Scene, like a main menu, that the user has to go to every time they want to start a new game. If you have one of these, do the following:
       
    • Add a LevelWaveSettings Game Object.
      •  
    • Go to the World Variables sub-Game Object under it.
      •  
    • Add entries just for the World Variables you would like to reset (score etc). Make sure their Type matches the Type in the other scene (integer etc).
      •  
    • Change their Persistence Mode to Reset To Starting Value and change the Starting Value field to the value you want.
      •  
    • Delete the entries for all other World Variables you don't need to reset.
    2.  
  2. If this method doesn’t fit your scenario, you can use a line of code to retrieve of modify a World Variable value.

    To retrieve, use this static method:

    var variable = WorldVariableTracker.GetWorldVariable("yourVarName");
     

    Then, you will retrieve the value with one of these properties, depending on the type of the Variable. Only Int or Float is used within each Variable:

       
    • variable.CurrentIntValue
      •  
    • variable.CurrentFloatValue

    To set the value, use the same code above, but assign a value to the property. i.e.

    var variable = WorldVariableTracker.GetWorldVariable("yourVarName");
    variable.CurrentIntValue = 45; // or CurrentFloatValue for a float!
 

Misconfigured Variables

Core GameKit will tell you about incorrect / deleted / renamed variables in two ways:

     
  1. It will be prominently displayed in the Inspectors like so:
     
    2.  
  2. All scripts that use World Variables check all their configuration upon the Awake event, and will log errors to the Console window to tell you very specifically what is missing for which prefab and script.

 

World Variable Modifiers

There is a common section for World Variable Modifiers in many Inspectors of Core GameKit. This lets you add / subtract / set / multiply to any number of World Variable values, such as score or experience points. It looks like this:

 

 

Here you can add any number of World Variable Modifiers. Each one has:

     
  1. Variable Name: You add each row from the "Add Variable Modifier" dropdown which contains only World Variables not already in the grid below.
    2.  
  2. Modifier Type Dropdown: Here you can choose the following:
       
    1. Add: The default. The value you specify will be added to the selected World Variable's value.
      2.  
    2. Set: The selected World Variable's value will be set to the value you specify.
      3.  
    3. Sub: The value you specify will be subtracted the selected World Variable's value.
      4.  
    4. Mult: The selected World Variable's value will be multiplied by the value you specify.
    3.  
  3. Modifier Value: Here you either enter a value such as 200 or use the current value of another World Variable by selecting Variable from the blue dropdown to the right. In either case, the value is what is added / set / subtracted / multiplied when the target World Variable is modified.
    4.  
  4. Setting Source: Choose either Value (default) or Variable. Read more about this in the first section on this page.
    5.  
  5. Delete Button: Delete this modifier.