PlexVariables

Create powerful custom PlaceholderAPI variables without writing Java.

PlexVariables lets server owners build their own placeholders using simple YAML files. Variables can be static, conditional, calculated from other values, or stored permanently for players and the server.

Everything is designed to work together, making PlexVariables useful for custom statistics, ranks, progression systems, status displays, event data, server-wide values, and much more.

---

Static Variables

Create simple reusable placeholders:

variables:
  server_name:
    value: "&d&lPlex Network"

  welcome:
    value: "&fWelcome %player_name% to %plexvar_server_name%!"

This creates placeholders such as:

%plexvar_server_name%
%plexvar_welcome%

PlexVariables can also resolve normal PlaceholderAPI placeholders inside your variables.

For example:

%plexvar_welcome%

could return:

Welcome KingApplex to Plex Network!

---

Conditional Variables

Create placeholders that automatically react to player or server data.

variables:
  health_status:
    conditions:
      - condition: "%player_health% <= 5"
        value: "&cCritical"

      - condition: "%player_health% <= 10"
        value: "&eLow"

    default: "&aHealthy"

Conditions are evaluated from top to bottom, and the first matching condition is used.

Supported condition types include:

• Numeric comparisons
• String comparisons
• Permissions
• Worlds
• Regex
• Contains
• Starts with
• Ends with

Example operators:

==
!=
>
>=
<
<=
contains
!contains
startsWith
endsWith
matches

Native conditions are also supported:

permission:server.staff
!permission:server.staff

world:spawn
!world:spawn

---

Expression Variables

Perform safe mathematical calculations using PlaceholderAPI values and other PlexVariables.

variables:
  doubled_gems:
    expression: "%plexvar_player_gems% * 2"
    decimals: 0

If:

%plexvar_player_gems% = 300

then:

%plexvar_doubled_gems%

returns:

600

Supported operators:

+  -  *  /  %  ^

Supported functions include:

min()
max()
abs()
round()
floor()
ceil()
sqrt()

Expression variables also support:

• Decimal formatting
• Rounding modes
• Prefixes and suffixes
• Thousands separators
• Error fallbacks
• Nested PlexVariables
• PlaceholderAPI values

Example:

variables:
  winrate:
    expression: "(%wins% / (%wins% + %losses%)) * 100"
    decimals: 1
    suffix: "%"
    on-error: "0%"

If:

wins = 30
losses = 10

the result is:

75%

without needing a custom Java plugin.

---

Persistent Player Variables

Create your own persistent player data.

variables:
  player_gems:
    type: stored
    scope: player
    default: "0"

Stored values can be changed using commands:

/pv set player_gems PlayerName 250
/pv add player_gems PlayerName 50

Then used anywhere PlaceholderAPI is supported:

%plexvar_player_gems%

Example result:

300

Player data is stored using SQLite and player UUIDs, and persists across server restarts.

Stored values can be useful for:

• Event points
• Reputation
• Gems
• Custom currencies
• Progression values
• Prestige
• Custom statistics
• Player titles
• Custom score systems

---

Global Stored Variables

Stored values are not limited to individual players.

You can also create server-wide values:

variables:
  server_event_status:
    type: stored
    scope: global
    default: "inactive"

Change it using:

/pv set server_event_status global OPEN

Then use:

%plexvar_server_event_status%

or:

%plexvar_global_server_event_status%

Example result:

OPEN

Global variables are useful for:

• Event states
• Season names
• Maintenance status
• Global counters
• Server-wide progression
• Dynamic announcements
• Custom server information

---

Everything Works Together

The different variable types can reference each other.

For example:

player_gems = 300
        ↓
expression: 300 * 2
        ↓
doubled_gems = 600
        ↓
condition: 600 >= 500
        ↓
gem_rank = High

Example configuration:

variables:
  doubled_gems:
    expression: "%plexvar_player_gems% * 2"
    decimals: 0

  gem_rank:
    conditions:
      - condition: "%plexvar_doubled_gems% >= 500"
        value: "&6High"

      - condition: "%plexvar_doubled_gems% >= 200"
        value: "&eMedium"

    default: "&7Low"

