Skip to main content
The TitleListener intercepts and formats title and subtitle packets, allowing servers to display formatted large text messages on the player’s screen with MiniMessage formatting and placeholder support.

​
Packet Types

Intercepts two packet types:
  • PacketType.Play.Server.SET_TITLE_TEXT - Main title text
  • PacketType.Play.Server.SET_TITLE_SUBTITLE - Subtitle text below the title

​
Configuration

listeners:
  titles: true
When disabled, titles and subtitles are sent unmodified to the client.

​
Class Structure

public class TitleListener extends AbstractListener {
    public TitleListener(ProcessHandler processHandler, ConfigManager configManager) {
        super(processHandler, configManager);
    }

    @Override
    public void onPacketPlaySend(PacketPlaySendEvent e) {
        // Implementation
    }
}
Source: TitleListener.java:12-35

​
Implementation Details

​
1. Packet Type Validation

PacketTypeCommon type = e.getPacketType();
if (!config.getOrDefault("listeners.titles", true) || (
    type != PacketType.Play.Server.SET_TITLE_TEXT &&
    type != PacketType.Play.Server.SET_TITLE_SUBTITLE)) return;
Source: TitleListener.java:19-22 The listener exits early if:
  • The listener is disabled in the configuration
  • The packet type is neither SET_TITLE_TEXT nor SET_TITLE_SUBTITLE

​
2. Title Text Processing

Player player = e.getPlayer();

if (type == PacketType.Play.Server.SET_TITLE_TEXT) {
    WrapperPlayServerSetTitleText packet = new WrapperPlayServerSetTitleText(e);
    packet.setTitle(handler.processComponent(packet.getTitle(), player));
}
Source: TitleListener.java:24-29 When the packet is a title:
  1. Creates a WrapperPlayServerSetTitleText wrapper
  2. Extracts the title component
  3. Processes it through ProcessHandler
  4. Sets the formatted title back to the packet

​
3. Subtitle Text Processing

else {
    WrapperPlayServerSetTitleSubtitle packet = new WrapperPlayServerSetTitleSubtitle(e);
    packet.setSubtitle(handler.processComponent(packet.getSubtitle(), player));
}
Source: TitleListener.java:30-33 When the packet is a subtitle:
  1. Creates a WrapperPlayServerSetTitleSubtitle wrapper
  2. Extracts the subtitle component
  3. Processes it through ProcessHandler
  4. Sets the formatted subtitle back to the packet

​
Usage Example

When a plugin sends a title: 
player.showTitle(Title.title(
    Component.text("<gradient:red:gold>VICTORY!</gradient>"),
    Component.text("You earned %player_points% points")
));
The listener will:
  1. Intercept both the title and subtitle packets
  2. Process the gradient formatting in the title
  3. Resolve the %player_points% placeholder in the subtitle
  4. Send the formatted components to the client
Result:
  • Title: “VICTORY!” displayed with a red-to-gold gradient
  • Subtitle: “You earned 150 points” (with the placeholder resolved)

​
Processing Flow

1

Packet Sent

Server sends a title or subtitle packet
2

Interception

TitleListener intercepts the packet before it reaches the client
3

Type Check

Determines whether it’s a title or subtitle packet
4

Component Processing

Extracts the text component and processes it:
  • Resolves placeholders
  • Parses MiniMessage formatting
5

Packet Modification

Updates the packet with the formatted component
6

Client Display

Modified packet is sent to the client and displayed

​
Per-Player Customization

Because processing includes the player parameter, titles can display personalized content: 
title: "<rainbow>Welcome Back!</rainbow>"
subtitle: "Last seen: %player_last_seen%"
Each player sees their own last login time in the subtitle.

​
Dependencies

  • PacketEvents: For packet interception
  • WrapperPlayServerSetTitleText: Packet wrapper for title text
  • WrapperPlayServerSetTitleSubtitle: Packet wrapper for subtitle text
  • ProcessHandler: For placeholder resolution and formatting

​
Common Use Cases

  1. Welcome Messages
    • Greet players when they join the server
    • Display personalized welcome back messages
  2. Game Events
    • Announce game starts, wins, or defeats
    • Show achievement notifications
    • Display round countdowns
  3. Broadcasts
    • Server-wide announcements
    • Event notifications
    • Important alerts
  4. Player Notifications
    • Level up messages
    • Reward notifications
    • Quest completions

Build docs developers (and LLMs) love

Get started for freeTalk to us