# Auctions

## Overview

This module give the ability to your virtual players to create auctions and buy real players items. You can define a list of items and a percentage of players who will auction these items. You can also define a delay between each auction, making the auctions house much more natural.

## Configuration

The configuration of the auction module is a bit complex, so follow this step by step tutorial to become an expert and have a flawless experience.

### Sell settings

```yaml
# +-------------------------------------------------------------------------+ #
# |                                                                         | #
# |                               SELL SETTINGS                             | #
# |                                                                         | #
# |     Define which items your poof players can sell and their prices.     | #
# |                                                                         | #
# +-------------------------------------------------------------------------+ #
sell-settings:

  enabled: true

  # This option defines the chance of
  # a poof player selling an item.
  chance: 30

  delay:
    minimum: 10
    maximum: 60

  items:
    diamond:
      material: "DIAMOND"
      amount: 1
      name: "&b&lDiamond"
      lore:
        - "&7A shiny diamond!"
        - "&7This item was placed by a poof player."
      price:
        minimum: 100
        maximum: 250
    netherite-chestplate:
      material: "NETHERITE_CHESTPLATE"
      amount: 1
      enchantments:
        PROTECTION_ENVIRONMENTAL: 4
        THORNS: 3
        UNBREAKING: 3
        MENDING: 1
      price:
        minimum: 500
        maximum: 1500
```

Let's start by the `chance` field, this field defines how many chance a poof players has to sell an item. It's a percentage so it must be within 0 and 100.

The `delay` section let you defines how often the buy task should run, which means how often the players will start new auctions.

Now, the big part, the `items` section. This is the place where you define which items poof players can sell and at which price.

Each item must have the `price` section, each time a poof players starts an auction, they will pick a random price within this range.

{% hint style="danger" %}
The only attribute requires is material!
{% endhint %}

There is the list of attributes an item can have:

* amount
* name
* lore
* custom-model-data
* enchantments
* flags
* unbreakable

All this attributes are indeed optional but can help you within your configuration journey.

### Buy settings

```yaml
# +-------------------------------------------------------------------------+ #
# |                                                                         | #
# |                               BUY SETTINGS                              | #
# |                                                                         | #
# |               Choose how your virtual players buys items.               | #
# |                                                                         | #
# +-------------------------------------------------------------------------+ #
buy-settings:
  enabled: true

  # Available types:
  # | - buy
  # | - bid (not supported by all plugins)
  type: 'buy'

  # Available strategies:
  # | - random
  # | - highest
  # | - average
  # | - lowest
  # | - newest
  # | - oldest
  # | - budget
  # | - fixed
  strategy: "random"

  # This option defines the chance of
  # a poof player buying an item.
  chance: 15

  # This option defines the delay between
  # each poof player buy.
  delay:
    minimum: 5
    maximum: 15

  # This category defines the price range
  # of the items that your poof players
  # will buy.
  #
  # Only works with the 'budget' strategy.
  budget:
    minimum: 100
    maximum: 500

  # This option defines the different
  # items that your poof players will
  # buy.
  fixed:
    items:
      1:
        material: "DIAMOND"
        amount: 1
        name: "&b&lDiamond"
        lore:
          - "&7A shiny diamond!"
          - "&7This item was placed by a poof player."
        price:
          minimum: 100
          maximum: 250
      2:
        material: "NETHERITE_CHESTPLATE"
      3:
        material: "NETHERITE_CHESTPLATE"
        enchantments:
          PROTECTION_ENVIRONMENTAL: 4
          THORNS: 3
          UNBREAKING: 3
          MENDING: 1
```

Let's start by the `type`  field, you can set it to `buy` or `bid`. The difference between both is, if you plugin supports bids, it'll make a bid if the field is turned to bid instead of instantly buying it.

Then, the `strategy` field allows you to define how the poof players are going to select the auction item they wants to buy. All strategies are self-explanatory but the budget and fixes ones that are explain below.

The `chance` field let you define how many chances the poof players have to buy an item when they found it. It's a percentage so it must be within 0 and 100.

The `budget` section is defining a budget range for the budget buy strategy, so the poof players will seek items to buy within this price range.

The `fixed` section defines the items the poof players will be able to buy with the fixed strategy. Items can be configured just for the sell section, the only difference is that the price range is totally optional.


---

# 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://docs.playerpoof.com/playerpoof/modules/auctions.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.