Skip to content

Text injection

Text injection is a core concept in the API, used to handle and manage components, parsers, and tags. It allows for flexible message building, contextual data passing, and custom tag creation. Common use cases include:

  • Building chat channel formats
  • Passing contextual values within parser and renderer contexts
  • Adding custom MiniMessage tags

Types of injected values

Injected values implement the SocialInjectedValue interface, which provides utility methods for creating and managing custom values.

Literals

Literal values wrap TextComponents instances and are appended directly to messages.

Example
TextComponent value = Component.text("Example literal");
SocialInjectedLiteral injectedValue = SocialInjectedValue.literal(value);

Placeholders

Placeholders are processed at runtime and are useful for unique, dynamic content that does not need to be globally registered in the text processor.

Example
String identifier = "example_injected_placeholder";
TextComponent value = Component.text("Example placeholder");

SocialInjectedPlaceholder injectedValue = SocialInjectedValue.placeholder(identifier, value);

Tag resolvers

Tag resolvers can be injected directly into the MiniMessage parser, enabling the creation of custom tags.

Example
String identifier = "example_injected_tag_resolver";
TagResolver tagResolver = ...

SocialInjectedTag injectedValue = SocialInjectedValue.tag(identifier, tagResolver);

Objects

Objects can also be injected into the context, making them retrievable by other instances during parsing or rendering.

Example
String identifier = "example_injected_object";
int value = 1;

SocialInjectedObject injectedObject = SocialInjectedValue.object(identifier, value);

Objects do not alter the message appearance.

Usage in chat channel formats

The ChatFormatBuilder leverages text injection exclusively. For practical examples, efer to Channel management.

Usage in SocialParserContext

Injected values can be stored and retrieved via a SocialParserContext: 

// Inject a value into the parser context
context.injectValue(injectedObject);

// Retrieve a value
SocialInjectedObject injectedObject = context.getInjectedValue("example_injected_object");

Warning

getInjectedValue may return null if the value is not present. You can provide a fallback to ensure a default: 

SocialInjectedObject fallback = SocialInjectedValue.object("example_injected_object", 0);
SocialInjectedObject injectedObject = context.getInjectedValue("example_injected_object", fallback);