# View Requirements

## View Requirements & Priority System

### Overview

The View Requirements and Priority system allows you to create dynamic, personalized shop menus that adapt to each player's permissions, rank, level, balance, and more. This powerful feature lets you show different items to different players in the same slot, creating a truly customized shopping experience.

***

### Table of Contents

* Priority System
* View Requirements
* Permission Requirements
* Placeholder Requirements
* Numeric Comparisons
* JavaScript Expressions
* Complete Examples
* Best Practices

***

### Priority System

#### What is Priority?

Priority determines which item displays when multiple items target the same inventory slot. The item with the **highest priority value** that meets its view requirements will be shown.

#### How It Works

1. **Default Priority**: If not specified, items have a priority of `0`
2. **Higher Wins**: Items with higher priority values override lower ones
3. **Requirements First**: Only items that meet their view requirements compete
4. **Dynamic Display**: Different players see different items based on their status

#### Basic Priority Example

```yaml
categories:
  weapons:
    items:
      # All three items use slot 10
      basic_sword:
        slot: 10
        priority: 1
        # No view requirements - everyone can see this
        
      vip_sword:
        slot: 10
        priority: 5
        view-requirement:
          permission: "shop.vip"
          
      mvp_sword:
        slot: 10
        priority: 10
        view-requirement:
          permission: "shop.mvp"
```

**Result:**

* **Default players** see: `basic_sword` (priority 1)
* **VIP players** see: `vip_sword` (priority 5 beats 1)
* **MVP players** see: `mvp_sword` (priority 10 beats 5)

***

### View Requirements

View requirements determine **who can see** an item. If a player doesn't meet the requirements, the item is completely hidden from their menu.

#### Basic Structure

```yaml
item_name:
  slot: 10
  priority: 5
  view-requirement:
    # Add your requirements here
```

{% hint style="danger" %}
 **Note:** All requirements within a single `view-requirement` section must be met (AND logic). If any requirement fails, the item is hidden. 
{% endhint %}

***

### Permission Requirements

#### Single Permission

Show an item only to players with a specific permission.

```yaml
vip_package:
  slot: 10
  view-requirement:
    permission: "shop.vip"
```

#### Multiple Permissions (OR Logic)

Show an item if the player has **at least one** of the listed permissions.

```yaml
premium_package:
  slot: 11
  view-requirement:
    permissions:
      - "shop.vip"
      - "shop.mvp"
      - "shop.ultimate"
```

**Result:** Players with VIP, MVP, **or** Ultimate rank can see this item.

***

### Placeholder Requirements

#### String Comparison (Equals)

Check if a placeholder equals a specific value.

```yaml
donor_item:
  slot: 12
  view-requirement:
    has-placeholder:
      placeholder: "%luckperms_primary_group%"
      value: "donor"
```

#### String Comparison (Not Equals)

Check if a placeholder does **not** equal a specific value.

```yaml
non_default_item:
  slot: 13
  view-requirement:
    has-not-placeholder:
      placeholder: "%luckperms_primary_group%"
      value: "default"
```

**Result:** Only players who are **not** in the "default" group can see this item.

#### Common Placeholders

| Placeholder                   | Description        | Plugin Required |
| ----------------------------- | ------------------ | --------------- |
| `%player_name%`               | Player's username  | None            |
| `%player_level%`              | Player's level     | None            |
| `%player_world%`              | Current world      | None            |
| `%vault_eco_balance%`         | Player's balance   | Vault           |
| `%luckperms_primary_group%`   | Player's rank      | LuckPerms       |
| `%statistic_deaths%`          | Death count        | None            |
| `%statistic_play_one_minute%` | Playtime (minutes) | None            |

{% hint style="info" %}
 **Important:** PlaceholderAPI must be installed for most placeholders to work! 
{% endhint %}

***

### Numeric Comparisons

Compare numeric placeholder values using mathematical operators.

#### Comparison Operators

| Operator | Alternative              | Description           |
| -------- | ------------------------ | --------------------- |
| `==`     | `equals`                 | Equal to              |
| `!=`     | `not-equals`             | Not equal to          |
| `>`      | `greater-than`           | Greater than          |
| `>=`     | `greater-than-or-equals` | Greater than or equal |
| `<`      | `less-than`              | Less than             |
| `<=`     | `less-than-or-equals`    | Less than or equal    |

#### Level Requirement Example

```yaml
high_level_sword:
  slot: 14
  view-requirement:
    placeholder-number:
      placeholder: "%player_level%"
      comparison: ">="
      value: 50
```

**Result:** Only players level 50 or higher can see this item.

#### Balance Requirement Example

```yaml
expensive_item:
  slot: 15
  view-requirement:
    placeholder-number:
      placeholder: "%vault_eco_balance%"
      comparison: ">="
      value: 100000
```

**Result:** Only players with $100,000+ can see this item.

#### Multiple Numeric Items (Priority + Level)

