> For the complete documentation index, see [llms.txt](https://tne.gitbook.io/tne-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tne.gitbook.io/tne-docs/developers/creating-custom-balance-format-rule.md).

# Creating Custom Balance Format Rule

## Adding Custom Currency Formatting Rules for TheNewEconomy

The currency formatting system in **TheNewEconomy** allows developers to define custom rules for displaying currencies. These rules are used in the `Format` configuration of a currency YAML file (e.g., `USD.yml`) and control how currency balances are formatted.

***

### Overview of Format Rules

A **Format Rule** is a component that defines how a placeholder in the currency format is replaced with dynamic content. For example, `<symbol>` can be replaced with `$`, and `<decimal>` can include the decimal separator.

#### Example Default Format in YAML

```yaml
Format: "<symbol><major><decimal><minor>"
```

***

### Creating a Custom Format Rule

#### 1. **Implement the `FormatRule` Interface**

To create a custom formatting rule, implement the `FormatRule` interface. Below is an example of a rule that adds a custom placeholder `<custom>`, which displays a fixed string.

```java
import net.tnemc.core.account.Account;
import net.tnemc.core.account.holdings.HoldingsEntry;
import net.tnemc.core.currency.format.FormatRule;
import org.jetbrains.annotations.Nullable;

public class CustomRule implements FormatRule {

  @Override
  public String name() {
    return "<custom>";
  }

  @Override
  public String format(@Nullable Account account, HoldingsEntry entry, String format) {
    return format.replace("<custom>", "CustomValue");
  }
}
```

#### 2. **Register the Rule**

Register your custom rule with the `CurrencyFormatter` class to make it available in TNE:

```java
CurrencyFormatter.addRule(new CustomRule());
```

This should be done during your plugin or integration's initialization phase.

***

### Examples of Default Rules

#### **SymbolRule**

Replaces `<symbol>` with the currency symbol:

```java
public class SymbolRule implements FormatRule {
  @Override
  public String name() {
    return "<symbol>";
  }

  @Override
  public String format(@Nullable Account account, HoldingsEntry entry, String format) {
    final Optional<Currency> currency = entry.currency();
    return currency.map(value -> format.replace("<symbol>", value.getSymbol())).orElse(format);
  }
}
```

#### **DecimalRule**

Handles the `<decimal>` placeholder, adding or omitting the decimal separator based on the amount:

```java
public class DecimalRule implements FormatRule {
  @Override
  public String name() {
    return "<decimal>";
  }

  @Override
  public String format(@Nullable Account account, HoldingsEntry entry, String format) {
    if (entry.currency().isPresent()) {
      if (entry.asMonetary().scale() == 0) {
        return format.replace("<decimal>", "");
      }
      return format.replace("<decimal>", entry.currency().get().getDecimal());
    }
    return format;
  }
}
```

***

### Example Custom Formatting Rule Usage

#### YAML Configuration

After adding your custom rule, it can be used in the `Format` configuration of a currency YAML file:

```yaml
Format: "<symbol><major><decimal><minor><custom>"
```

When applied, the `<custom>` placeholder will be replaced with the value defined in your `CustomRule`.

***

### Notes

1. **Registration**: Always register custom rules using `CurrencyFormatter.addRule()`.
2. **Compatibility**: Ensure your custom rules align with TNE's currency formatting system.
3. **Dynamic Content**: Use the `Account` and `HoldingsEntry` parameters in your rule to provide dynamic formatting based on player or balance data.

***

By following these steps, you can expand TNE's currency formatting system to suit your server's unique needs. For further reference, review default rules such as `SymbolRule`, `DecimalRule`, and `ShortenRule`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://tne.gitbook.io/tne-docs/developers/creating-custom-balance-format-rule.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.