# Information

## RivalCredits Shop Plugin

Welcome to the complete documentation for RivalCredits - a powerful, best, feature-rich shop system for Minecraft servers.

***

### Features

#### Core Features

* ✅ **Unlimited Categories** - Create as many shop categories as you need
* ✅ **Unlimited Packages** - No limits on the number of items you can sell
* ✅ **Unlimited Pages** - Multi-page support for large amount of packages
* ✅ **Fully Configurable** - Customize every aspect of your shop
* ✅ **Database Support** - MySQL & SQLite support with cross-server functionality
* ✅ **PlaceholderAPI Support** - Full integration with PlaceholderAPI
* ✅ **HEX Color Support** - Modern RGB color codes for names and lore

#### Shop Features

* 📊 **Leaderboards** - Text-based or GUI leaderboards for top purchasers
* 🎯 **Menu Actions** - Execute commands, close menus, play sounds, and more
* 🔒 **Permission Requirements** - Control who can see and purchase items
* ✅ **Confirmation Menu** - Optional purchase confirmation for expensive items
* 💰 **Advanced Discounts** - Per-category, per-item, global, temporary, or permanent
* 🔥 **Special Deals** - Time-limited special offers system
* ⭐ **Hot Products** - Display most-purchased items automatically
* 📝 **Purchase Logs** - Track all purchases with detailed logging
* 🔔 **Discord Webhook** - Log commands and purchases to Discord

#### Advanced Features

* 🎨 **Fully Customizable Menus** - Design your shop exactly how you want
* 🌐 **Cross-Server Support** - Execute commands on other servers (requires MySQL)
* 📈 **View Requirements** - Dynamic item display based on conditions
* 🏆 **Priority System** - Control item display order in the same slot

***

### Commands

#### Player Commands

| Command                          | Permission                    | Description                            |
| -------------------------------- | ----------------------------- | -------------------------------------- |
| `/creditshop`                    | `rivalcredits.use`            | Opens the main shop category           |
| `/credits balance [player]`      | `rivalcredits.balance.others` | Check your or another player's balance |
| `/credits pay <player> <amount>` | `rivalcredits.pay`            | Transfer credits to another player     |

#### Admin Commands

| Command                             | Permission           | Description                   |
| ----------------------------------- | -------------------- | ----------------------------- |
| `/credits reload`                   | `rivalcredits.admin` | Reloads the entire plugin     |
| `/credits give <player> <amount>`   | `rivalcredits.admin` | Give credits to a player      |
| `/credits set <player> <amount>`    | `rivalcredits.admin` | Set a player's credit balance |
| `/credits remove <player> <amount>` | `rivalcredits.admin` | Remove credits from a player  |
| `/credits reset <player>`           | `rivalcredits.admin` | Reset a player's balance to 0 |
| `/credits about`                    | `rivalcredits.admin` | Shows plugin information      |

#### Discount Commands

