All Collections
Using the Portal
Design | Item Management | Catalog
Design | Item Management | Catalog

Use the Item Template to build game objects that live in the cloud

John Harley avatar
Written by John Harley
Updated over a week ago

Item Management is a powerful, fast way for your design team to build out a selection of key items in your app. 

Design

You will be able to use a template form to establish the core nature of items and easily tune many fundamental aspects of them without developer assistance.  This system is excellent for: 

Vanity Items

  • Hat for your hero: Buy once, use forever. 

Gear

  • Sword: Buy one, wears down as you use it. Vanishes when worn out.

Per Round Game Boosts: 

  • Double XP Booster: Buy once, use once

  • Double XP Booster Triple Pack: Buy once, use 3 times

Timed Game Boosts:

  • Invincibility Potion: Buy once, activate, use for duration

Permanent Game Boosts:

  • Lifetime Coin Doubler: Buy once, use forever

If your project requires, items also can be set to no-drop or non tradeable.

Implementation

To manage or create new items, find the Catalog page on the brainCloud portal.

Use the filter to help you focus on just the items you want. 

Status: 

Draft - This item is not exposed to the client. You can use this state to do the initial setup on the item and later implement it in your app.
Published - This item is available in the game
Retired - This item can no longer be acquired in the game, but existing owners are allowed to continue using it.
Revoked - This item has been banished from the game and removed from your users' inventories.

Note: Items need to be either in Draft state, or moved into Revoked state before they can be Deleted. 

Tip: Facilitate your workflow by choosing to sort by Status to arrange the Draft items near the top of the list. 

You can use the checkboxes on the left side of the list to act on multiple items at once. However, actions are visible when items of the SAME status are selected. 

Actions
Use the Actions dropdown for the available operations on your items.

Design Tip: If your app needs several copies of a similar item, the Clone operation will save time by making a copy of an existing item definition in a Draft state, and automatically advance you to the Item edit view. 

Creating a new item 

  • Click [Create] in the upper right

  • Enter a Definition ID. This is the unique identifier used when referencing and awarding the item.

  • Enter a user-facing Item Name. It's recommend to decide on a maximum Name length, so all given names will later fit within the app's UI.

  • Enter a user-facing Description. Similarly, you may need to decide to use terse descriptions to preserve UI space in your app and to simplify text-fitment issues.

  • Select Type: "Item". brainCloud will be bringing Bundles to Items soon. 

  • Enter a category. Categories are useful for grouping and filtering results. eg. Swords, Potions, Boosters, or Doublers are good categories. 

  • Add tags which might help your users filter and find specific items. Tags should have no spaces and should be separated by commas

  • You'll need to save the current Item Definition before you can add a picture. Skip this for now.

  • Optionally, add the Resource Group and Resource Tag. Use these values to indicate where your game locates the art assets required for the item.

  • Select Manage to set a Purchase Price for your item. 

  • From the Purchase price manager window select a Currency and Price for your item. 

  • Select [Apply]

  • Tip: You can set one price per currency type in your game. Multiple price points can be useful in demonstrating the appeal of using both soft and hard currencies to the player.

  • Select [Confirm] to save your prices.

  • If your item is Sellable, repeat the process for the Sell Price. 

Design Tip: It's common to offer a lower Sell price to drive users to Purchase things as needed but not frivolously. It is also usually important to game economies that Tradable items have a low sell-back value to limit currency transferring between players. 

  • Choose if your item is Stackable. "Stackable" should be set when every instance of the item in the game will have the same attributes AND the user can collect more than one of it. For example, a "Small Health Potion" would be stackable. Items which can be customized, or which have cooldowns should not be set to Stackable. Typically Vanity items and permanent items are not stackable, while gameplay items such as XP Boosters or Health Potions are.

  • If the item gets used up in the course of play, enable Consumable. Select how many uses the item has per unit. 

  • Design can set a Cooldown which will make the player wait a while before they may activate the item again. For example a Fireball Potion might have a 1 minute cooldown before it can be used again.  

  • Design can set a Recovery which controls the rate at which the item recharges to its capacity. The item will regain one charge per duration set. 

  • If the item can be Activated for a Status Effect, set the Status Effect Name and the Active Duration. 

Design Tip: Because Cooldowns & Recoveries are tracked on the Server, boost effects that last multiple days are easy to implement. For example, Design could make a Building (or NPC) in the game that grants a "48 hour Double XP Boost" and recharges twice per month. (With more available to purchase in the shop.) This would give players additional motivational tools to improve engagement for relatively low implementation effort. 

  • Tradeable: If you want to forbid players from transferring an item (such as a vanity item, or no-drop item), then leave Tradeable Unchecked. By enabling Tradeable, it means braincloud will allow an instance of the item to be transferred between player accounts.  

  • Use Blockchain: Coordinate with your team on whether to use Blockchain to improve item security for Tradeable, non-stackable, high-value items. Note that using Blockchain can substantially slow down transaction performance while the purchase is executing (up to several hours). 

Custom Data

  • Meta Data: Coordinate with your team on a format to use for custom Meta data. For example: damage, accuracy and range are often useful values. 

  • Initial Item Data: Enter the custom Initial Item data state. For example a Rusty Sword might start in a partially worn out condition, giving the player the opportunity to repair it back to 100% durability. 

After entering your data, select [Save] in the upper left. 

  • If you have an image icon for your item, you can now select Edit and add it. 

  • Select [Save] once again. 

Decide and coordinate with your team on how to implement the item within your app. When ready to make the item visible to your client, select Publish.

Remember: Clone is available to rapidly create similar items with minor changes.