```yaml
beginner_package:
  slot: 20
  priority: 1
  view-requirement:
    placeholder-number:
      placeholder: "%player_level%"
      comparison: "<"
      value: 25

intermediate_package:
  slot: 20
  priority: 5
  view-requirement:
    placeholder-number:
      placeholder: "%player_level%"
      comparison: ">="
      value: 25

advanced_package:
  slot: 20
  priority: 10
  view-requirement:
    placeholder-number:
      placeholder: "%player_level%"
      comparison: ">="
      value: 50
```

**Result:**

* **Level 1-24**: See `beginner_package`
* **Level 25-49**: See `intermediate_package`
* **Level 50+**: See `advanced_package`

***

### JavaScript Expressions

For complex conditions that require multiple checks or custom logic, use JavaScript expressions.

#### Basic Syntax

```yaml
item_name:
  slot: 16
  view-requirement:
    javascript: "expression that returns true/false"
```

#### Supported Operations

* **Math**: `+`, `-`, `*`, `/`, `%`
* **Comparison**: `>`, `<`, `>=`, `<=`, `==`, `!=`
* **Logical**: `&&` (AND), `||` (OR), `!` (NOT)
* **Grouping**: `( )`

#### Example: Level AND Balance

```yaml
premium_item:
  slot: 17
  view-requirement:
    javascript: "%player_level% >= 30 && %vault_eco_balance% >= 50000"
```

**Result:** Player must be level 30+ **AND** have $50,000+

#### Example: Multiple Conditions with OR

```yaml
special_item:
  slot: 18
  view-requirement:
    javascript: "%player_level% >= 100 || %vault_eco_balance% >= 1000000"
```

**Result:** Player must **either** be level 100+ **OR** have $1,000,000+

#### Example: Complex Logic

```yaml
exclusive_item:
  slot: 19
  view-requirement:
    javascript: "(%player_level% >= 50 && %vault_eco_balance% >= 100000) || %player_name% == 'Admin'"
```

**Result:** Show if (level 50+ AND $100k+) OR player is named "Admin"

{% hint style="danger" %} **Warning:** JavaScript expressions are evaluated on every menu open. Complex expressions may impact performance on large servers. {% endhint %}

***

### Complete Examples

#### Example 1: Rank-Based Shop

Create a shop where items change based on player rank in the same slots.

```yaml
categories:
  ranks:
    items:
      default_kit:
        slot: 10
        priority: 1
        material: WOODEN_SWORD
        name: "&7Default Starter Kit"
        view-requirement:
          has-placeholder:
            placeholder: "%luckperms_primary_group%"
            value: "default"
      
      vip_kit:
        slot: 10
        priority: 5
        material: IRON_SWORD
        name: "&a&lVIP Starter Kit"
        view-requirement:
          has-placeholder:
            placeholder: "%luckperms_primary_group%"
            value: "vip"
      
      mvp_kit:
        slot: 10
        priority: 10
        material: DIAMOND_SWORD
        name: "&b&lMVP Starter Kit"
        view-requirement:
          has-placeholder:
            placeholder: "%luckperms_primary_group%"
            value: "mvp"
      
      legend_kit:
        slot: 10
        priority: 15
        material: NETHERITE_SWORD
        name: "&6&lLEGEND Starter Kit"
        view-requirement:
          has-placeholder:
            placeholder: "%luckperms_primary_group%"
            value: "legend"
```

#### Example 2: Progressive Level Shop

Items unlock as players level up.

```yaml
categories:
  weapons:
    items:
      novice_sword:
        slot: 12
        priority: 1
        material: WOODEN_SWORD
        name: "&7Novice Sword"
        lore:
          - "&7Level Requirement: 1+"
        view-requirement:
          placeholder-number:
            placeholder: "%player_level%"
            comparison: ">="
            value: 1
      
      apprentice_sword:
        slot: 12
        priority: 5
        material: STONE_SWORD
        name: "&8Apprentice Sword"
        lore:
          - "&7Level Requirement: 10+"
        view-requirement:
          placeholder-number:
            placeholder: "%player_level%"
            comparison: ">="
            value: 10
      
      warrior_sword:
        slot: 12
        priority: 10
        material: IRON_SWORD
        name: "&fWarrior Sword"
        lore:
          - "&7Level Requirement: 25+"
        view-requirement:
          placeholder-number:
            placeholder: "%player_level%"
            comparison: ">="
            value: 25
      
      master_sword:
        slot: 12
        priority: 15
        material: DIAMOND_SWORD
        name: "&bMaster Sword"
        lore:
          - "&7Level Requirement: 50+"
        view-requirement:
          placeholder-number:
            placeholder: "%player_level%"
            comparison: ">="
            value: 50
```

#### Example 3: VIP Exclusive Section

Create items that only VIP+ members can see.

