### Start Local Development Server

Source: https://github.com/booksaw/betterteams/blob/master/wiki/README.md

Run this command in the `/wiki` directory to start a local development server for testing changes.

```bash
npm start
```

--------------------------------

### Example extension.yml Configuration

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/Extensions-Intro.md

Define metadata for your BetterTeams extension, including name, main class, version, and dependencies.

```yaml
# [Mandatory] The unique name of the extension
name: MyFirstExtension

# [Mandatory] The fully qualified path to your main class
main: com.example.betterteams.MyFirstExtension

# [Optional] The version of the extension (uses Maven filtering)
version: ${project.version}

# [Optional] The author of the extension
author: ADeveloper

# [Optional] A short description of what the extension does
description: An example extension that demonstrates the BetterTeams API.

# [Optional] The website for the extension (e.g., GitHub link)
website: https://github.com/booksaw/BetterTeams

# [Optional] List of other BetterTeams EXTENSIONS required to run
depend: []

# [Optional] List of other BetterTeams EXTENSIONS that are optional
softdepend: []

# [Optional] List of Bukkit PLUGINS required to run (e.g., Vault, WorldGuard)
plugin-depend: []

# [Optional] List of Bukkit PLUGINS that are optional
plugin-softdepend: []
```

--------------------------------

### Placeholder Format Example

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/extensions-mesages.md

Example of defining placeholders in messages.yml and using them with dynamic values during message sending.

```yaml
player:
  joined: "&a{player} joined team {team}!"
```

--------------------------------

### Placeholder Usage Example

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/extensions-mesages.md

Demonstrates how to use placeholders when sending messages, providing key-value pairs for dynamic content replacement.

```java
getMessages().send(player, "player.joined", "player", "Steve", "team", "Warriors");
```

--------------------------------

### Configure Team Level 3

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/04-configuration/Team-Levels.md

Example configuration for team level 3. The 'price' can be set in 's' (score) or 'm' (money).

```yaml
   l3:
      # Price is determined for all levels aside level 1,
      # - If this value ends with 's' it will take score from the team
      # - If this value ends with 'm' it will take money from the team balance
      price: 500s
      teamLimit: 25
      maxChests: 5
      maxWarps: 5
```

--------------------------------

### Command Permissions Configuration

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/03-permissions/Team-Permissions.md

Example of how a command's permissions are defined in the configuration file. Use `enabled` to control command availability and `rank` to set access restrictions.

```YAML
command:
  enabled: true
  rank: ADMIN
```

--------------------------------

### Score Configuration Example

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/07-Score.md

This YAML snippet shows how to configure score-related settings. Adjust values for `purgeCommands`, `autoPurge`, `spamThreshold`, `events` (death and kill scores), and `minScore` to customize the scoring system.

```yaml
# All settings depending on the score aspect of this plugin
# For integrations of other plugins with score see the bottom section of the config


# This is a list of commands which are run by the console before a purge occurs
# A purge is where all teams scores are reset to 0
# If this is left blank, no commands will be run before a purge occurs
# You can use placeholders from placeholder API, though the player is set to be null (so things like %betterteams_team% will not work) 
#    the main reason for the placeholders is so you can use %betterteams_score_{rank}% to refrence a player on the leaderboard
#
# Possible values: [Any command valid on your server]
purgeCommands:
- 'give @a minecraft:dirt 1'

# This is used to track when the next purge should occur. This is a list of dates where a purge will be run 
# If this list is left blank, no purges will occur
# these dates must be in order of ealiest to latest
#
# Possible values: [{dateOfMonth}:{Hour of day}]
autoPurge:
#- '1:6'
# This will purge the users score at 6am on the first of every month

# The amount of time after an event occurs that repeat events are classed as spam
# This is in seconds
# Recognising spam is useful as it means players cannot spam kill 1 person to get score, this means you can give spam kills reduced score 
# - The spam kill tracker is unique to every event, so dying will not activate the spam timer on kills
#
# Possible values: [Any whole number, 0 to disable]
spamThreshold: 60

# MAKE SURE YOU READ SPAM THRESHOLD COMMENTS ABOVE
# If something happens on your server you want to influence score is not listed below, make a request for it here: https://github.com/booksaw/BetterTeams/issues/new/choose

# Score changes for when a player dies
events:
   death:
      score: 0
      spam: -1

# Score changes for when a player kills another player
   kill:
      score: 1
      spam: 0

# The minimum score a team can have
#
# Possible values: [Any whole number]
minScore: 0

```

