# 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 %}


---

# 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/fluctuation.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.