# Step

This module aims to record player statistics when they reach significant milestones on your server. The goal is to analyze player progression and understand the actions they take to achieve these milestones.

When a step (**milestone**) is reached, all player statistics are saved, including blocks mined, items used, and entities killed. You can also add your own data using the API.

Currently, zEssentials does not provide tools for data analysis. Therefore, you must create your own analysis tools or directly examine the database.

To save a player's step, execute the command `/step <player> <milestone name>`. All steps must be registered in the module's `config.yml` file.

Data is stored in JSON format, allowing for easy manipulation by other plugins or websites.

## Configuration

### `config.yml`

```yaml
########################################################################################################################
#
# ░██████╗████████╗███████╗██████╗░░██████╗
# ██╔════╝╚══██╔══╝██╔════╝██╔══██╗██╔════╝
# ╚█████╗░░░░██║░░░█████╗░░██████╔╝╚█████╗░
# ░╚═══██╗░░░██║░░░██╔══╝░░██╔═══╝░░╚═══██╗
# ██████╔╝░░░██║░░░███████╗██║░░░░░██████╔╝
# ╚═════╝░░░░╚═╝░░░╚══════╝╚═╝░░░░░╚═════╝░
#
# Documentation: https://zessentials.groupez.dev/modules/steps
#
########################################################################################################################

enable: true

steps:
  - name: "step-1"
  - name: "step-2"
  - name: "step-3"
  - name: "step-4"
```

## API

### Create a CustomStep

To create a custom step, you must use the `CustomStep` interface. You need to return a `Map` containing all your information.

{% code fullWidth="true" %}

```java
package fr.maxlego08.example.steps;

import fr.maxlego08.example.api.dto.ShopLogDTO;
import fr.maxlego08.essentials.api.steps.CustomStep;
import fr.maxlego08.example.CorePlugin;
import org.bukkit.entity.Player;

import java.util.ArrayList;
import java.util.Date;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class ShopStep implements CustomStep {

    private final CorePlugin plugin;

    public ShopStep(CorePlugin plugin) {
        this.plugin = plugin;
    }

    @Override
    public String getServiceName() {
        return "shop";
    }

    @Override
    public Map<String, Object> register(Player player, Date date) {

        var shops = this.plugin.getStorageManager().getShops(player.getUniqueId(), date);
        if (shops.isEmpty()) return Map.of();

        Map<String, Object> results = new HashMap<>();
        for (ShopLogDTO shop : shops) {

            List<Map<String, Object>> elements = (List<Map<String, Object>>) results.computeIfAbsent(shop.material(), k -> new ArrayList<>());
            elements.add(Map.of(
                    "material", shop.material(),
                    "amount", shop.amount(),
                    "price", shop.price(),
                    "action", shop.action(),
                    "date", shop.created_at().getTime()
            ));
        }

        return results;
    }
}

```

{% endcode %}

This example retrieves logs from a shop plugin based on a date and a player. We will then save the information about each item sold or purchased into a map.


---

# 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://zessentials.groupez.dev/modules/step.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.