> For the complete documentation index, see [llms.txt](https://docs.playerpoof.com/playerpoof/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.playerpoof.com/playerpoof/modules/fluctuation.md).

# Fluctuation

## Overview

Automatize your virtual players, let them join and leave your network on their own.

## Configuration

The configuration of this module can be a tricky, so follow this tutorial to know everything you need to use the fluctuation module.

### Fluctuation type

```yaml
# This option how the fluctuation module will acts.
# The options are:
# - ALGORITHM: The poof players will follow a mathematical algorithm.
# - AI: The poof players will fluctuate depending on an AI. (Not yet implemented)
type: "ALGORITHM"
```

This option allows you to choose between two modes, the algorithm mode which is based on a mathematical formula or the AI mode which collect, and reproduce your real players behaviors.

{% hint style="warning" %}
Unfortunately the AI mode is not available yet.
{% endhint %}

### Threshold

This section let you define a virtual players threshold. This feature is not related to the algorithm or AI modes.

So the `minimum` field let you define how much virtual players should be on your server at anytime, the `maximum` one defines a limit, so the fluctuation algorithm stops adding new players when it's reached.

```yaml
# +-------------------------------------------------------------------------+ #
# |                                                                         | #
# |                            THRESHOLD SETTINGS                           | #
# |                                                                         | #
# |     Choose how many players should consistently stay on your server.    | #
# |                                                                         | #
# +-------------------------------------------------------------------------+ #
threshold:
  # This field let you define the minimum amount of virtual players
  # that should stay on your server no matter how many real players are
  # online.
  minimum: 2

  # This field let you define the maximum amount of virtual players
  # that should stay on your server at any time.
  maximum: 20
```

### Generator

As said in the configuration, this section let you chose between using our built-in API and configuring a list of usernames by yourself.

In order to use your own username list, turn the `automatic` field to false and fill the `usernames` list.

```yaml
# +-------------------------------------------------------------------------+ #
# |                                                                         | #
# |                            GENERATOR SETTINGS                           | #
# |                                                                         | #
# |               Define how virtual players name are chosen.               | #
# |                                                                         | #
# +-------------------------------------------------------------------------+ #
generator:
  # If set to true, it will use our api and pick a pre-validated profile from
  # our database. Otherwise, it will pick a username from the list above.
  automatic: true

  # You need to set the 'automatic' field to false in order use this list.
  # You must verify a real profile exists for each username, otherwise,
  # the module will ignore the username.
  usernames:
    - LordKiwix
    - Kore
```

### Algorithm settings

As said previously, the algorithm mode is based on a mathematical formula that use your configuration to knows when to connect or disconnect virtual players to hit a certain total amount of players.

```yaml
# +-------------------------------------------------------------------------+ #
# |                                                                         | #
# |                            ALGORITHM SETTINGS                           | #
# |                                                                         | #
# |               Tweak fluctuation algorithm to fit your needs.            | #
# |                                                                         | #
# +-------------------------------------------------------------------------+ #
algorithm:
  delay:
    minimum: 10
    maximum: 20
  percentage:
    minimum: 2.0
    maximum: 2.5
  asynchronous: false
```

The first section `delay`, allows you to define a delay range (in seconds). This range is basically defines how often the module performs an update. The plugin will pick a random value within that range and wait the specified amount of time.

Then, in the second section `percentage`, you can define a range that represent the percentage of virtual players that will connect to your server automatically. It's not easy to understand at the first look, so let me explain you what I mean.

So by default the configuration set the range from `2.0` to `2.5`, which in reality represent `200%` to `250%`. For the example let's say 5 players are connected on your server, then the fluctuation module will progressively create 5 to 6 virtual players to match the 200% - 250%.

Finally the `asynchronous` option, let you define if the algorithm should work on the bukkit primary thread (synchronously) or on a secondary thread (asynchronously).

### AI settings

{% hint style="warning" %}
As for now, we are still working on the AI feature. 

We hope to release it at the end of May.
{% endhint %}