--------------------------------

### Getting Messages

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/extensions-mesages.md

Demonstrates how to retrieve messages using the getMessages() function, including retrieving specific messages by key and retrieving messages with a prefix.

```APIDOC
## Getting Messages

### Description
Retrieves messages from the translation system.

### Usage
```java
getMessages().get("welcomePath");
getMessages().get("player.joined", "player", "Steve", "team", "Warriors");
getMessages().getWithPrefix("welcome");
```
```

--------------------------------

### Get Team by Name

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/API-intro.md

Retrieve a Team object by its name. Use with caution as team names can be changed.

```java
Team.getTeam(String teamName)
```

--------------------------------

### Get Messages using Message Manager

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/extensions-mesages.md

Retrieve messages using the getMessages() function. Supports direct key retrieval and retrieval with parameters for dynamic content.

```java
getMessages().get("welcomePath");
```

```java
getMessages().get("player.joined", "player", "Steve", "team", "Warriors");
```

```java
getMessages().getWithPrefix("welcome");
```

--------------------------------

### Get Team by UUID

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/API-intro.md

Retrieve a Team object using its UUID. This is the recommended method for storing team references as UUIDs are constant.

```java
Team.getTeam(UUID teamUUID)
```

--------------------------------

### Get Team by Player

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/API-intro.md

Retrieve the Team object associated with a player. Returns null if the player is not in a team.

```java
Team.getTeam(Player player)
```

--------------------------------

### Response Handling

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/extensions-mesages.md

Illustrates how to construct responses for commands, indicating success or failure and including translated messages.

```APIDOC
## Response Handling

### Description
Constructs responses for commands, indicating success or failure with translated messages.

### Usage
```java
return getMessages().response(true, "command.success");
return getMessages().response(false, "error.no-permission");
return getMessages().response(true, "command.done", "player", "Steve");

// or:
return new CommandResponse(getMessages().toStatic("command.success"));
```
```

--------------------------------

### Placeholder Format

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/extensions-mesages.md

Explains the format for placeholders within messages.yml files and how to use them when sending messages.

```APIDOC
## Placeholder Format

### Description
Defines the format for placeholders in messages and provides an example of their usage.

### Placeholder Format
Placeholders use `{key}` format in messages.yml:
```yaml
player:
  joined: "&a{player} joined team {team}!"
```

### Usage
```java
getMessages().send(player, "player.joined", "player", "Steve", "team", "Warriors");
```

### Result
`Steve joined team Warriors!`
```

--------------------------------

### Add BetterTeams Maven Repository

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/Extensions-Intro.md

Configure your Maven project to include the Jitpack repository to access BetterTeams.

```xml
<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>
```

--------------------------------

### YAML Configuration for Team Level Price (Money)

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/04-configuration/Team-Levels.md

Sets the cost to upgrade a team to the next level using team balance. The 'm' suffix indicates that the price is in money, which will be deducted from the team's balance.

```yaml
price: 100m
```

--------------------------------

### Configure Cost Source

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/04-configuration/Command-Cost-and-Cooldown.md

Determine whether command costs are deducted from the team balance first or the individual player's balance. Set to 'true' to prioritize team balance.

```yaml
# This option determines if the command cost is taken from the team balance first or the individual player
#
# Possible values: [true, false]
costFromTeam: true
```

--------------------------------

### Builder for Complex Messages

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/extensions-mesages.md

Demonstrates the use of a builder pattern to construct complex messages with placeholders and send them to players or use them in responses.

```APIDOC
## Builder for Complex Messages

### Description
Uses a builder pattern to construct complex messages with placeholders and send them to players or use them in responses.

### Usage
```java
// replace placeholder {kills} -> 10
getMessages().builder("player.stats")
    .with("kills", 10)
    .with("deaths", 5)
    .with("ratio", 2.0)
    .send(player);

getMessages().builder("complex.message")
    .with("player", player.getName())
    .with("team", team.getName())
    .toResponse(true);
```
```

--------------------------------

### Add Custom /team Command

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/registering-custom-commands.md

