Skip to content

Catalog

The Catalog feature of ChilliConnect is a centralized repository that allows you to manage, version and publish in-game currencies, purchases, content, assets, custom metadata and more. Anything you want to update or modify in your game without having to distribute a new build can be included as part of your game Catalog. Catalog items can be defined either through the ChilliConnect dashboard or imported in batch.

You can also modify data for particular player groups or segments through Overrides, allowing you to easily run A/B Tests and Live Events. See our Gacha Tutorial for an example of this.

Item Types

Each item in a game catalog is defined as a Catalog item. Catalog items can include currencies, conversion tables, inventory items, virtual purchases, content and general purpose metadata - you can also define your item types using Custom Types. Each of the built in item types are described in detail below.

Currencies

Currencies are used to define virtual currencies that exist within your game. When defining currencies there is the option to set an "Initial Balance", the amount a player will receive when they first join your game, and a "Max", the limit to how much of that currency a player can have. For each currency defined, ChilliConnect will store a balance against each player account which can then be managed through the Economy.

AddCurrency

Currency Conversions

Currency conversions are used to define exchange rates between your Currencies. You must have two Currencies before you can define a Conversion. When defining a Conversion, you may specify multiple rules for all the different Currencies you have. This allows you to have one Conversion object defined that contains all currencies, or have multiple conversions with different rules when you want to apply different conversion rates in different scenarios - providing a different conversion rate for different player levels for example.

CurrencyConversion

Inventory Items

Inventory Items are objects that a player can own.

InventoryItems

Real Money Purchases

Real Money Purchases allow you to map In App Purchase store identifiers from Google Play, iTunes and the Amazon App Store to Inventory Items and Currencies. The Real Money Purchase feature of ChilliConnect is a more powerful version of the standalone In App Purchase validation feature.

Real Money purchases also allow you to specify one-time-only purchases so that players can be restricted to only buying certain In App Purchases once.

For a detailed walkthrough on how to implement a full end-to-end In App Purchase system in Unity using ChilliConnect Real Money Purchases, see the In App Purchase tutorial.

RealMoneyPurchase

Virtual Purchase

Like Real Money Purchases, Virtual Purchases allow your players to purchase items and currency but using costs deducted from their in-game account rather than real money. As well as the most obvious use case of defining in-game shops, by allowing costs to be defined as both currencies and items, virtual purchases can also be used to define items conversions, crafting tables, or even exchanging items for currency.

Also like Real Money Purchases, Virtual Purchases can be assigned as one-time-only purchases to restrict the amount of times players can make specific Virtual Purchases.

VirtualPurchase

Metadata

Metadata is an untyped, wildcard object that can you can use to store bespoke, custom definitions - for example, XP required by a player to level up or game difficulty configuration. By defining this data as part of the ChilliConnect Catalog you can easily manipulate it from the dashboard, retrieve it on demand in your game using the GetMetadataDefinitions API method as well as access it directly from Cloud Code to write your own API methods.

Metadata

Zip Package

Zip Packages allow you to upload content in a zip file that is then hosted on the ChilliConnect servers. The GetZipPackageDefinitions API method then allows you to search for available packages and retrieve the URL of the package which you can use to initiate a download to the player's device. Zip Packages can be used to deliver any type of content you like to your players including assets, new levels, localization files.

ZipPackage

Unreal Mobile Patch

The Unreal Mobile Patch type provides direct support for mobile patches generated by the Unreal Engine.

UnrealMobilePatch

For more details on how to generate a patch file in Unreal Engine, please see the following resources:

Once you have generated the patch content in Unreal you must then create a Zip file of the CloudDir folder for each platform that you want to download the content from ChilliConnect. The folder structure generated by Unreal will be similar to below:

UnrealMobilePatch

You should create a Zip of the CloudDir folder, so that the folder is the only item at the root of the Zip. Once you have created the Zip, it can be uploaded as an Unreal Mobile Patch catalog item. The GetUnrealMobilePatchDefinitions API method then allows you to search for available patches and retrieve the CloudDir URL and Manifest URL of the patch. These can be then be passed directly to the supporting Unreal Blueprints nodes to download the content:

ImportUpload

Custom Data