Development Tip: the Item Catalog comes with its own API that will also allow you to programatically handle all these configuration aspects. Read about SysAddCatalogItem and other system API calls in the API Reference.

Writing the code

Now that you added item definitions to the item catalog, you will want to grant them to your players.

In your client code

  • Add the brainCloud client to your app.

  • Pair the client with the dashboard.

  • Authenticate your user into brainCloud.

  • Request published items from the catalog with the GetCatalogItemsPage call.

  • Award two random items from the catalog.

  • Get a list of all the Items that the user currently has.

  • Have the user randomly drop one of those items.

  • Review other User Item and Item Catalog related calls for your app in the API Reference.

private BrainCloudWrapper _bc;
private string _wrapperName = "default";

void LogError(int status, int code, string error, object cbObject)
{
    Debug.Log(String.Format("An error occured {0} : {1} ({2})", status, error, code));
}

void Start() {
    // Unity
    GameObject go = new GameObject();
    _bc = go.AddComponent<BrainCloudWrapper>();
    _bc.WrapperName = _wrapperName; // optionally set a wrapper-name
    _bc.Init(); // extra data, such as: _appId, _secret and _appVersion, is taken from the brainCloud Unity Plugin.
    DontDestroyOnLoad(go); // keep the brainCloud game object through scene changes  
   
    _bc.AuthenticateAnonymous((response, cbObject) =>
    {
        CheckTheItemCatalog();
    }, LogError);
}

List<string> itemsToAward = new List<string>();

// Get a list of items from the Item Catalog
void CheckTheItemCatalog()
{
    var context = BrainCloud.JsonFx.Json.JsonWriter.Serialize(new Dictionary<string, object>
    {
        {"pagination", new Dictionary<string, object> {
                {"rowsPerPage", 50},
                {"pageNumber", 1}
            }
        },
        {"searchCriteria", new Dictionary<string, object> {
                {"category", "collectable"}, // Choose a category of item
                {"pState", "PUBLISHED"}      // Ensure it's published  
            }
        },
        {"sortCriteria", new Dictionary<string, object> {
                {"createdAt", 1},
                {"updatedAt", -1}
            }
        }
    });
   
    _bc.ItemCatalogService.GetCatalogItemsPage(context, (response, cbObject) =>
    {
        var jsonMessage =
            (Dictionary<string, object>) BrainCloud.JsonFx.Json.JsonReader.Deserialize(response);
        var jsonData = (Dictionary<string, object>) jsonMessage["data"];
        var results = (Dictionary<string, object>) jsonData["results"];
        var items = (Dictionary<string, object>[]) results["items"];

        if (items.Length > 0)
        {
            var random = new System.Random();
           
            // Randomly grab two items from the first page of the catalog
            itemsToAward.Add((string)items[random.Next(items.Length)]["defId"]);
            itemsToAward.Add((string)items[random.Next(items.Length)]["defId"]);
           
            AwardItems();
        }
    }, LogError);
}

// Award two of those items from the user
void AwardItems()
{
    int called = 0;
    foreach (var itemDefId in itemsToAward)
    {
        var quantity = 1;
        var includeDef = false;
       
        _bc.UserItemsService.AwardUserItem(itemDefId, quantity, includeDef, (response, cbObject) =>
        {
            called++;

            // Once all items are awarded, let's check the inventory
            if (called == itemsToAward.Count)
            {
                ReadUserItems();
            }
        }, (status, code, error, cbObject) =>
        {
            LogError(status, code, error, cbObject);
        });

    }

}

List<string> itemsToDrop = new List<string>();
// Get a list of items from the user's inventory
void ReadUserItems()
{
    var context = BrainCloud.JsonFx.Json.JsonWriter.Serialize(new Dictionary<string, object>
    {
        {"pagination", new Dictionary<string, object> {
                {"rowsPerPage", 50},
                {"pageNumber", 1}
            }
        },
        {"searchCriteria", new Dictionary<string, object> {
                // Our search criteria will by empty, to grab all possible items
            }
        },
        {"sortCriteria", new Dictionary<string, object> {
                {"createdAt", 1},
                {"updatedAt", -1}
            }
        }
    });


    var includeDef = true;
    _bc.UserItemsService.GetUserItemsPage(context, includeDef, (response, cbObject) =>
    {
        var jsonMessage =
            (Dictionary<string, object>) BrainCloud.JsonFx.Json.JsonReader.Deserialize(response);
        var jsonData = (Dictionary<string, object>) jsonMessage["data"];
        var results = (Dictionary<string, object>) jsonData["results"];
        var items = (Dictionary<string, object>[]) results["items"];

        if (items.Length > 0)
        {
            var random = new System.Random();
           
            // Randomly grab one item from the first page of the user's items
            itemsToDrop.Add((string)items[random.Next(items.Length)]["itemId"]);
           
            DropItem();
        }
    }, LogError);
}

// Drop one of those items
void DropItem()
{
    foreach (var itemDefId in itemsToDrop)
    {
        var quantity = 1;
        var includeDef = false;
       
        _bc.UserItemsService.DropUserItem(itemDefId, quantity, includeDef, (response, cbObject) => { }, (status, code, error, cbObject) =>
        {
            LogError(status, code, error, cbObject);
        });
    } }

Further learning

  • Try using items that invoke status conditions, with UseUserItem, and review current user status conditions with ReadUserState.

  • Create and award a virtual currency to your player, and use PurchaseUserItem and SellUserItem to add and remove items from the user.

  • Create multiple users and use both GiveUserItemTo and ReceiveUserItemFrom to allow players to move items between themselves.

Did this answer your question?