| Command                           | Description                                                                                                    |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `/credits discount list`          | List all active discounts                                                                                      |
| `/credits discount remove <name>` | Remove a specific discount                                                                                     |
| `/credits discount removeall`     | Remove all discounts                                                                                           |
| `/credits discount create`        | Create a new discount (see [Discounts](https://claude.ai/chat/a06cc945-045e-45cd-962f-428648ac5e8b#discounts)) |

***

### Placeholders

RivalCredits provides the following PlaceholderAPI placeholders:

| Placeholder                        | Output    | Description                  |
| ---------------------------------- | --------- | ---------------------------- |
| `%rivalcredits_balance%`           | `1234`    | Raw credits amount           |
| `%rivalcredits_balance_decimal%`   | `1234.56` | Credits with decimal points  |
| `%rivalcredits_balance_formatted%` | `1.2k`    | Formatted (1k, 1M, 1B, etc.) |

***

### Configuration

#### Main Command Configuration

You can customize the main command, aliases, and shop shortcuts in `config.yml`:

```yaml
options:
  main-command: "credits"  # Main command name
  command-aliases:         # Alternative commands
    - "credit"
    - "balance"
  shop-aliases:            # Commands that directly open the shop
    - "shop"
    - "store"
    - "buy"
```

#### Item Configuration

**Basic Item Structure**

```yaml
categories:
  category_name:
    options:
      size: 54                    # Inventory size (9, 18, 27, 36, 45, 54)
      name: "&8&nMy Shop"        # Inventory title
      next-page-slot: 50         # Slot for next page button
      previous-page-slot: 48     # Slot for previous page button
      current-page-slot: 49      # Slot for current page display
    items:
      item_name:
        material: 'DIAMOND_SWORD'
        amount: 1
        name: "&b&lDiamond Sword"
        lore:
          - "&7A powerful weapon"
          - ""
          - "&ePrice: {price}"
        price: 1000
        slot: 10
        page: 0                   # Optional: page number (0 = first page)
        package: true             # Mark as purchasable package
```

**Material & Display Options**

**Custom Model Data**

```yaml
item_name:
  material: 'DIAMOND_SWORD'
  customModelData: 12345
```

**Player Heads**

```yaml
item_name:
  material: 'PLAYER_HEAD'
  base64:
    use: true
    value: 'eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvMTM5OWM5NzI0YmVmZjMxNGY4Yjk5OWQ3OWIyMmFkNzc5NGZkNzQ3NjkxMzgwNTcxOGY5NjZhMzU4NTBjNTNhOSJ9fX0='
```

**Leather Armor Colors**

RivalCredits supports multiple color formats for leather armor:

**Hex Color**

```yaml
item_name:
  material: 'LEATHER_CHESTPLATE'
  color: '#FF5733'  # Hex format with #
```

**Named Color**

```yaml
item_name:
  material: 'LEATHER_CHESTPLATE'
  color: 'RED'  # Predefined color names
```

**Available Color Names:**

* `WHITE`, `SILVER`, `GRAY`, `BLACK`
* `RED`, `MAROON`, `YELLOW`, `OLIVE`
* `LIME`, `GREEN`, `AQUA`, `TEAL`
* `BLUE`, `NAVY`, `FUCHSIA`, `PURPLE`
* `ORANGE`&#x20;

**RGB Values**

```yaml
item_name:
  material: 'LEATHER_CHESTPLATE'
  color: '255,100,50'  # RGB format (0-255 for each value)
```

**Examples:**

```yaml
# Example 1: Hex color
red_chestplate:
  material: 'LEATHER_CHESTPLATE'
  color: '#FF0000'
  name: "&cRed Chestplate"
  
# Example 2: Named color
blue_leggings:
  material: 'LEATHER_LEGGINGS'
  color: 'BLUE'
  name: "&9Blue Leggings"
  
# Example 3: RGB values
purple_boots:
  material: 'LEATHER_BOOTS'
  color: '128,0,128'
  name: "&5Purple Boots"
  
# Example 4: Custom RGB
custom_helmet:
  material: 'LEATHER_HELMET'
  color: '50,205,50'  # Lime green
  name: "&aCustom Helmet"
```

**Enchantments**

```yaml
item_name:
  material: 'DIAMOND_SWORD'
  enchantments:
    - 'SHARPNESS:5'
    - 'UNBREAKING:3'
    - 'FIRE_ASPECT:2'
```

**Item Flags**

```yaml
item_name:
  material: 'DIAMOND_SWORD'
  flags:
    - 'HIDE_ATTRIBUTES'
    - 'HIDE_ENCHANTS'
    - 'HIDE_UNBREAKABLE'
```

**Glowing Effect**

```yaml
item_name:
  material: 'DIAMOND'
  glow: true  # Makes item glow without enchantments
```

***

### Discounts

RivalCredits features a powerful discount system that supports various discount types and scopes.

#### Discount Types

**1. Global Discounts**

Apply to all items in the entire shop.

**Permanent Global Discount:**

```bash
/credits discount create example 50 permanent global
```

**Temporary Global Discount (until specific date):**

```bash
/credits discount create example 50 2024-12-25:23:59:59 global
```

**Temporary Global Discount (date range):**

```bash
/credits discount create example 50 2024-12-20:00:00:00_2024-12-26:23:59:59 global
```

**2. Category Discounts**

Apply to all items in a specific category.

**Permanent Category Discount:**

```bash
/credits discount create example 50 permanent ranks
```

**Temporary Category Discount (until specific date):**

```bash
/credits discount create example 50 2024-12-25:23:59:59 ranks
```

**Temporary Category Discount (date range):**

```bash
/credits discount create example 50 2024-12-20:00:00:00_2024-12-26:23:59:59 ranks
```

**3. Item-Specific Discounts**

Apply to a specific item in a category.

**Permanent Item Discount:**

```bash
/credits discount create example 50 permanent ranks warrior
```

**Temporary Item Discount (until specific date):**

```bash
/credits discount create example 50 2024-12-25:23:59:59 ranks warrior
```

**Temporary Item Discount (date range):**

```bash
/credits discount create example 50 2024-12-20:00:00:00_2024-12-26:23:59:59 ranks warrior
```

#### Discount Command Structure

```
/credits discount create <name> <percentage> <duration> <scope> [item]
```

* **name**: Unique identifier for the discount
* **percentage**: Discount amount (50 = 50% off)
* **duration**: `permanent` or date/date range
* **scope**: `global`, category name, or category with item
* **item**: (Optional) Specific item name when using category scope

#### Date Format

* **Single date**: `YYYY-MM-DD:HH:MM:SS` (discount active until this date)
* **Date range**: `YYYY-MM-DD:HH:MM:SS_YYYY-MM-DD:HH:MM:SS` (start\_end)

#### Managing Discounts

```bash
# List all active discounts
/credits discount list

# Remove specific discount
/credits discount remove example

# Remove all discounts
/credits discount removeall
```

{% hint style="info" %}
**Discount Priority**: Item-specific discounts override category discounts, which override global discounts.
{% endhint %}

***

### Confirmation Menu

Add an extra confirmation step for expensive or important purchases.

#### Enabling Confirmation

Add `confirmation: true` to any item:

```yaml
categories:
  crates:
    items:
      rare_key:
        confirmation: true  # Enables confirmation menu
        material: 'LIGHT_BLUE_DYE'
        name: "&f&l1x &b&lRare Key"
        lore:
          - ""
          - "&b&lPrice: {price}"
          - ""
          - "&eClick to purchase"
        price: 200
        slot: 10
        package: true
```

#### Configuring Confirmation Menu

The confirmation menu itself is configured in `config.yml`:

```yaml
confirmation-menu:
  enabled: true
  size: 27
  title: "&8Confirm Purchase"
  confirm-slot: 11
  cancel-slot: 15
  confirm-item:
    material: 'LIME_STAINED_GLASS_PANE'
    name: "&a&lConfirm Purchase"
    lore:
      - "&7Click to confirm"
  cancel-item:
    material: 'RED_STAINED_GLASS_PANE'
    name: "&c&lCancel"
    lore:
      - "&7Click to cancel"
```

***

### Commands & Actions

Execute commands and actions when items are purchased.

#### Basic Command Execution

```yaml
item_name:
  commands:
    use: true
    commands:
      - "give {player} diamond 64"
      - "msg {player} &aYou received diamonds!"
```

#### Action Types

| Action Type     | Format                   | Description              |
| --------------- | ------------------------ | ------------------------ |
| Console Command | `command` or no prefix   | Execute as console       |
| Player Command  | `[player] command`       | Execute as player        |
| Close Menu      | `[close]`                | Close the inventory      |
| Play Sound      | `[sound] SOUND_NAME`     | Play a sound to player   |
| Message         | `[message] text`         | Send message to player   |
| Broadcast       | `[broadcast] text`       | Broadcast to all players |
| Title           | `[title] title;subtitle` | Send title to player     |
| ActionBar       | `[actionbar] text`       | Send actionbar to player |

#### Example: Advanced Actions

```yaml
vip_rank:
  commands:
    use: true
    commands:
      - "lp user {player} parent set vip"
      - "[player] spawn"
      - "[sound] ENTITY_PLAYER_LEVELUP"
      - "[title] &6&lVIP Rank;&7Activated!"
      - "[broadcast] &e{player} &7purchased &6VIP Rank&7!"
      - "[close]"
```

#### No-Credits Actions

Execute actions when a player doesn't have enough credits:

```yaml
item_name:
  no-credits-actions:
    - '[close]'
    - '[message] &cYou need more credits!'
    - '[sound] ENTITY_VILLAGER_NO'
```

***

### Cross-Server Purchases

Execute commands on other servers using MySQL database synchronization.

#### Setup

1. Configure MySQL in `config.yml`
2. Set a unique `server-id` for each server
3. Ensure all servers connect to the same database

#### Configuration Example

**Server 1 (Hub) - config.yml:**

```yaml
database:
  type: 'MYSQL'
  host: 'localhost'
  port: 3306
  database: 'rivalcredits'
  username: 'root'
  password: 'password'

server-id: 'Hub'
```

**Server 2 (SkyBlock) - config.yml:**

```yaml
database:
  type: 'MYSQL'
  host: 'localhost'
  port: 3306
  database: 'rivalcredits'
  username: 'root'
  password: 'password'

server-id: 'SkyBlock'
```

#### Using Cross-Server Commands

Add `server: 'serverid'` to execute commands on a specific server:

```yaml
categories:
  crates:
    items:
      skyblock_key:
        server: 'SkyBlock'  # Commands execute on SkyBlock server
        material: 'LIGHT_BLUE_DYE'
        name: "&f&l1x &b&lSkyBlock Rare Key"
        lore:
          - ""
          - "&7Will be given on"
          - "&7the SkyBlock server"
          - ""
          - "&b&lPrice: {price}"
        commands:
          use: true
          commands:
            - "crate give {player} Rare 1"
        price: 200
        slot: 10
        package: true
```

***

### Special Deals System

Create time-limited special offers that automatically rotate.

#### Configuration

In `config.yml`:

```yaml
special-deals:
  enabled: true
  sync:
    # Enable main-instance: on only 1 server!
    main-instance: false
    time: false
    packages: false
  amount: 2
  shuffle-time: 3600
  packages:
    # category;package;chance;discount
    - 'crates;3;5;5'
    - 'crates;2;50;20'
    - 'crates;1;50;20'
    - 'ranks;1;30;20'
  display:
    # category:slot,slot,slot:timerdisplayslot:page
    - 'main:48,49,50:40:0'
```

#### Display Format

```
category:slots:display_slot:page
```

* **category**: Which category to show deals in
* **slots**: Comma-separated slots for deal items (e.g., `10,11,12`)
* **display\_slot**: Slot for the "Special Deals" info item
* **page**: Which page to display deals on

#### Package Format

```
category;package;chance;discount
```

* **category**: Category containing the item
* **package**: Name of the package
* **chance**: Chance of package appearing
* **discount**: Discount as decimal (0.25 = 25% off)

***

### Hot Products System

Automatically display the most-purchased item across all categories.

#### Configuration

In `config.yml`:

```yaml
most-purchased-package:
  enabled: true
  display:
    - "ranks:10:0"     # Format: category:slot:page
    - "crates:15:0"
  add-lore:
    - ""
    - "&6⭐ &e&lMOST PURCHASED"
    - "&7Bought &e{amount} &7times!"
```

#### Display Format

```
category:slot:page
```

* **category**: Which category to display the hot product in
* **slot**: Slot number for display
* **page**: Page number for display

The system automatically tracks purchases and displays the most popular item with additional lore.

Set display: \[] to empty to disable

***

### View Requirements & Priority

Create dynamic menus that adapt to each player. See the dedicated View Requirements documentation for complete details.

#### Quick Example

```yaml
item_name:
  slot: 10
  priority: 5
  view-requirement:
    permission: "shop.vip"
    placeholder-number:
      placeholder: "%player_level%"
      comparison: ">="
      value: 25
```

{% hint style="info" %}
&#x20;**Learn More**: Check out the View Requirements & Priority System page for comprehensive documentation with examples.&#x20;
{% endhint %}

***

### Color Codes & Formatting

#### Standard Color Codes

| Code | Color       | Code | Color        |
| ---- | ----------- | ---- | ------------ |
| `&0` | Black       | `&8` | Dark Gray    |
| `&1` | Dark Blue   | `&9` | Blue         |
| `&2` | Dark Green  | `&a` | Green        |
| `&3` | Dark Aqua   | `&b` | Aqua         |
| `&4` | Dark Red    | `&c` | Red          |
| `&5` | Dark Purple | `&d` | Light Purple |
| `&6` | Gold        | `&e` | Yellow       |
| `&7` | Gray        | `&f` | White        |

#### Format Codes

| Code | Effect                |
| ---- | --------------------- |
| `&l` | **Bold**              |
| `&m` | \~\~Strikethrough\~\~ |
| `&n` | Underline             |
| `&o` | *Italic*              |
| `&k` | Obfuscated            |
| `&r` | Reset                 |

#### HEX Colors

Use modern RGB colors with the format `&#RRGGBB`:

```yaml
name: "&#FF5733This is orange text"
lore:
  - "&#00FF00Green text"
  - "&#3498DBBlue text"
```

***

### FAQ

#### How do I change the currency command/name?

In `config.yml` under `options:` you can customize:

* `main-command`: Primary command name
* `command-aliases`: Alternative command names
* `shop-aliases`: Commands that open the shop directly

#### How do I activate discounts?

Use the `/credits discount create` command. See the Discounts section for all formats and examples.

#### Can players purchase items on other servers?

Yes! Configure MySQL and set unique `server-id` values. Then add `server: 'serverid'` to items. See Cross-Server Purchases.

#### How do I make an item glow?

Add `glow: true` to the item configuration. No enchantments needed!

#### Can I use custom textures?

Yes! Use `customModelData: 1234` for custom models, or `base64:` for custom player head textures.

#### How do I hide items from certain players?

Use the View Requirements system with permissions, placeholders, or other conditions.

#### Can I have multiple items in the same slot?

Yes! Use the Priority System to determine which item shows based on player conditions.

#### How do I add a purchase confirmation?

Add `confirmation: true` to any item. Configure the confirmation menu in `config.yml`. See Confirmation Menu.

#### What placeholder plugins are supported?

Any PlaceholderAPI expansion can be used in view requirements and item lore/names.

#### Can I execute commands as the player?

Yes! Use `[player] command` format. See Commands & Actions.

***

### Support & Resources

#### Getting Help

1. **Read the Documentation** - Most questions are answered here
2. **Check Examples** - Review the example configurations
3. **Discord Support** - Join our Discord for live help
4. **Ticket System** - Submit a support ticket

#### Best Practices

1. **Test in Development** - Always test changes on a test server first
2. **Backup Configurations** - Keep backups before major changes
3. **Use Reload Sparingly** - Restart server after major config changes
4. **Monitor Performance** - Check logs for errors or warnings
5. **Start Simple** - Add complexity gradually as you learn

{% hint style="success" %}
&#x20;**Pro Tip**: Join our Discord community to get help from other users and share your shop designs!
{% endhint %}

***

###