(4.0.0 - 4.21.1) 1.2.0 (4.0.0 - 4.21.1) 1.1.1 (4.0.0 - 4.21.1) 1.1.0 (4.0.0 - 4.21.1) 1.0.0
InfoAPI formats your text using placeholders called "info".
You can put the info in {}
and it will be replaced into the actual value.
For example, if you are using a chat plugin
that provides an info called player
which represents the player chatting,
and an info called message
which represents the message to be sent.
Then you can customize the chat message like this:
<{player}> {message}
If the player is called Steve
and the message is Hello world
, the formatted chat message would become
<Steve> Hello world
Some types of infos provide extra details.
For example, an info representing a player has a detail called health
.
So you can write the detail name after the original info name
(separated by a space):
[{player health}] <{player}> {message}
This will become
[9.5/10] <Steve> Hello world
You can get details of details!
The player health is a proportion.
Proportion infos have a detail called percent
,
which converts the fraction into a percentage:
[{player health percent}] <{player}> {message}
This will become
[95%] <Steve> Hello world
All default info types are listed here: https://sof3.github.io/InfoAPI/defaults.html
Other plugins may also provide their info types. Check out their plugin description to learn more.
{}
if I don't want it replaced?Simply write {{
or }}
when you want {
or }
.
What if I really want
{{
or}}
?
Write {{{{
or }}}}
. Just duplicate every brace. Simple.
If your plugin stores data (esp. about players, etc.), you can expose your data to InfoAPI so that users can use these data in other plugins.
To provide info for InfoAPI, use the API methods on InfoRegistry
in onEnable
:
public function onEnable(){
// other normal stuff
if(class_exists(InfoAPI::class)){
InfoAPI::provideInfo(SomeInfo::class, MyInfo::class, "pluginname.infoname", function(SomeInfo $info){
return new MyInfo(...);
});
}
}
SomeInfo
is the type of the parent of the info you provide, and MyInfo
is the type of the info provided.
The third parameter is a fully-qualified identifier for the info you provide. Users only need to type the part behind the last dot, but they can use the previous parts in case two infos have identical names (especially from different plugins). (For the first example above, {infoname}
, {modulename.infoname}
and {pluginname.modulename.infoname}
will all be matched)
For example, if you provide a kills/deaths ratio for a player in a plugin called KDCounter, your code might look like this:
public function onEnable(){
// other normal stuff
if(class_exists(InfoRegistry::class)){
InfoAPI::provideInfo(PlayerInfo::class, NumberInfo::class, "kdcounter.kills", function(PlayerInfo $info){
return new NumberInfo($this->getKills($info->getPlayer()));
});
InfoAPI::provideInfo(PlayerInfo::class, NumberInfo::class, "kdcounter.deaths", function(PlayerInfo $info){
return new NumberInfo($this->getDeaths($info->getPlayer()));
});
InfoAPI::provideInfo(PlayerInfo::class, NumberInfo::class, "kdcounter.kd", function(PlayerInfo $info){
return new RatioInfo($this->getKills($info->getPlayer()), $this->getDeaths($info->getPlayer()));
});
}
}
The second parameter is a closure that gets called if the event is matched. It should return an Info
object that is the resolved result.
InfoAPI introduces some builtin subclasses for Info
, but plugins may also implement new subclasses of such type. Please consult the API documentation for usage.
If your plugin uses placeholders in your config, you can use InfoAPI so that users can use data from other plugins.
To use InfoAPI, add InfoAPI
to the depend
attribute in plugin.yml
depend: [InfoAPI]
Let's say the template string is retrieved with $this->getConfig()->get("format")
.
Extra placeholders are {speaker}
, which refers to a pocketmine\Player
object in the variable $player
,
and {message}
, which refers to a string in the variable $arg
.
Then we can create the formatted string with this code:
use SOFe\InfoAPI\{InfoAPI, PlayerInfo, StringInfo};
// ...
$formatted = InfoAPI::resolve($this->getConfig()->get("format"), new MyInfo([
"message" => new StringInfo($msg),
"speaker" => new PlayerInfo($player),
]));
Then we create the class MyInfo
according to the arguments we have:
<?php
namespace Your\Plug\In;
use SOFe\InfoAPI\{ContextInfo, PlayerInfo, StringInfo};
final class MyInfo extends ContextInfo {
public StringInfo $message;
public PlayerInfo $speaker;
}
If you need to resolve at multiple places with different argument sets,
create a new class for each set of arguments.
InfoAPI is strict about the keys provided and properties declared:
The keys that appear in the InfoAPI::resolve
array must be
exactly the same as the property names in the custom info class.
You may also add up to 1 line of doc comment to the properties in MyInfo
,
which are displayed to users in help menus.
The doc comment can be multiline,
but only the first line will be used as the description.
Furthermore, add an @example
tag to provide examples.
final class MyInfo extends ContextInfo {
/** The message spoken by the player */
public StringInfo $message;
/**
* The player who spoke the message
* @example Steve
*/
public PlayerInfo $speaker;
}
Do NOT use ContextInfo
for return values in provideInfo
/provideFallback
!
ContextInfo
is only for the convenient creation when resolving.
Please refer to the previous guide if you are actively providing some info.