Skip to main content
Runway allows you to define custom static placeholders in the placeholders.yml file. These placeholders are resolved before MiniMessage parsing, allowing you to use MiniMessage formatting within placeholder values.

​
Overview

Custom placeholders are useful for:
  • Defining server-wide constants (server name, IP, Discord link, etc.)
  • Creating reusable formatted text snippets
  • Centralizing commonly-used text with MiniMessage formatting
  • Simplifying complex MiniMessage syntax into simple placeholders
Custom placeholders are static and do not change dynamically. For dynamic placeholders, use PlaceholderAPI or MiniPlaceholders integration.

​
Configuration Structure

The placeholders.yml file uses a simple key-value structure: 
custom-placeholders:
  placeholder_name: value
  another_placeholder: value with formatting
​
custom-placeholders
object
A map of placeholder names to their values. Each key becomes a placeholder that can be used in messages.

​
Usage

Custom placeholders use the standard placeholder syntax: %placeholder_name%

​
Basic Example

placeholders.yml
custom-placeholders:
  server_name: RunwayMC
  server_ip: play.runwaymc.net
  website: https://runwaymc.net
Now you can use these placeholders in any message: 
Welcome to %server_name%!
Connect at: %server_ip%
Visit: %website%

​
MiniMessage Support

Custom placeholders fully support MiniMessage formatting, allowing you to create richly formatted reusable text.

​
Formatted Examples

placeholders.yml
custom-placeholders:
  server_name: <gradient:#00ff00:#00aa00>RunwayMC</gradient>
  prefix: <bold><gold>[Server]</gold></bold>
  error_prefix: <bold><red>✖</red></bold>
  success_prefix: <bold><green>✔</green></bold>
  discord_link: <click:open_url:'https://discord.gg/example'><hover:show_text:'<green>Click to join!'><aqua><u>Discord</u></aqua></hover></click>
  vip_badge: <gradient:#FFD700:#FFA500><bold>[VIP]</bold></gradient>
  separator: <gray><strikethrough>                              </strikethrough></gray>

​
Using Formatted Placeholders

Once defined, you can use these placeholders in your plugin messages: 
%prefix% Welcome to the server!
%error_prefix% You don't have permission!
%success_prefix% Action completed successfully!
Join our %discord_link% for updates!
%separator%
When using MiniMessage in placeholder values, you don’t need the [mm] prefix. The placeholders themselves are always parsed as MiniMessage.

​
Combining Placeholders

You can use placeholders within other placeholders:
placeholders.yml
custom-placeholders:
  server_name: RunwayMC
  prefix: <gold>[%server_name%]</gold>
  welcome_message: %prefix% <green>Welcome to the server!</green>

​
Advanced Examples

​
Role Badges

custom-placeholders:
  owner_badge: <gradient:#FF0000:#FF6600><bold>[OWNER]</bold></gradient>
  admin_badge: <gradient:#FF3333:#FF9999><bold>[ADMIN]</bold></gradient>
  mod_badge: <gradient:#3333FF:#9999FF><bold>[MOD]</bold></gradient>
  helper_badge: <green><bold>[HELPER]</bold></green>
  vip_badge: <gold><bold>[VIP]</bold></gold>

​
Status Messages

custom-placeholders:
  maintenance_notice: <yellow>⚠</yellow> <red><bold>Server is under maintenance</bold></red>
  update_notice: <aqua>ℹ</aqua> <gray>Server will restart for updates in 5 minutes</gray>
  event_starting: <rainbow><bold>🎉 EVENT STARTING SOON! 🎉</bold></rainbow>

​
Chat Formatting

custom-placeholders:
  arrow: <gray>»</gray>
  bullet: <gray>•</gray>
  divider: <gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>
  tip_prefix: <yellow>💡 TIP:</yellow>
  warning_prefix: <red>⚠ WARNING:</red>

​
Best Practices

Use descriptive placeholder names with underscores (e.g., server_name, error_prefix) for better readability.
Avoid circular references where placeholders reference each other in a loop. This can cause parsing issues.

​
Naming Conventions

  • Use lowercase with underscores: server_name not ServerName
  • Be descriptive: error_prefix not ep
  • Group related placeholders: badge_owner, badge_admin, badge_mod

​
Performance Considerations

  • Custom placeholders are static and loaded once at startup
  • They have minimal performance impact
  • Use them freely for commonly-used formatted text

​
Reloading

After modifying placeholders.yml, reload the configuration: 
/runway reload
All custom placeholders will be reloaded and immediately available.

​
Integration with Placeholder Plugins

Custom placeholders work alongside PlaceholderAPI and MiniPlaceholders: 
custom-placeholders:
  player_display: <gradient:#00ff00:#00aa00>%player_name%</gradient>
When PlaceholderAPI is enabled, %player_name% will be resolved first, then the MiniMessage gradient will be applied.
Custom placeholders are resolved in the order they’re defined. If you reference another placeholder, make sure it’s defined earlier in the file.

Build docs developers (and LLMs) love

Get started for freeTalk to us