Use this to register a custom command that will be available under the /team command. Ensure your command class implements the appropriate interface.

```java
import com.booksaw.betterTeams.Main;

public void onEnable() {
    Main.plugin.getTeamCommand().addSubCommand(new YourCommandHere());
}
```

--------------------------------

### Add Custom /teama Command

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/registering-custom-commands.md

Use this to register a custom admin command that will be available under the /teama command. Ensure your command class implements the appropriate interface.

```java
import com.booksaw.betterTeams.Main;

public void onEnable() {
    Main.plugin.getTeamaCommand().addSubCommand(new YourAdminCommandHere());
}
```

--------------------------------

### Direct Send

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/extensions-mesages.md

Shows how to directly send translated messages to a player.

```APIDOC
## Direct Send

### Description
Sends translated messages directly to a player.

### Usage
```java
getMessages().send(player, "welcome");
getMessages().send(player, "player.joined", "player", "Steve", "team", "Warriors");
```
```

--------------------------------

### Set Team Membership Permission with LuckPerms

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/05-dependencies/LuckPerms.md

Grant the 'kits.member' permission to a default group only if the player is part of any team. This uses the 'bt_inteam' context provided by BetterTeams.

```bash
/lp group default permission set kits.member true bt_inteam=true
```

--------------------------------

### YAML Configuration for Team Level Price (Score)

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/04-configuration/Team-Levels.md

Sets the cost to upgrade a team to the next level using team score. The 's' suffix indicates that the price is in score.

```yaml
price: 100s
```

--------------------------------

### YAML Configuration for Team Levels

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/04-configuration/Team-Levels.md

Defines various parameters for team levels, such as team size limits, maximum chests, warps, balance, and admin/owner counts. It also includes placeholders for commands to be executed when a team reaches a new level and lore for rank descriptions.

```yaml
levels:
   l1:
      # This is used set a maximum size for a team.
      # - If this feature is unwanted, set the teamLimit to -1 and there will be unlimited places in each team
      # - Keep this value reasonable, as Java cannot cope with larger numbers (over 2 billion), so if you want the team to be limitless, set the value to -1 instead of something large
      #
      # Possible values: [-1, any positive whole number]
      teamLimit: 10
      # This is used to determine the maximum number of chests that a team can claim
      # - If this is set to 0 teams will not be allowed any claims (though it is recommended you do that through permissions instead of the config option)
      # - If this is set to -1 there will be no limit on the number of chests
      #
      # Possible values: [Any positive whole number, 0, -1]
      maxChests: 2
      # This is used to determine the maximum number of warps that a team can set
      # - If this is set to 0 teams will not be allowed any warps (though it is recommended you do that through permissions instead of the config option)
      # - If this is set to -1 there will be no limit on the number of warps
      #
      # Possible values: [Any positive whole number, 0, -1]
      maxWarps: 2
      # Used to limit the balance the team can have in their team bank
      # - If this is set to -1 there will be no limit on team balance
      # - If this is set to 0, teams of that level will not have a team bank (to completely disable use teampermissions.yml)
      #
      # Possible values [-1, 0, any positive number]
      maxBal: -1
      # The maximum number of admins a team is allowed while is has this rank
      # - If this is set to -1 there will not be a limit
      #
      # Possible values [-1, any positive number]
      maxAdmins: 5
      # The maximum number of owners a team is allowed at this rank
      # - If singleOwner is set to true this value will be ignored
      #
      # Possible values [any positive whole number]
      maxOwners: 2
      
      # This is a list of commands that are run when a team
      # Any player which contains %player% will be run for every player on the team
      # Placeholders:
      # %team% is replaced with the team name
      # %player% is replaced with all players in the team
      # %level% is replaced with the level that the team is becomming
      endCommands:
      # - say %player% is no longer level 1

      # This message is included in /team rank command to give more details about the rank
      # this message, for example could include the perks of this team rank along with the perks of the next rank
      rankLore:
      - '&7The first level'
   l2:
      # Price is determined for all levels aside level 1,
      # - If this value ends with 's' it will take score from the team
      # - If this value ends with 'm' it will take money from the team balance
      price: 100s
      teamLimit: 20
      maxChests: 2
      maxWarps: 2
      maxBal: -1
      maxAdmins: 5
      maxOwners: 1
      rankLore:
      - '&7The second level'

```

