# Items

## What are Digital Items?

Digital Items are individual, ownable objects stored by the Marble contract. A Digital Item can represent anything from a trading card to a deed of ownership to an in-game spaceship. 

Upon creation, every Item is given a unique contract-wide serial number used to identify it among all other Items in the contract. 

Ownership of an Item can be proven by controlling the account that owns a given Item. Every Item also belongs to one and only one Group, which dictates the different kinds of behaviors the Item can perform.

## Behavior Rules

Items follow the behavior rules set by their respective groups. For example, if an Item belongs to a group whose `transfer` behavior is set to false, then the Item is not transferrable. If the group manager were to activate transferability with the `toggle()` action, the Item would become transferrable. See the Behaviors section for more information on behaviors.

## Table Breakdown

**Table Name:** `items`

**Table Scope:** `self`

| Field Name | Field Type | Description                                     |
| ---------- | ---------- | ----------------------------------------------- |
| serial     | uint64\_t  | Contract-wide Item serial number. (Primary Key) |
| group      | name       | Group name identifier.                          |
| owner      | name       | Account that owns the Item.                     |

#### Additional Indices

`bygroup`, `byowner`

## Mint New Item

To create a new Item, call the `mintitem()` action on your Marble contract.

**Required Authority:** `group.manager`

### Action Parameters

| Name  | Type | Example      | Description                                       |
| ----- | ---- | ------------ | ------------------------------------------------- |
| to    | name | testaccount1 | The recipient account that will own the new Item. |
| group | name | group1       | The group the new Item will belong to.            |

### Examples

{% tabs %}
{% tab title="Cleos" %}

```
cleos push action {account} mintitem '[ {params} ]' -p {manager}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble make item ...
```

{% endtab %}
{% endtabs %}

## Transfer an Item

To transfer an Item, call the `transferitem(`) action on your Marble contract.

{% hint style="warning" %}
All items included in the transfer must be owned by the "from" account to be a valid transfer.
{% endhint %}

**Required Authority:** `item.owner`

**Notified Accounts:** `from`, `to`

### Action Parameters

| Name    | Type               | Example       | Description                                  |
| ------- | ------------------ | ------------- | -------------------------------------------- |
| from    | name               | testaccount1  | Account name of sender.                      |
| to      | name               | testaccount2  | Account name of recipient.                   |
| serials | vector\<uint64\_t> | \[5, 6, 8, 9] | The serial numbers of the Items to transfer. |
| memo    | string             | "Thank You!"  | An optional memo field.                      |

### Examples

{% tabs %}
{% tab title="Cleos" %}

```
cleos push action {account} transferitem '[ {params} ]' -p {owner}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble item transfer ...
```

{% endtab %}
{% endtabs %}

## Activate an Item

Items can be activated with the `activateitem()` action. Developers can interpret what activations do in reference to their own applications. Items can be activated any number of times.

**Required Authority:** `item.owner` and `group.manager`

### Action Parameters

| Name   | Type      | Example | Description                            |
| ------ | --------- | ------- | -------------------------------------- |
| serial | uint64\_t | 5       | Serial number of the Item to activate. |

### Examples

{% tabs %}
{% tab title="Cleos" %}

```
cleos push action {account} activateitem '[ {params} ]'
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble item activate ...
```

{% endtab %}
{% endtabs %}

## Consume an Item

Some Items can be consumed by the owner. Consumable Items will be destroyed after consumption. Developers determine what Item consumption translates to in their projects.

**Required Authority**: `item.owner`

### Action Parameters

| Name   | Type      | Example | Description                           |
| ------ | --------- | ------- | ------------------------------------- |
| serial | uint64\_t | 5       | Serial number of the Item to consume. |

### Examples

{% tabs %}
{% tab title="Cleos" %}

```
cleos push action {account} consumeitem '[ {params} ]' -p {owner}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble item consume
```

{% endtab %}
{% endtabs %}

## Destroy an Item

&#x20;To destroy an Item, call the `destroyitem()` action on your Marble contract.

**Required Authority:** `group.manager`

### Action Parameters

| Name   | Type      | Example             | Description                       |
| ------ | --------- | ------------------- | --------------------------------- |
| serial | uint64\_t | 5                   | Serial number of Item to destroy. |
| memo   | string    | "Destroying Item 5" | Optional memo                     |

### Examples

{% tabs %}
{% tab title="Cleos" %}

```
cleos push action {account} destroyitem '[ {params} ]' -p {manager}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble item destroy ...
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://craig-branscom.gitbook.io/marble-docs/contract-standard/marble-core/items.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.