---
title: "Item"
disqus: hackmd
tags: 'ctrl'
---
## Chapter 4 Item Management

### 4-1 Knowing the Items in the Game

An item is basically a database service that Cloud organized specially for online games, and there are three types according to their uses:

1. Goods
Goods are the treasure or the props in the game, which can be sold in the Cloud market. Players pay arcas (Cloud’s virtual currency) and get the goods, and the arcas will be restored to the developers’ arcas account. Developers can withdraw cash after having a certain number of arcas.
When developers design the game’s program, usually the goods the player owns are shown in the game. Besides, when a player logs in to the Cloud website, the goods he owns in the game can also be looked up.
2. Property
Properties allow program designers to describe some traits a player has in the game, such as height, weight, and so on. Beyond that, it can also be used to represent treasures, props, functions, and more. However, since properties are not for sale, they are not shown in the market. Adding or reading their values are only accessible in the game program with the Cloud API.
Like the goods, once the player logs in to the Cloud website, his properties and contents is all available for searching.

3. Data
The memory that the players store the game data, whose content does not disappear when the player disconnects or shuts down. It is a non-volatile memory that exceeds the local computer.
Since the data are an internal memory, they are completely stored and accessed by the game program. Players will not and do not need to know the content, so they will not be able to search for it after logging in to the Cloud website.

Please be aware that what items the player owns and what the contents are are not set as public for other players. Below are the opennesses of different items for the players and their personal backstages:

| item type | Cloud website’s bakcstage |
|:--------------:|:---------------:|
| Goods | visible |
| Property | visible |
| Data | not visible |

### 4-2 Item Management

An item needs to be defined in the Cloud game management backstage and obtained with its IGUID (Item GUID) to be stored in the game. Creating a new item required filling up the following form:



Here are the explanation for the form columns:

- name
the item’s name
- note
the item’s detailed note
- type
there are three kinds, goods, property, and data
- public
there are two kinds, public or unpublic
- validity
there are three kinds, permanently valid, valid in a fixed period of time, and valid before a fixed date
- item’s attribute
“Item’s attribute” is the pairing between “attribute’s name” and “attribute’s value.” Several attribute data can be set in every item, and when the item is instantiated, the attribute value set here will be the instance item’s preset value. For further explanation on item instance, please refer to the next session.

After creating the item, developers can come back to the item page to check its IGUID, which is a parameter data that calling the Cloud item API needs.

### 4-3 Item-Management Functions

The API functions for managing items are all in the CloudItem class, which is composed of static functions, with neither Constructor nor Property. If program designers need to deal with the items, please call these functions directly.

Next, for the introduced API function, take the `GetItemClass()` from the next session as an example, program designers have to add “CloudItem.” at the beginning. It will look like:

`CloudItem.GetItemClass();`

### 4-4 Obtaining the Data from a Certain Item Class

When developers create an item in the management backstage, its Class is already created. Since the contents of the item classes are the same for all players, the data about the item class that a player gets with an API function are the same. To read an item’s definition data, please use GetItemClass() and here is its definition:

`static void GetItemClass(CloudGame game, string iguid, OnCallCompletionWithData cb, object token)`

Parameter cb is the callback function, which developers need to write by themselves, and here is the function’s definition:

`cb(int code, object data, object token)`

When `GetItemClass()` obtains the item’s definition data successfully, the system will call the callback the developers define and send in a parameter with a 0 `code`. Otherwise, when the work fails, `code` is not 0.

The obtained item data are stored in the callback’s parameter `data` and they have to be cast as `List <Hashtable>` when storing. However, there is only one element in the `List`. The below are the key values in `Hashtable` and they represent items’ definition data:

| Key | Value | Value’s type |
|:-----:|:------------------------------------------------------------------------------------------------------------------------------------------------:|:--------------:|
| iguid | item’s IGUID | string |
| name | item’s name | string |
| desc | item’s name | string |
| type | item’s type 1. goods 2. property 3. data | int |
| now | The format is `yyyy/mm/dd hh:mm:ss` and the timezone is UTC. | string |
| attr |If this item is set without an attribute, the Value is null. 2. The attribute data is key=value and stored as Hashtable. 3. There are two keys in the Hashtable: name attribute’s name and value attribute’s value |

### 4-5 List the Class Data of the Item Class that Is Created

GetItemClass() has another overloading function that can also enumerate the created item class:
static void GetItemClass(CloudGame game,int option, OnCallCompletionWithData cb, object token)

Unlike searching particular item classes by designating IGUID, the difference of values of parameter `option` search up different types of item classes:

| option | item classes |
| :----: | :--------------------------: |
| 0 | all the “property” items |
| 1 | all the “good” items |
| 2 | all the “property” and “goods” items |
| 3 | all the “data” items |

After searching, the item classes’ data will be sent back with a callback function as `List <Hashtable>`. In the list, the elements are the data of every item class. For a more detailed explanation of the format of List and Hashtable, please go to the previous session.

