Placeholders

Module Information

Group ID: net.impactdev.impactor.api

Artifact ID: text

Placeholder Management

When it comes to placeholders for text based objects, Impactor provides a text module which manages different levels of raw text deserialization and placeholder resolution. A placeholder is an object which is identified by a specific Key, and from there, is capable of injecting text directly at the location of the placeholder key. For instance, given the raw string <red>Hello World, the server is running at <yellow><impactor:tps> TPS! would result in a resulting Component which has everything up to in red coloring, followed by impactor:tps replaced with the actual server TPS value and the literal TPS in yellow.

How do I Create Placeholders?

To create a placeholder, you'll want to access the PlaceholderService. To do so, you'll want to request the service using Impactor.instance().services().provide(PlaceholderService.class). Additionally, you can subscribe to the RegisterPlaceholdersEvent which fires as soon as placeholders are immediately able to be registered. From there, placeholders are created using a PlaceholderParser, which is simply a functional interface which takes in a nullable viewer (for contextual placeholder resolution) and additional binding context which might aid in placeholder resolution. All you need to do is implement parse such that given the viewer and context, you can create a Component of any kind.

Placeholder Resolution

When it comes to placeholder resolution, this is where you'll want to make use of a TextProcessor. By default, Impactor provides two kinds of text processors. One which focuses on legacy character formats, such as color codes defined with & and §, and another which processes text in the MiniMessage Format. Using these processors, or using your own implementation, you can then start parsing raw strings or lists of strings into actual Components, with placeholders registered to Impactor additionally resolved as capable. It should be noted that you are also responsible for creating and supplying context as necessary for expected placeholders to resolve, so any necessary context should be built just before calling any parse request.

Default Placeholders

Impactor provides a small set of default placeholders should their need become required. Their keys and descriptions are available below...

Core Module

Key	Description	Context Requests
impactor:tps	Specifies the current Ticks/Second of the server at the exact moment the placeholder resolves
impactor:mspt	Specifies the average time it is currently taking to process a single server tick (aim is below 50)
impactor:memory_used	The amount of RAM currently in use
impactor:memory_allocated	The amount of RAM currently allocated
impactor:memory_total	The maximum amount of RAM available to the Server
impactor:name	The name of the given source, if available	PlatformSource
impactor:uuid	The UUID of the given source, if available	PlatformSource

Economy Module

The following placeholders all belong to the economy module...

Key	Argument Chain	Description	Context Requirements
impactor:currency		Specifies the plural name of a given Currency	Currency
impactor:account	balance	Indicates the current balance of the given Account	Account
	name	The name of the account holder	Account
	uuid	The uuid of the account holder	Account
impactor:baltop	ranking	The integer value of the current list position of baltop	Integer
impactor:economy_transaction	type	The type of transaction to occur	TransactionContext/TransferTransactionContext
	before	The balance of the account before the transaction	Currency + TransactionContext
	after	The balance of the account after the transaction	Currency + TransactionContext
	result	The overall result of the transaction	TransactionContext
	source before	The balance of the source account prior to a transfer action	Currency + TransferTransactionContext
	source after	The balance of the source account after a transfer action	Currency + TransferTransactionContext
	recipient before	The balance of the recipient account prior to a transfer action	Currency + TransferTransactionContext
	recipient after	The balance of the recipient account after a transfer action	Currency + TransferTransactionContext

Translations

Key	Argument	Description	Context Requirements
impactor:language	id	The language tag of a particular locale (e.g. en_US)	LanguageInfo
	name	The display name of a particular language	LanguageInfo
	progress	The amount of progress made into translating a particular language	LanguageInfo
	contributor	The name of a contributor for a language	String + LanguageInfo