```yaml
categories:
  vip-exclusive:
    items:
      vip_bundle:
        slot: 20
        priority: 5
        material: CHEST
        name: "&a&lVIP Bundle"
        view-requirement:
          permissions:
            - "shop.vip"
            - "shop.mvp"
            - "shop.ultimate"
      
      mvp_only_item:
        slot: 21
        priority: 10
        material: BEACON
        name: "&b&lMVP Exclusive Item"
        view-requirement:
          permissions:
            - "shop.mvp"
            - "shop.ultimate"
      
      ultimate_package:
        slot: 22
        priority: 15
        material: NETHER_STAR
        name: "&6&lULTIMATE Package"
        view-requirement:
          permission: "shop.ultimate"
```

#### Example 4: Multi-Condition Items

Combine multiple requirements for complex conditions.

```yaml
categories:
  special:
    items:
      veteran_reward:
        slot: 25
        priority: 20
        material: GOLDEN_APPLE
        name: "&6&lVeteran Reward"
        lore:
          - "&7Requires:"
          - "&7- Level 75+"
          - "&7- $500,000+"
          - "&7- VIP Rank"
        view-requirement:
          permission: "shop.vip"
          placeholder-number:
            placeholder: "%player_level%"
            comparison: ">="
            value: 75
          javascript: "%vault_eco_balance% >= 500000"
```

#### Example 5: Event-Based Items

Show items based on specific conditions (requires additional placeholders).

```yaml
categories:
  events:
    items:
      christmas_package:
        slot: 30
        priority: 100
        material: SNOW_BLOCK
        name: "&c&lChristmas Package"
        view-requirement:
          has-placeholder:
            placeholder: "%server_time_month%"
            value: "12"
      
      weekend_deal:
        slot: 31
        priority: 50
        material: EMERALD
        name: "&a&lWeekend Special"
        view-requirement:
          javascript: "%server_time_day_of_week% == 6 || %server_time_day_of_week% == 7"
```

***

### Best Practices

#### 1. Use Priority Strategically

```yaml
# ✅ Good - Clear priority hierarchy
default_item:
  priority: 1
vip_item:
  priority: 10
mvp_item:
  priority: 20

# ❌ Bad - Unclear priority differences
default_item:
  priority: 5
vip_item:
  priority: 6
mvp_item:
  priority: 7
```

**Tip:** Use increments of 5 or 10 to leave room for future items.

#### 2. Always Set Fallback Items

```yaml
# Always have a low-priority item with no requirements
default_option:
  slot: 10
  priority: 1
  # No view-requirement - everyone sees this if no higher priority items match
```

#### 3. Test Requirements Thoroughly

* Test with players of different ranks
* Test with different level ranges
* Test with varying balances
* Use `/sudo` or alt accounts for testing

#### 4. Document Your Requirements

```yaml
endgame_item:
  slot: 15
  priority: 50
  material: NETHERITE_INGOT
  name: "&5&lEndgame Item"
  lore:
    - "&7Requirements:"
    - "&7- Level 100+"
    - "&7- $1,000,000+"
    - "&7- Ultimate Rank"
  view-requirement:
    permission: "shop.ultimate"
    javascript: "%player_level% >= 100 && %vault_eco_balance% >= 1000000"
```

#### 5. Optimize Performance

```yaml
# ✅ Good - Simple permission check
view-requirement:
  permission: "shop.vip"

# ⚠️ Caution - Complex JavaScript runs on every menu open
view-requirement:
  javascript: "(%player_level% >= 50 && %vault_eco_balance% >= 100000) || (%statistic_deaths% < 10 && %player_world% == 'survival')"
```

**Tip:** Use simple permission/placeholder checks when possible. Reserve JavaScript for truly complex conditions.

#### 6. Avoid Requirement Conflicts

```yaml
# ❌ Bad - These will never both show (same slot, one is always higher priority)
item_a:
  slot: 10
  priority: 5
  view-requirement:
    permission: "shop.vip"

item_b:
  slot: 10
  priority: 10  # This will always override item_a if requirements are met
  view-requirement:
    permission: "shop.vip"  # Same requirement!
```

***

### Troubleshooting

#### Item Not Showing

1. **Check View Requirements**: Use `/papi parse me %placeholder%` to test placeholder values
2. **Check Priority**: Another item might have higher priority
3. **Check Permission**: Verify player has required permissions
4. **Check Page**: Ensure item is on correct page

#### Wrong Item Showing

1. **Verify Priority Values**: Higher priority item might be meeting requirements
2. **Check Placeholder Values**: Placeholders might not return expected values
3. **Test JavaScript**: JavaScript expression might have logic errors

***

### Additional Resources

* **PlaceholderAPI Wiki**: <https://github.com/PlaceholderAPI/PlaceholderAPI/wiki>
* **JavaScript Tutorial**: <https://www.w3schools.com/js/>
* **Common Placeholders**: `/papi ecloud list all`

***

### Support

If you need help with view requirements or priority:

1. Check this documentation thoroughly
2. Test placeholder values with `/papi parse me %placeholder%`
3. Contact support with your configuration and error logs

{% hint style="info" %}
&#x20;**Pro Tip:** Start simple and add complexity gradually. Test each requirement individually before combining them!
{% endhint %}