This means PlexVariables can act as a flexible logic and data layer between other plugins.

You can build things such as:

• K/D ratios
• Win rates
• Custom player ranks
• Economy tiers
• Event progression
• Reputation systems
• Player status indicators
• Custom score calculations
• Seasonal values
• Dynamic server information
• Permission-based labels
• World-based placeholders

---

Built-In Debugging

Use:

/pv test <player|--null> <variable>

to see exactly how a variable is being evaluated.

Conditional variables can show:

• Original condition
• Resolved values
• Match result
• Selected branch
• Final output
• Parse time

Expression variables can show:

• Original expression
• Resolved expression
• Calculated result
• Formatting
• Error fallback

Stored variables can show:

• Scope
• Cache state
• Raw stored value
• Default value
• Effective value
• Final output

This makes complex variables much easier to debug without guessing.

---

Features

• Static variables
• Conditional variables
• Expression variables
• Persistent player variables
• Persistent global variables
• PlaceholderAPI nesting
• PlexVariables referencing other PlexVariables
• Permission conditions
• World conditions
• Regex support
• Numeric comparisons
• String comparisons
• Safe mathematical expressions
• SQLite persistence
• Async database operations
• UUID-based player storage
• In-memory stored-value caching
• Automatic YAML file discovery
• Nested variable folders
• Cross-file variable references
• Cycle protection
• Resolution safety limits
• Transactional reload system
• Hex color support
• Built-in debugging tools
• No forced branding

---

Placeholder Format

All standard variables use:

%plexvar_<variable>%

Examples:

%plexvar_server_name%
%plexvar_health_status%
%plexvar_player_gems%
%plexvar_kd_ratio%
%plexvar_gem_rank%

Global stored variables can also use:

%plexvar_global_<variable>%

---

Commands

/pv help
/pv list [page]
/pv reload
/pv parse <player|--null> <text>
/pv test <player|--null> <variable>

/pv get <variable> [player|global]
/pv set <variable> <player|global> <value>
/pv add <variable> <player|global> <amount>
/pv reset <variable> <player|global>

Aliases:

/plexvariables
/plexvar
/pvar
/pv

---

Requirements

• Paper 1.21+
• Java 21
• PlaceholderAPI

Additional PlaceholderAPI expansions may be required depending on which placeholders you use inside your variables.

For example, if you use placeholders provided by another plugin or PlaceholderAPI expansion, that provider must also be installed.

---

Performance

PlexVariables is designed for placeholders that may be requested frequently by:

• Scoreboards
• TAB lists
• Holograms
• Menus
• Chat formats
• Other PlaceholderAPI-supported plugins

Stored player and global values are cached in memory during normal placeholder resolution.

Normal placeholder parsing does not perform a SQLite database read every time a placeholder is requested.

Database operations are handled asynchronously using a dedicated storage worker.

Conditions and expressions are also prepared during configuration loading where possible, reducing unnecessary work during normal placeholder parsing.

---

Safety

PlexVariables includes several protections for complex variable setups:

• Cycle detection
• Maximum resolution depth
• Expression complexity limits
• Output length limits
• Work-budget protection
• Throttled warnings
• Safe division-by-zero handling
• Transactional reloads

If a configuration reload fails, the previous working configuration remains active instead of replacing it with a broken one.

---

Automatic Variable Discovery

You can organize variables across multiple YAML files.

Example:

plugins/PlexVariables/
├── config.yml
├── messages.yml
├── data.db
└── variables/
    ├── general.yml
    ├── conditions.yml
    ├── expressions.yml
    ├── storage.yml
    └── events/
        └── halloween.yml

PlexVariables automatically discovers YAML files inside the variables folder.

No manual file registration is required.

---

Support

If you encounter an issue, please include:

• Your server version
• Your PlexVariables version
• Relevant variable configuration
• Any related console errors

Bug reports and feature suggestions are welcome.