All of the catalog items listed so far, with the exception of the Metadata item, have the option of attaching a Custom Data to them. Custom Data allows you to define additional information that you want to be stored against an catalog object definition. This could be something as simple as a better item description, the path to the texture that should be used to render the or any additional item properties that you want to change without having to rebuild your game. Custom Data is defined in JSON format.

CustomData

Custom Types

Custom Types allow you to define your own catalog types that are specific to your game. Custom Types are described using the JSON Schema standard, Draft 04. Once a Custom Type is defined, you can add items of that type to your catalog. ChilliConnect will automatically generate a form for your type and apply the validation rules described in your JSON schema. This way, a game programmer can describe the format of the data they expect in the game using a Custom Type, and other non-technical members of the team such as game designers or live ops support staff can create or modify items of that type without having to worry about making mistakes.

Custom types are added from the Types tab of the catalog view:

CustomData

The example Power Up type in the screenshot above uses the below JSON Schema definition to describe an object with properties for an icon, the player property that is affected by the power up (one of health, defence, or stamina), a cooldown timer between the values of 0 and 500 and a modified between 1 and 10 that describes how the power up modifies the underlying property.

{
    "type": "object",
    "properties": {
        "icon": {
            "type": "string"
        },
        "affects": {
            "type": "string",
            "enum": [
                "health",
                "defence",
                "stamina"
            ]
        },
        "cooldown": {
            "type": "integer",
            "minimum": 0,
            "maximum": 500
        },
        "modifier": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10
        }
    },
    "required": [
        "icon",
        "affects",
        "modifier"
    ]
}

Note that all Custom Types must start with an object type as the root property. For more information on the available JSON Schema rules, see the JSON Schema official website. From the Catalog Items view, it is now possible to add an instance of our Power Up type:

Publish

ChilliConnect will generate a form view based on the properties of the Power Up:

Publish

Any validation rules described in the JSON Schema will also be applied automatically by ChilliConnect when attempting to save the item:

Publish

It is also possible to edit the underlying JSON directly:

Publish

Filtering

The "Show Filters" option on the Catalog view can be used to filter and search for specific items in your catalog from the ChilliConnect dashboard:

Filters

Publishing

Catalog changes are always made to a editable version of your Catalog called the Working Copy and are only made visible to your game once they have been published. Publishing an Catalog creates a read-only version of all Catalog items and Custom Types from the current Working Copy.

When a player logs in to your game, their session will always be associated with latest Catalog version so that you can make further changes without affecting in-game sessions. All calls to the Catalog and Economy API methods, including those from Cloud Code, will automatically use the correct version for the player. You can programmatically check what version the current player is associated with by checking the CatalogVersion property returned from the player login API calls, or by calling the GetCatalogVersion API method. To publish a catalog, use "Publish" button in the top right when viewing the Working Copy:

Publish

You can also select a specific version of the Catalog using the version drop down. Items and Custom Types in a published version of the Catalog are not editable.

Publish

Definitions

To retrieve Catalog item definitions within your game, you can use the below API methods:

By checking and storing the version of the Catalog the player session is associated with using GetCatalogVersion, you can use the API methods above to download and locally cache Catalog data on the players device to support off-line play. If you have a large number of Catalog items, you can also download definitions in batch using Catalog Packages

Packages

When a Catalog is published, ChilliConnect will create a package for the Catalog - a zip file that contains separate JSON definitions for each object and Custom Type definition. The zip file can be downloaded and extracted to the players device for locally caching the latest catalog version. To get the Url of the package zip file associated with the currently logged in players session, you can use the GetDefinitionsPackage API method.

From the ChilliConnect dashboard you can also manually download the package when viewing an Catalog version using the button in the top right of the dashboard. The downloaded package can be extracted and bundled with your game build to ensure that a version of the catalog is available for players if they first start the game when offline. The package can also be re-uploaded to the Working Copy using the Import feature to restore a previous version of the Catalog or copy an Catalog from one game to another.

Tags

It is possible to associate each catalog item with a list of comma-separated tags. When The main use case for Tags is grouping different types of Catalog Objects together, so that when searched will return all items with that Tag. For example, tags can be used to group Virtual Purchases together in to specific stores, or to separate inventory items in to different categories.

Importing

