Skip to content

06-messaging.md

Latest commit

 

History

History
158 lines (117 loc) · 4.71 KB

06-messaging.md

File metadata and controls

158 lines (117 loc) · 4.71 KB

Messaging System

Message Class

Package: com.hypixel.hytale.server.core

Message is the primary way to send formatted text to players. It supports raw text, i18n translations, colors, styles, parameters, and child composition.

Factory Methods

// Raw text (displayed as-is)
@Nonnull public static Message raw(@Nonnull String message);

// Translation key (looked up via I18nModule)
@Nonnull public static Message translation(@Nonnull String messageId);

// Parse formatted string (with embedded formatting)
@Nonnull public static Message parse(@Nonnull String message);

// Empty message
@Nonnull public static Message empty();

// Join multiple messages
@Nonnull public static Message join(Message... messages);

Parameter Methods (Fluent API)

All return this for chaining.

// String parameter
@Nonnull public Message param(@Nonnull String key, @Nonnull String value);

// Numeric parameters
@Nonnull public Message param(@Nonnull String key, int value);
@Nonnull public Message param(@Nonnull String key, long value);
@Nonnull public Message param(@Nonnull String key, float value);
@Nonnull public Message param(@Nonnull String key, double value);

// Boolean parameter
@Nonnull public Message param(@Nonnull String key, boolean value);

// Nested message parameter
@Nonnull public Message param(@Nonnull String key, @Nonnull Message formattedMessage);

Style Methods

@Nonnull public Message bold(boolean bold);
@Nonnull public Message italic(boolean italic);
@Nonnull public Message monospace(boolean monospace);
@Nonnull public Message color(@Nonnull String color);     // Hex string e.g., "#FF0000"
@Nonnull public Message color(@Nonnull Color color);      // java.awt.Color
@Nonnull public Message link(@Nonnull String url);        // Clickable link

Composition Methods

// Append child message
@Nonnull public Message insert(@Nonnull Message formattedMessage);

// Append raw text as child
@Nonnull public Message insert(@Nonnull String message);

// Append multiple children
@Nonnull public Message insertAll(Message... formattedMessages);
@Nonnull public Message insertAll(@Nonnull List<Message> formattedMessages);

Accessors

@Nullable public String getRawText();
@Nullable public String getMessageId();       // Translation key
@Nullable public String getColor();
@Nonnull public List<Message> getChildren();
@Nonnull public String getAnsiMessage();      // Terminal-formatted string

Sending Messages

// To a player
PlayerRef playerRef = ...;
playerRef.sendMessage(Message.raw("Hello!"));

// From a command
ctx.sender().sendMessage(Message.raw("Command executed."));

// With ChatType
playerRef.sendMessage(message, ChatType.SYSTEM);

Color Utilities

Colors are specified as hex strings (e.g., "#FF0000") or java.awt.Color objects.

// Common colors used in HyperPerms:
java.awt.Color GOLD = new java.awt.Color(255, 170, 0);    // #FFAA00
java.awt.Color GREEN = new java.awt.Color(85, 255, 85);   // #55FF55
java.awt.Color GRAY = java.awt.Color.GRAY;                // #808080
java.awt.Color WHITE = java.awt.Color.WHITE;               // #FFFFFF

// Command system colors:
"#C1E0FF"  // Required argument color
"#7E9EBC"  // Optional argument color

Translation System

Messages with Message.translation(key) are resolved via I18nModule.get().getMessage(language, key).

Parameters in translations use {key} placeholders that get filled by .param() calls.

// Built-in translation keys (examples):
"server.commands.parsing.error.noPermissionForCommand"
"server.commands.parsing.error.wrongNumberRequiredParameters"
"server.commands.help.usagecolon"

HyperPerms Usage Patterns

// Building a styled help message
Message helpMessage = Message.raw("")
    .insert(Message.raw("--- ").color(GOLD))
    .insert(Message.raw("HyperPerms").color(GREEN).bold(true))
    .insert(Message.raw(" ---").color(GOLD))
    .insert(Message.raw("\n  Commands:").color(WHITE))
    .insert(Message.raw("\n    group").color(GREEN))
    .insert(Message.raw(" - Manage groups").color(GRAY));

ctx.sender().sendMessage(helpMessage);

// Simple feedback
ctx.sender().sendMessage(
    Message.raw("Permission set: ").color(GREEN)
        .insert(Message.raw(permission).color(WHITE))
);

Internal Protocol

Messages are serialized as FormattedMessage protocol objects with fields:

  • rawText — literal text
  • messageId — translation key
  • color — hex color string
  • bold, italic, monospace — MaybeBool (True/False/unset)
  • link — URL string
  • params — Map<String, ParamValue> (primitive params)
  • messageParams — Map<String, FormattedMessage> (nested message params)
  • children — FormattedMessage[] (child messages)