# Project Essentials Cooldown

This module is responsible for cooldown Minecraft commands. The mod adds a delay for the use of commands, prevents command-spamming and limits the number of uses for a certain time. A mod can also create cooldown for command aliases. The delay and other settings are controlled by the configuration of the mod. Useful information and documentation are [here](https://github.com/ProjectEssentials/ProjectEssentials-Cooldown/blob/MC-1.14.4/documentation/for-developers.md).

You can also use the API, for example, as a delay in the use of an item or the like, but instead of commands, you can use identifiers. (This is one of the ideas for use by third-party developers).

## How to Install

For start the modification, you **need installed Forge**, it is desirable that the version matches the supported versions. You can download Forge 1.14.4 from the [link](https://files.minecraftforge.net/maven/net/minecraftforge/forge/index_1.14.4.html) and Forge 1.15.2 from it [link](https://files.minecraftforge.net/maven/net/minecraftforge/forge/index_1.15.2.html). Move the downloaded mod to the `mods` folder (*installation example below*).

```
val MV = valueOf(your_minecraft_version)

.
├── assets
├── config
├── libraries
├── mods (that's how it should be)
│   ├── Project Essentials Core-MOD-1.MV.X-1.X.X.jar (mandatory)
│   ├── Project Essentials Permissions-1.MV.X-1.X.X.jar (recommended)
│   └── Project Essentials Cooldown-1.MV.X-1.X.X.jar
└── ...
```

### **Dependencies**

Also **do not forget** to install dependencies, only two types of dependencies: **mandatory** (*game will not start without a mod*) and **recommended** (*without a mod, game can start, but I recommend using it*).

#### **Download dependencies**: [Core](https://github.com/ProjectEssentials/ProjectEssentials-Core) · [Permissions](https://github.com/ProjectEssentials/ProjectEssentials-Permissions)

### Final step

Now try to start the game, go to the `mods` tab, if this modification is displayed in the `mods` tab, then the mod has been **successfully installed.**

## Commands

| Name               | Permission            | Op level | Description                                           |
| ------------------ | --------------------- | -------- | ----------------------------------------------------- |
| `/cooldown`        | `ess.cooldown`        | `4`      | Print in chat cooldown version and other information. |
| `/cooldown save`   | `ess.cooldown.save`   | `4`      | Save cooldown configuration.                          |
| `/cooldown reload` | `ess.cooldown.reload` | `4`      | Reload cooldown configuration without saving.         |

## Permissions

`ess.cooldown.bypass` - for bypassing cooldown.

## Configuration

### Configuration location

```
.minecraft/config/ProjectEssentials/cooldowns.json
```

### Configuration documentation

#### `CommandCooldowns` configuration section.

`CommandCooldowns` contains an array of command cooldowns, each element of the array (cooldown) must have the `command name` and `cooldown value`; it looks like "heal:10" where heal it command and 10 it command cooldown (in seconds).

{% hint style="info" %}
Also, if you need set common cooldown for any command, just use literals "\*", "all", "any", i.e "any:5", where any random command and 5 it command cooldown (in seconds).
{% endhint %}

#### `IgnoredPlayers` configuration section.

`IgnoredPlayers` contains an array of player nicknames; Just it contain players what not get restrictions on the use of commands.

### Just in case

If something goes according to the cunt, and your configuration flies, just delete the configuration or take the default configuration from here.

**Default configuration:**

```javascript
{
  "CommandCooldowns": [],
  "IgnoredPlayers": []
}
```

## **Applying aliases**

When you register your command with aliases, for cooldowns you need register aliases for cooldown api, just make it:

```kotlin
CommandAliases.aliases["mycommand"] = mutableListOf("mcmd", "mycommandalias")
```

## Cooldown as Dependency

### Dev. Dependencies 1.14.4

```
    - kotlin-std lib version: 1.3.61
    - kotlinx serialization version: 0.14.0
    - forge version: 1.14.4-28.1.114
    - brigadier version: 1.0.17
    - target jvm version: 1.8
```

### Dev. Dependencies 1.15.2

```
    - kotlin-std lib version: 1.3.61
    - kotlinx serialization version: 0.14.0
    - forge version: 1.14.4-31.1.1
    - brigadier version: 1.0.17
    - target jvm version: 1.8
```

### Get as Dependency

{% hint style="warning" %}
 :: For Forge 1.14.4 only ::
{% endhint %}

```groovy
repositories {
    maven { url("https://jitpack.io") }
}

dependencies {
    compile(
        group: "com.github.projectessentials",
        name: "ProjectEssentials-Cooldown",
        version: "v1.14.4-1.+"
    )
}
```

{% hint style="warning" %}
 :: For Forge 1.15.2 only ::
{% endhint %}

```groovy
repositories {
    maven { url("https://jitpack.io") }
}

dependencies {
    compile(
        group: "com.github.projectessentials",
        name: "ProjectEssentials-Cooldown",
        version: "v1.15.2-1.+"
    )
}
```

## API Documentation

@ todo: make in-table documentation instead code blocks. (*If I forgot about this, please remind me of this in issue*)

```
CooldownAPI.DEFAULT_COOLDOWN

- description: Default command cooldown (in seconds).

- note: it value be using as callback, e.g if cooldown value is invalid.
```

```
CooldownAPI.defaultCooldownLiterals

- description: Default cooldown literals. It literals what replaced cooldowns for any command in game, i.e if you set in config all=10, then all commands be with cooldown 10 sec.

- note: it not override existing cooldown for some command.
```

```
CooldownAPI.addCooldown

- description: Just add new or replace cooldown for target player and for target command.

- accepts:
    - nickname - nickname of target player. (string)
    - command - target command for cooldown (string)
```

```
CooldownAPI.removeCooldown

- description: Just remove existing cooldown from target player and target command.

- accepts:
    - nickname - nickname of target player. (string)
    - command - target command for cooldown (string)
```

```
CooldownAPI.getCooldownIsExpired

- accepts:
    - nickname - nickname of target player. (string)
    - command - target command for cooldown (string)
    - minSecondsDuration - minimal seconds diff between old command execute and new command execute. (int)

- return: true if command cooldown expired, else return false. (boolean)
```

```
CooldownAPI.getCooldownTimeLeft

- accepts:
    - nickname - nickname of target player. (string)
    - command - target command for cooldown (string)

- return: left cooldown time in seconds for command. (double)
```

```
CommandsAliases.aliases

- description: stores all aliases, just add your alias here.

- note: Where `String` - command for aliases; Where `MutableList<String>` - aliases of command.
```

## If you have any questions or encounter a problem, be sure to open an [issue](https://github.com/ProjectEssentials/ProjectEssentials-Cooldown/issues/new/choose)


---

# 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://mairwunnx.gitbook.io/project-essentials/project-essentials-cooldown.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.