Since catalogs have the potential to be become very large, containing possible hundreds of items and currencies, ChilliConnect also allows definitions to uploaded in batch using the catalog import feature. The catalog import takes a zip file containing one or more .json files, with each file containing a single catalog item definition.

Optionally, Custom Types can also be included in an catalog import. If a Custom Type is found, then the import process will assume that all Custom Types for the catalog are contained within the import. If the import contains no Custom Types, then the Custom Types from the base catalog will be used.

Zip Packages and Unreal Mobile Patches can also be included in the Catalog import, but they must reference files that are currently hosted within ChilliConnect - this allows a package zip from one Game to be imported in to another Game. By default, if no Zip Packages or Unreal Mobile Patches are found in the import, existing items in the catalog will be retained.

ImportUpload

Examples showing the required format of the json file for each item type are shown below:

Currency Format

{
    "Type" : "CURRENCY",
    "Name" : "Coins",
    "Key" : "COINS",
    "Tags" : "Grind",
    "Initial" : 10,
    "Max" : 100000,
    "CustomData" : {
        "TexturePath" : "/textures/assets/coins.png"
    }
}

Inventory Item Format

{
    "Type" : "INVENTORYITEM",
    "Name" : "Swords",
    "Key" : "SWORDS",
    "Tags" : "Collectable, Weapons",
    "InitialAllocation" : 1,
    "CustomData" : {
        "Strength" : 10,
        "Durability" : 20
    }
}

Virtual Purchase Format

{
    "Type" : "VIRTUALPURCHASE",
    "Name" : "BuySword",
    "Key" : "SWORDPURCHASE",
    "Tags" : "WeaponShop"
    "OneTimePurchase": true,
    "Costs" : [
        { "ItemKey" : "COINS", Amount : 10 }
    ],
    "Rewards" : [
        { "ItemKey" : "SWORD", Amount : 1 }
    ],
    "CustomData" : {
        "RequiredLevel" : 10
    }
}

Real Money Purchase Format

{
    "Type" : "MONEYPURCHASE",
    "Name" : "BagOfCoins",
    "Key" : "BAGOFCOINS",
    "OneTimePurchase": true,
    "IosID" : "com.chilliconnectgame.bagofcoins",
    "GoogleID" : "com.chilliconnectgame.bagofcoins",
    "AmazonID" : "com.chilliconnectgame.bagofcoins",
    "Rewards" : [
        { "ItemKey" : "COINS", Amount : 100 },
        { "ItemKey" : "DIAMONDS", Amount : 10 }
    ]
}

Currency Conversion Format

{
    "Type" : "CONVERSION",
    "Name" : "CoinsToDiamonds",
    "Key" : "COINSTODIAMONDS",
    "Rules" : [
    { "CurrencyFromKey" : "COINS", "AmountFrom" : 100, "CurrencyToKey" : "DIAMONDS", "AmountTo" : 1 }
    ]
}

Metadata Format

{
    "Type" : "METADATA",
    "Name" : "PlayerLevels",
    "Key" : "PLAYERLEVELS",
    "CustomData" : [ { 
        "Levels" : [
            { "XPRequired" : 1000 },
            { "XPRequired" : 2000 },
            { "XPRequired" : 5000 },
            { "XPRequired" : 10000 }
        ] }
    ]
}

Custom Type Format

{
    "Key": "POWER_UP",
    "Name": "Power Up",
    "Description": "Modifies one of the player base stats",
    "Definition": {
        "type": "object",
        "properties": {
            "icon": {
                "type": "string"
            },
            "affects": {
                "type": "string",
                "enum": [
                    "health",
                    "defense",
                    "stamina"
                ]
            },
            "cooldown": {
                "type": "integer",
                "minimum": 0,
                "maximum": 500
            },
            "modifier": {
                "type": "integer",
                "minimum": 1,
                "maximum": 10
            }
        },
        "required": [
            "icon",
            "affects",
            "modifier"
        ]
    }
}

It's important to note that the import feature will replace the catalog with the items defined in the uploaded zip. Existing items and Custom Types (if provided) will be updated, new items will be added and any item that is defined in the existing catalog but is not part of the import will be deleted. The import preview screen highlight the changes that will be made.

ImportDiff