Game Foundation tutorial

Creating a Game Item

Tip: A Game Item is any type of data that represents a gameplay concept you want Game Foundation to manage. While Game Foundation already provides built-in concepts like Inventory Item, for any generic concept in your own custom logic (such as a Player Character), defining them as Game Item allows you to take advantage of Game Foundation capabilities. Furthermore, when you want the same concept to be shared by multiple systems, you can define that first as Game Item, and later use ‘Reference Definition’ to inherit that definition in other systems.

You can define a “coin” in the Game Item catalog and have your Store and Wallet systems refer to that Game Item when they want to know what a coin is.

Open the Game Item window (menu: Window → Game Foundation → Game Item). This is a tool for viewing and managing the contents of your Game Item catalog.
Click the + button to create a new Game Item and then enter a Display Name and an Id. The display name can be modified later, but the ID will be permanent.
- Tip: String IDs are the easiest way to access object instances managed by Game Foundation (the alternative approach is hash number). We recognize that using string ID may not be the best solution in some cases. We’ll provide an alternative solution in a future release.
Click the Create button. When a Game Item is created and added to the catalog, the Detail Definitions configuration options become available for that Game Item. A Detail in Game Foundation is a little bit of data added to a Game Item to describe it further, and details are often pertinent to specific systems.

Using the Wallet with Soft Currency

Creating a soft currency

Tip: Soft Currency is a common game mechanic to let the player manage one or more “soft” currencies, which can be earned by playing the game, and spent to unlock content or progress your gameplay. We can keep track of these soft currencies with a virtual “wallet”.

Open the Inventory window (menu: Window → Game Foundation → Inventory).
This is a tool for viewing and managing the contents of your Inventory catalog.
Click the + button to create a new inventory item and then enter a Display Name and an Id. The display name can be modified later, but the ID will be permanent.
Click the Create button. When an item is created and added to the catalog, the Categories and Details Definitions configuration options become available for that item.
A currency item must contain a currency detail. Click the Add Details button and then select Currency Detail. The Currency Detail allow you to select the type of currency you want to use, but for this tutorial it can stay as the default value, Soft.

Adding a Currency Detail also automatically adds an Analytics Detail.
Currency items can be added to the Wallet at runtime. You can display currency items automatically in the player’s wallet at the start of the game by making the currency item a Default Item in the Wallet inventory. Click on the Inventories tab and select Wallet from the list of inventory items (the Main and Wallet inventories are built-in to Game Foundation and can’t be deleted; you can create additional custom inventories as needed).
Each inventory contains a list of Default Items which are automatically added to that inventory when it is first instantiated at runtime. In your Wallet, look under Other Available Items to find the Coin item, and click the Add To Default Items button next to it. This moves Coin to the Default Items list.
You can now set the quantity of the item to be added to the wallet when it is first created. In this case, the player will start with 100 coins in their wallet.

Spending currency in-game

After creating your Coin and adding it to the Wallet in the previous tutorial sections, add the following script to a GameObject in a Scene:

using UnityEngine;
using UnityEngine.GameFoundation;

public class WalletTest : MonoBehaviour
{
    void Awake()
    {
        // you always need to call Initialize once per session
        GameFoundation.Initialize();
    }

    void Start()
    {
        // get the coin item by its ID
        InventoryItem coinItem = Wallet.GetItem("coin");

        Debug.LogFormat("coins in wallet at start: {0}", coinItem.quantity);

        coinItem.quantity -= 25;

        Debug.LogFormat("coins in wallet: {0}", coinItem.quantity);
    }
}

Click Play. In the console, you’ll see the player’s wallet starting out with 100 coins in it. 25 coins are then removed, leaving them with 75 coins.

Creating and Applying Stats

Tip: In Game Foundation you can use Stats to track and manage any numeric values in your gameplay, such as the health of a character, damage point of a weapon, or how many times the player has beat the level. Extending the stat system will allow you to apply formulas to stats based on modifiers and player progression.

Open the Stat window (menu: Window → Game Foundation → Stat).
This is a tool for viewing and managing the stats you want to adjust and persist at runtime.
For this example, we’ll use a sword with a Damage stat. Create the Damage stat by clicking the + button to create a new stat item with the following values:
- Display Name: Damage
- Id: damage
- Value Type: Int
Click Create.
- Tip: the numeric types currently supported are Float (C# System.Single) and Int (C# System.Int32). Once you choose which numeric type a stat is, it cannot be changed later.
Following the steps from the Creating a Game Item tutorial, create a Sword GameItem.
Click Add Details to add Stat Details to the Sword.
In the Stat Details section, you’ll see a popup menu with your only stat, Damage, already selected. Click Add to add the Damage stat to your Sword, and then set the Default Value as 10.
Using what you've learned from the tutorials so far, do the following:
- Create a “Damage Increase” stat with a Value Type of Int.
- Create a “Damage Buff Spell” Game Item.
- Give the spell a “Damage Increase” stat with a default value of 1.
- Create a “Sword” Inventory Item with the Reference Definition set to Sword, and add it as a default item in the Main inventory.
- Create a “Damage Buff Spell” Inventory Item with the Reference Definition set to Damage Buff Spell and also add it to the Main inventory’s default items.

Working with Stats at Runtime

Now that we have a sword and a spell, let’s use those while playing the game. We’ll access the sword and spell in the inventory, and consume the spell in order to improve the damage stat of the sword:

// let's use a consumable scroll to buff our weapon

void Awake()
{
    // you always need to call Initialize once per session
    GameFoundation.Initialize();
}

void SharpenSword()
{
    // get the sword from inventory
    InventoryItem swordItem = Inventory.main.GetItem("sword");

    // get the scroll from inventory
    InventoryItem scrollItem = Inventory.main.GetItem("scrollDamageIncrease");

    // get the sword’s current damage
    int swordDamage = StatManager.GetIntValue(swordItem, "damage");

    // find out how much the scroll will increase the damage
    int damageIncrease = StatManager.GetIntValue(scrollItem, "damageIncrease");

    // increase this sword’s damage permanently
    StatManager.SetIntValue(swordItem, "damage", swordDamage + damageIncrease);

    // consume the scroll by removing it from the inventory
    Inventory.main.RemoveItem(scrollItem);
}

Saving and Loading Game State

Now that you’re playing the game and your wallet values have changed, you’ll want to save your progress to make sure these changes persist when you return to the game. When you initialize the inventory manager (as you did in the previous tutorial), you should also pass in a persistence provider. That will automatically load the state that was last saved. When you’re ready to save or load the game state, you can use methods like these:

using UnityEngine;
using UnityEngine.GameFoundation;

public class SaveGame : MonoBehaviour
{
    IDataPersistence localPersistence;

    void Awake()
    {
        // choose what format you want to use
        JsonDataSerializer dataSerializer = new JsonDataSerializer();

        // choose where and how the data is stored
        localPersistence = new LocalPersistence(dataSerializer);

        // tell Game Foundation to initialize using this
        // persistence system. Only call Initialize once per session.
        GameFoundation.Initialize(localPersistence);
    }

    public void Save()
    {
        GameFoundation.Save(localPersistence);
    }

    public void Load()
    {
        GameFoundation.Load(localPersistence);
    }
}