Skip to main content

​
Overview

The ProcessHandler class is Runway’s core utility for processing text components and items with MiniMessage formatting, placeholders, and custom styling. It handles the conversion of strings and components with support for PlaceholderAPI, MiniPlaceholders, and custom placeholders defined in your configuration. Package: me.mrafonso.runway.util

​
Getting an Instance

Runway does not expose a public API to access the ProcessHandler directly. If you need to use Runway’s processing capabilities in your own plugin, you should create your own instance: 
// Get Runway's ConfigManager
Runway runwayPlugin = (Runway) Bukkit.getPluginManager().getPlugin("Runway");
ConfigManager configManager = new ConfigManager(runwayPlugin);

// Create your own ProcessHandler instance
ProcessHandler processHandler = new ProcessHandler(configManager);
processHandler.reloadPlaceholders();
Runway uses ProcessHandler internally for packet processing. The examples below show how the class works, but most users won’t need to instantiate it directly.

​
Constructor

​
configManager
ConfigManager
required
The ConfigManager instance used to access configuration and placeholder settings
public ProcessHandler(ConfigManager configManager)

​
Methods

​
processComponent (String)

Processes a string into a Component with MiniMessage formatting, placeholders, and styling applied. 
public Component processComponent(@Nullable String s, @Nullable Player player)
​
s
String
required
The string to process. Can contain MiniMessage tags, placeholders, and special prefixes.Special Prefixes:
  • [mm] - Indicates MiniMessage formatting (required if require-prefix.minimessage is enabled)
  • [p] - Indicates placeholder processing (required if require-prefix.placeholders is enabled)
​
player
Player
The player context for placeholder resolution. Required for player-specific placeholders from PlaceholderAPI or MiniPlaceholders.
​
return
Component
The processed Component with all formatting and placeholders applied. Returns Component.empty() if input is null.

​
Example

// Create ProcessHandler instance (see "Getting an Instance" above)
ProcessHandler handler = new ProcessHandler(configManager);
handler.reloadPlaceholders();

Player player = // ... get player

// Basic MiniMessage formatting
Component welcome = handler.processComponent(
    "<gradient:blue:aqua>Welcome to the server!</gradient>",
    null
);
player.sendMessage(welcome);

// With player placeholders
Component greeting = handler.processComponent(
    "[p]Hello <player_name>, you have %player_level% levels!",
    player
);
player.sendMessage(greeting);

// With custom placeholders defined in placeholders.yml
Component info = handler.processComponent(
    "Server: <server_name> | Version: <server_version>",
    null
);

​
processComponent (Component)

Processes an existing Component by serializing it and applying all formatting rules. 
public Component processComponent(@Nullable Component component, @Nullable Player player)
​
component
Component
required
The Component to process. Will be serialized to MiniMessage format and reprocessed.
​
player
Player
The player context for placeholder resolution.
​
return
Component
The reprocessed Component with all formatting applied.

​
Example

Component original = Component.text("Original text");
Component processed = handler.processComponent(original, player);

​
processComponent (List)

Processes a list of Components, applying formatting to each one. 
public List<Component> processComponent(@Nullable List<Component> components, @Nullable Player player)
​
components
List<Component>
required
The list of Components to process. Commonly used for item lore.
​
player
Player
The player context for placeholder resolution.
​
return
List<Component>
A new list containing all processed Components. Returns empty list if input is null.

​
Example

List<Component> lore = Arrays.asList(
    Component.text("<gray>Rarity: <gold>Legendary"),
    Component.text("[p]Owner: %player_name%")
);

List<Component> processedLore = handler.processComponent(lore, player);

​
processItem

Processes an ItemStack by applying formatting to its display name and lore. 
public ItemStack processItem(@Nullable ItemStack item, @Nullable Player player)
​
item
ItemStack
required
The PacketEvents ItemStack to process. Both display name and lore will have formatting applied.
​
player
Player
The player context for placeholder resolution in item text.
​
return
ItemStack
The processed ItemStack with formatted display name and lore. Returns null if input is null.
This method uses PacketEvents’ ItemStack type, not Bukkit’s. The conversion is handled internally using SpigotConversionUtil.

​
Example

import com.github.retrooper.packetevents.protocol.item.ItemStack;

// Create or get a PacketEvents ItemStack
ItemStack item = // ... your item

// Process the item with player context
ItemStack processedItem = handler.processItem(item, player);

// Now the item's display name and lore have MiniMessage formatting applied

​
processItems

Processes a list of ItemStacks, applying formatting to each one. 
public List<ItemStack> processItems(@Nullable List<ItemStack> items, @Nullable Player player)
​
items
List<ItemStack>
required
The list of PacketEvents ItemStacks to process.
​
player
Player
The player context for placeholder resolution.
​
return
List<ItemStack>
A new list containing all processed ItemStacks. Returns empty list if input is null.

​
Example

List<ItemStack> inventory = // ... get items
List<ItemStack> processedInventory = handler.processItems(inventory, player);

​
reloadPlaceholders

Reloads custom placeholders from the placeholders configuration file. This method should be called after modifying placeholders.yml. 
public void reloadPlaceholders()
This method is automatically called when Runway reloads. You typically don’t need to call this manually unless you’re modifying placeholders programmatically.

​
Example

// After modifying placeholders.yml programmatically
configManager.reload();
processHandler.reloadPlaceholders();

​
Configuration Options

The ProcessHandler behavior is controlled by several configuration options in config.yml:
  • require-prefix.minimessage (default: true) - Whether [mm] prefix is required for MiniMessage formatting
  • require-prefix.placeholders (default: true) - Whether [p] prefix is required for placeholder processing
  • placeholder-hook.placeholderapi (default: false) - Enable PlaceholderAPI integration
  • placeholder-hook.miniplaceholders (default: false) - Enable MiniPlaceholders integration
  • ignore-legacy (default: false) - Whether to ignore legacy color codes (§)
  • disable-italics (default: true) - Automatically disable italics for processed text

​
Full Example

Here’s a complete example showing how to use ProcessHandler in your plugin: 
import me.mrafonso.runway.Runway;
import me.mrafonso.runway.util.ProcessHandler;
import net.kyori.adventure.text.Component;
import org.bukkit.entity.Player;
import org.bukkit.plugin.java.JavaPlugin;

public class MyPlugin extends JavaPlugin {
    private ProcessHandler processHandler;
    
    @Override
    public void onEnable() {
        // Create ProcessHandler instance
        Runway runwayPlugin = (Runway) getServer().getPluginManager().getPlugin("Runway");
        ConfigManager configManager = new ConfigManager(runwayPlugin);
        processHandler = new ProcessHandler(configManager);
        processHandler.reloadPlaceholders();
        
        // Example 1: Send formatted message
        Player player = // ... get player
        Component message = processHandler.processComponent(
            "<gradient:gold:yellow>⭐ Achievement Unlocked!</gradient>",
            player
        );
        player.sendMessage(message);
        
        // Example 2: Create formatted item
        ItemStack item = // ... create item
        ItemMeta meta = item.getItemMeta();
        
        // Set display name with formatting
        meta.displayName(processHandler.processComponent(
            "<rainbow>Legendary Sword</rainbow>",
            null
        ));
        
        // Set lore with player-specific placeholders
        meta.lore(processHandler.processComponent(
            Arrays.asList(
                Component.text("<gray>Damage: <red>50</red>"),
                Component.text("[p]<gray>Owned by: <gold>%player_name%</gold>")
            ),
            player
        ));
        
        item.setItemMeta(meta);
    }
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us