--------------------------------

### Static Message

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/extensions-mesages.md

Explains how to convert messages into a static format for use in command responses or direct sending.

```APIDOC
## Static Message

### Description
Converts messages into a static format suitable for command responses or direct sending.

### Usage
```java
getMessages().toStatic("welcome");
getMessages().toStatic("player.joined", "player", "Steve", "team", "Warriors");
```
```

--------------------------------

### BetterTeams Extension Main Class Methods

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/Extensions-Intro.md

Implement the onEnable and onDisable methods in your main extension class, which extends BetterTeamsExtension. These methods are called when the extension is enabled or disabled, and also during BetterTeams reloads.

```java
@Override
public void onEnable() {

}

@Override
public void onDisable() {

}
```

--------------------------------

### Discord Webhook Configuration

Source: https://github.com/booksaw/betterteams/blob/master/wiki/extensions/discord.md

Configure Discord webhook settings in `config.yml`. Set `hookURL` to your webhook URL and `hookSupport` to `true` to enable the feature. Other options control specific event triggers.

```yaml
# The webhook URL of your webhook.
hookURL: "WEBHOOKURL_HERE"

# Will this feature be enabled?
# If set to false skip the rest of the settings
hookSupport: false

# If you disabled support for webhooks these settings won't matter
# You can change for what specific events the webhook should be triggered.
# For example, if you set the create-hook option to true the webhook will send a message
# on team creation.
create-hook: false
disband-hook: false
player-left-hook: false
team-nameChange-hook: false
team-chat: false
```

--------------------------------

### Configure Command Costs

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/04-configuration/Command-Cost-and-Cooldown.md

Set costs for /team commands, deducting money from the player or team balance. The cost is only charged if the command executes successfully. Ensure the entire line is enclosed in single quotes.

```yaml
costs:
- 'home:9.99'
```

--------------------------------

### Configure Command Cooldowns

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/04-configuration/Command-Cost-and-Cooldown.md

Add cooldowns to specific /team commands by specifying the command and the cooldown duration in seconds. Ensure the entire line is enclosed in single quotes.

```yaml
cooldowns:
- 'home:60'
## The line above will add a 60-second cooldown to the command /team home
```

--------------------------------

### Static Message Creation

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/extensions-mesages.md

Create static messages that can be used in command responses or sent directly. Supports dynamic content.

```java
getMessages().toStatic("welcome");
```

```java
getMessages().toStatic("player.joined", "player", "Steve", "team", "Warriors");
```

--------------------------------

### Migrate Event Handlers from PrePurgeEvent to PurgeEvent

Source: https://github.com/booksaw/betterteams/blob/master/MIGRATING.md

Update your event handler methods to use the new `PurgeEvent` class instead of the deprecated `PrePurgeEvent`. The handler logic remains the same.

```java
// Old code
public void onPrePurge(PrePurgeEvent event) {
    // handler logic
}

// New code
public void onPurge(PurgeEvent event) {
    // same handler logic
}
```

--------------------------------

### Declare Soft Dependency in plugin.yml

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/API-intro.md

Declare BetterTeams as a soft dependency in your plugin.yml if your plugin can function without it.

```yaml
softDepend: [BetterTeams]
```

--------------------------------

### Response Messages for Commands

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/extensions-mesages.md

Generate response messages for commands, indicating success or failure. Supports dynamic content.

```java
return getMessages().response(true, "command.success");
```

```java
return getMessages().response(false, "error.no-permission");
```

```java
return getMessages().response(true, "command.done", "player", "Steve");
```

```java
return new CommandResponse(getMessages().toStatic("command.success"));
```

--------------------------------

### Declare Hard Dependency in plugin.yml

Source: https://github.com/booksaw/betterteams/blob/master/wiki/docs/99-API/API-intro.md

Declare BetterTeams as a hard dependency in your plugin.yml if your plugin requires it to function.

```yaml
depend: [BetterTeams]
```

--------------------------------

### Configure Score per Capture

Source: https://github.com/booksaw/betterteams/blob/master/wiki/extensions/zkoth.md

Set the amount of score awarded to a team for each KOTH capture. This configuration is located in the extension's `config.yml` file.

```yaml
# The amount of score to give to the team that wins the KOTH
pointsPerCapture: 10
```