> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dogebot.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Lists and objects

> Collections (lists) and objects (named keys), for shops, backpacks and settings.

Most variables hold **one thing**, like a number. Sometimes you need **many things** in one box. That's what **Collections** and **Objects** are for.

> **Collection**
>
> A **list**, like a shopping list.
>
> `sword, shield, potion`

> **Object**
>
> A **card with labelled boxes**, like settings.
>
> `prefix: !`, `color: #F5C842`

> [!NOTE]
>
> New to all this? You can build almost everything with **Number**, **Text** and **User** variables. Come back to Collections and Objects when you feel ready.

## Collections (lists)

A **Collection** is a list, like a shopping list:

```text theme={null}
sword, shield, potion
```

Use a Collection for things like a list of bad words, a list of prizes, a list of people who joined a giveaway, or a shop.

Each thing in the list is an **item**. Items can be plain words, or they can have **keys**, like a shop where each item has a name, a price and a stock:

| name | price | stock |
| - | - | - |
| Potion | 50 | 10 |
| Sword | 200 | 3 |

### Change a list with Save a value

Pick a Collection variable in the **Save a value** block and you get a **Collection Operation** menu:

> **Add things**
>
> | Operation | What it does |
> | - | - |
> | **Push value to end** | Adds a thing to the end of the list |
> | **Push value to front** | Adds a thing to the start |
> | **Add item** / **Add item to front** | Adds an item with keys. Write `name=Potion, price=50`, one per line, or JSON |

> **Change things**
>
> | Operation | What it does |
> | - | - |
> | **Set value at position** | Changes the thing at a place (the first place is 1) |
> | **Edit item at position** | Changes some keys on one item, like `price=60` |
> | **Edit items where** | Changes every item whose key matches, like where `name` equals `Potion` set `stock=0` |
> | **Sort by key** | Puts the list in order, lowest or highest first |
> | **Replace with JSON** | Swaps the whole list for a new one |

> **Take things out**
>
> | Operation | What it does |
> | - | - |
> | **Remove first value** / **Remove last value** | Takes the first or last thing out |
> | **Remove value at position** | Takes out the thing at a place |
> | **Remove value in collection** | Takes out every copy of a thing, like `potion` |
> | **Remove items where** | Takes out every item that matches |
> | **Clear collection** | Empties the whole list |

### Read a list

| Type this | You get |
| - | - |
| `{DBVAR_bag}` | The whole list |
| `{DBVAR_bag.length}` | How many things are in it |
| `{DBVAR_bag.first}` / `{DBVAR_bag.last}` | The first or last thing |
| `{DBVAR_bag.0}` | The thing at place 0 (**places start at 0 here**) |
| `{DBVAR_bag.random}` | A random thing |
| `{DBVAR_bag.join[, ]}` | Everything, with a comma between |
| `{DBVAR_bag.has[potion]}` | `true` if it has a potion |
| `{DBVAR_bag.count[potion]}` | How many potions |
| `{DBVAR_bag.each[$number. $value\n]}` | A numbered list, one per line |
| `{DBVAR_shop[name=Potion].price}` | The price of the Potion item |
| `{DBVAR_shop.sum.price}` | All the prices added up |
| `{DBVAR_shop.each[**$name**: $price coins\n]}` | A shop list with names and prices |

In `.each[...]`, `$value` is the thing, `$number` counts 1, 2, 3, and `$name`, `$price` (any key) read that key of the item. `\n` means a new line.

> [!WARNING]
>
> Watch the places. In **Save a value** (Set value at position, Remove value at position) the first place is **1**. When you **read** with `{DBVAR_bag.0}`, the first place is **0**.

> [!TIP]
>
> Want to do something for **every** item, like give each one a button? Use the **Repeat** block with **Each item in a list**. While it runs, `{item}` is the current item and `{loop_number}` is which turn it is on. See [Repeats and waiting](/building-with-blocks/repeats-and-waiting).

## Objects (named keys)

An **Object** is like a card with labelled boxes on it. Each box has a name (a **key**) and holds something:

```text theme={null}
prefix: !
log-channel: 1234567890
color: #F5C842
```

Perfect for **settings**, profiles, shops and inventories. Instead of making three variables, you make **one** and keep everything together.

### Change an object with Save a value

In **Save a value**, pick an Object variable and choose an **Object Operation**:

| Operation | What it does |
| - | - |
| **Set a key** | Writes a value under one key, like `prefix` = `!` |
| **Get a key** | Reads one key into a value for this run, for example as `{my_coins}` |
| **Remove a key** | Deletes one key |
| **Remove every key** | Empties the whole object |

The block on the canvas then says what it does, for example **Remove shop.coins**, so you can read your canvas at a glance.

### Read a key

Put a dot and the key name after the variable:

```text theme={null}
Prefix: {DBVAR_settings.prefix}
```

### Starting properties

When you make an Object variable (or a User variable that stores an Object), you can add **Starting properties**: the named values every new entry begins with. Press **Add property** to add one.

For example, add `coins = 0`, `gems = 0` and `title = Newbie`. Now every new member starts with exactly those boxes filled in.

You can set Starting properties in the builder's **Create New Variable** window and on the Database page.

### Objects for every member

A **User** variable can also store an object, so each member has their own card, like `{DBVAR_pet.name}` and `{DBVAR_pet.happiness}`. In **Save a value** or **Do the maths**, fill in the **Key** box to change just one part.

```text theme={null}
{DBVAR_profile.coins} coins, {DBVAR_profile.gems} gems
```

## Example: a tiny shop

**1. Make the variable**

Make a **Collection** variable called `shop`.

**2. Fill it**

In a **Save a value** block, pick `shop`, choose **Add item** and write `name=Potion, price=50`.

**3. Show it**

In `/shop`, add a **Reply** with:

```text theme={null}
Shop
{DBVAR_shop.each[- **$name**, $price coins\n]}
```

For the full buy-and-sell version, see [A shop with items](/build-real-systems/a-shop-with-items).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.