### 4-6 Instance

Item instances are shared by all the players. They are produced with item classes, which means to go through instantiation, to form the items respective players own.

Players can create or delete an item instance and also read or change the attribute data. These operations are only management of the items they own personally, and do not affect other players’ items. We can imagine these item instances as the items’ copies, and the copies players created are owned by respective players themselves, so the players’ copies do not interfere with one another.

(1) Add Item Instance

When players want to own an item instance, they need to create one first. Here is the definition for the function we use:

static void NewItemInstance(CloudGame game, string iguid, OnCallCompletionWirhData cb, object token)

In the function, parameter iguiid is the IGUID of the item one wants to add, and the definition of the callback function is:

void cb(int code, object id, object token)

When the code is 0, it means the item instance is created successfully, and the id is the item instance’s Instance ID. Please cast the id into string. On the other hand, if the code is not 0, the work fails.

Please be aware that the several item instances can be created out of the same item class, and every time NewItemInstance() is called, it creates a new instance. We rely on the item instances’ Istance IDs when distinguishing them, and program designers have to try to store respective item instances’ Instance IDs.

(2) Deleting Item Instance

The function used to delete item instances is:

static void DeleteItemInstance(CloudGame game, string iguid, string id, OnCallCompletion cb, object token)

Parameter `id` is the instance id of the item instance one wants to delete.

The definition of the callback function:

void cb(int code, object token)

When the code is 0, it means the item instance is deleted successfully. However, if the code is not 0, the deleting fails.

(3) Reading Item Instances

Designate the item’s IGUID and the item instance’s Instance ID to read the instance’s attribute data, and the function is:

static void GetItemInstanceAttribute(CloudGame game, string iguid, string id, string attrName,OnCallCompletionWithData cb, object token)

Parameter `id` is the item’s instance id and attrName is the name of the attribute one wants to read.

After processing the function, the triggered callback cb has the following definition:

void cb(int code, object obj, object token)

When the code is 0, the execution succeeds, and when the code is not 0, it fails. If the execution is successful, please case parameter `obj` as `Hashtable`, and the below key values represent the attribute data:

| Key | explanation|
| :---: | :-----------------------------------------------------------: |
| name | the attribute’s name, which is parameter `attrName` |
| value | the attribute’s value |
| stamp | the time this attribute is written |
| now | the current system time of the server, the format is `yyyy/mm/dd hh:mm:ss` and the timezone is UTC |

(4) Change Item Attribute

Changing the item, whose instance is aleady created, requires using the SetIemInstanceAttribute() function instead. Here is what its definition is:

void SetItemInstanceAttribute(CloudGame game, string iguid, string id, string attrName, string attrValue, OnCallCompletion cb, object token)

Parameter `id` is the instance id of the item instance one wants to delete, `attrName` is the name of the attribute one wants to change, and `attrValue` is the value after changing the attribute.

After executing the function, the triggered callback `cb` has the following definition:

void cb(int code, object token)

When the code is 0, it suceeds. When the code is not 0, it fails.

### 4-7 In-App Purchase and In-App Billing

In-App Purchase is the mechanism that allows iOS devices to buy products directly in the apps, and there are two ways:

1. Build-in Product Delivery
This is an unsafe way of trading, so we will skip this.
2. Server Product Delivery
For steps (1) to (9) in the process, developers have to make the program with XCODE, and further information is on the iOS Developer website. After obtaining the trade receipt “receipt-data,” use the server that Cloud provides to execute steps (10) to (14) to examine whether receipt-data is the receipt data for a legal trade.
The examination is simple. All we have to do is calling `CloudShop.CommitInAppPurchase()` and here is its definition:
`public static void CommitInAppPurchase(CloudGame game, string iguid, int type, string receipt, OnCallCompletion cb, object token)`
Parameter `type` designates the way of purchasing. 0 is a sandbox (for testing) and 1 is an actual purchase.

Parameter `receipt` is the trade receipt data that is sent back from App-Store. After the examination, the callback function `cb` will be called, and its definition is:
`void cb(int code)`

When the examination suceeds, `code` is 0；When it does not, the `code` is not 0.
Except for iOS, Android system also has a built-in purchase service. Since the Android market is not specially provided by Apple, unlike iOS, currently Cloud supports the receipt examination service of built-in purchases in the Google Play market, which is officially provided by Google. Developers only need to submit the receipt data, which they get after completing the purchase, with the `CloudShop.CommitInAppBiling()` function, and the system will add an item instance for the goods after examining the receipt and finding no problem. Here is the function’s definition:
`public static void CommitInAppBilling(CloudGame game, string iguid, int type, string receipt, string signature, OnCallCompletion cb, object token)`

Since Google Play sends back the receipt data and the electronic signature data, hand in both of them for the examination because this function has an extra signature function. Other usages are the same as the `CommitInAppPurchase()` function iOS uses.