> ## Documentation Index
> Fetch the complete documentation index at: https://pumpkings.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# NxShards: AFK-Zone Shards Economy for Paper and Folia

> NxShards rewards players with Shards for staying in AFK zones, includes a GUI shop, leaderboard, MySQL/SQLite storage, and full Folia support.

NxShards is an advanced *Shards* economy plugin built for modern Minecraft servers with **full Folia support**. Players earn Shards by spending time inside designated AFK zones, spend them through an interactive GUI shop, and compete for the top spots on a server-wide leaderboard. Every periodic task is wired through the Lifecycle API and Folia entity schedulers, keeping the plugin smooth even on high-population shards.

## Key Features

<CardGroup cols={2}>
  <Card title="Folia + Paper Support" icon="bolt">
    Natively compiled for the Folia architecture. All AFK timers and periodic tasks run through dedicated entity schedulers, reducing tick delay to the absolute minimum.
  </Card>

  <Card title="Dynamic AFK Zones" icon="location-dot">
    Reward players for the time they spend inside any region you define. Each zone has its own interval and Shards payout, configured live with a selection wand.
  </Card>

  <Card title="Titles and BossBars" icon="bars-progress">
    Fully customisable entry, in-zone, and exit feedback — pick colors, durations, and messages for titles, action bars, and the boss bar.
  </Card>

  <Card title="GUI Shop" icon="basket-shopping">
    Players spend Shards through an interactive shop menu defined in `config.yml`. Stock items, set prices, and customise icons without touching code.
  </Card>

  <Card title="MySQL or SQLite Storage" icon="database">
    Use MySQL for shared multi-server balances or SQLite for a zero-setup local database. Switch backends from a single config option.
  </Card>

  <Card title="Safe Player Transfers" icon="right-left">
    `/shards pay` lets players move Shards between accounts, with configurable maximum transfer limits to block abuse and protect the economy.
  </Card>

  <Card title="Leaderboard" icon="trophy">
    `/shards top` ranks the wealthiest players on the network. Expose any leaderboard position to other plugins through PlaceholderAPI.
  </Card>

  <Card title="PlaceholderAPI Support" icon="tag">
    Drop `%shards_balance%` and `%shards_leaderboard_*%` into scoreboards, chat formats, holograms, and tab lists.
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="Mark an AFK zone">
    An admin grabs the selection wand with `/shards wand`, left- and right-clicks two opposite corners, then runs `/shards zone create <name> <interval> <amount>`.
  </Step>

  <Step title="Players enter the zone">
    Anyone standing inside the region sees the configured boss bar, action bar, and entry title — they are now earning Shards on every tick of the interval.
  </Step>

  <Step title="Spend or transfer">
    Players check their balance with `/shards`, buy items from `/shards shop`, send Shards to friends with `/shards pay`, or climb the `/shards top` leaderboard.
  </Step>
</Steps>

## Compatibility

| Requirement         | Details                                      |
| ------------------- | -------------------------------------------- |
| **Server software** | Paper or Folia                               |
| **Folia**           | Fully supported (native scheduler)           |
| **Database**        | MySQL or SQLite (default)                    |
| **PlaceholderAPI**  | Optional — enables `%shards_*%` placeholders |
| **Language**        | Java                                         |
| **License**         | MIT                                          |