# Attributes

## What are Attributes?

Attributes are key-value pairs that can be assigned to individual Marble items to represent any kind of numerical value associated with an item. Since attributes are attached to individual items they will travel with changes in ownership.

Below are a few sample Attributes and their associated point values. 

| Attribute Name | Attribute Points |
| -------------- | ---------------- |
| level          | 5                |
| experience     | 750              |
| strength       | 18               |
| height         | 74               |
| bananas        | 3                |
| modifier       | -5               |

{% hint style="info" %}
Note that Attributes have specific actions that allow the point values to be manipulated directly, as opposed to Tags that can only be overwritten.
{% endhint %}

## Shared Attributes

The Attributes layer also includes Shared Attributes that are assigned to a group rather than an individual item. Use Shared Attributes to apply attributes to all items in a group or to save RAM costs.

## Table Breakdown

**Table Name:** `attributes`

**Table Scope:** `item.serial`

| Field Name      | Field Type | Description                              |
| --------------- | ---------- | ---------------------------------------- |
| attribute\_name | name       | Attribute name identifier (Primary Key). |
| points          | uint64\_t  | Point value for attribute.               |
| locked          | bool       | Attribute locked state.                  |

#### No extra indices.

## Creating an Attribute

To assign a new attribute to an Item call the `newattribute()` action.

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

### Action Parameters

| Name            | Type      | Example | Description                                                 |
| --------------- | --------- | ------- | ----------------------------------------------------------- |
| serial          | uint64\_t | 5       | The serial number of the Item to be assigned the attribute. |
| attribute\_name | name      | health  | The name of the new attribute to assign.                    |
| initial\_points | int64\_t  | true    | The initial points value the attribute will start with.     |
| shared          | bool      | true    | Create shared attribute if true.                            |

### Examples

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

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

{% endtab %}

{% tab title="Marble CLI" %}

```
marble make attribute ...
```

{% endtab %}
{% endtabs %}

## Set Attribute Points

To set an attribute's points to a specific value call the `setpoints()` action.

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

### Action Parameters

| Name            | Type      | Example | Description                                                 |
| --------------- | --------- | ------- | ----------------------------------------------------------- |
| serial          | uint64\_t | 5       | The serial number of the item with the attribute to affect. |
| attribute\_name | name      | health  | The name of the attribute to affect.                        |
| new\_points     | int64\_t  | 25      | The new point value of the attribute.                       |
| shared          | bool      | true    | Set points for a shared attribute if true.                  |

### Examples

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

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

{% endtab %}

{% tab title="Marble CLI" %}

```
marble modify ...
```

{% endtab %}
{% endtabs %}

## Increase Points

To increase an attribute's points call the`increasepts()` action.

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

### Action Parameters

| Name            | Type      | Example | Description                                                  |
| --------------- | --------- | ------- | ------------------------------------------------------------ |
| serial          | uint64\_t | 5       | The serial number of the Item with the attribute to affect.  |
| attribute\_name | name      | health  | The name of the attribute to affect.                         |
| points\_to\_add | uint64\_t | 10      | The number of points to add to the current attribute points. |
| shared          | bool      | false   | Increase points for a shared attribute if true.              |

### Examples

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

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

{% endtab %}

{% tab title="Marble CLI" %}

```
marble modify ...
```

{% endtab %}
{% endtabs %}

## Decrease Points

To decrease an attribute's points call the `decreasepts()` action.

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

### Action Parameters

| Name                 | Type      | Example | Description                                               |
| -------------------- | --------- | ------- | --------------------------------------------------------- |
| serial               | uint64\_t | 5       | The serial number of the Item to affect.                  |
| attribute\_name      | name      | health  | The name of the attribute to affect.                      |
| points\_to\_subtract | uint64\_t | 10      | The number of points to subtract from the current points. |
| shared               | bool      | true    | Decrease points of shared attribute if true.              |

### Examples

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

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

{% endtab %}

{% tab title="Marble CLI" %}

```
marble modify ...
```

{% endtab %}
{% endtabs %}

## Lock an Attribute

Lock an attribute and prevent future updates with the `lockattr()` action.

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

### Action Parameters

| Name            | Type      | Example | Description                                              |
| --------------- | --------- | ------- | -------------------------------------------------------- |
| serial          | uint64\_t | 5       | The serial number of the Item with the behavior to lock. |
| attribute\_name | name      | level   | The name of the attribute to lock.                       |
| shared          | bool      | true    | Lock a shared attribute if true.                         |

### Examples

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

```
cleos push action {account} lockattr '[ ... ]' -p {account}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble lock ...
```

{% endtab %}
{% endtabs %}

## Remove an Attribute

To remove an attribute from an Item call the `rmvattribute()` action.

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

### Action Parameters

| Name            | Type      | Example | Description                                                 |
| --------------- | --------- | ------- | ----------------------------------------------------------- |
| serial          | uint64\_t | 5       | The serial number of the Item with the attribute to remove. |
| attribute\_name | name      | health  | The name of the attribute to remove.                        |
| shared          | bool      | false   | Remove a shared attribute if true.                          |

### Examples

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

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

{% endtab %}

{% tab title="Marble CLI" %}

```
marble remove ...
```

{% endtab %}
{% endtabs %}