LibPlaceholder Expansions

Official external expansion packages for LibPlaceholder.

Each directory under expansions/ is built into an independent expansion.phar. Releases use <identifier>-v<version> tags and are automatically published to LibPlaceholder Index.

Contributing an Expansion

Use this repository for pull requests that add or modify official expansion code. A contribution should include its resolver, catalog.json metadata, contract tests, compatibility information, and placeholder documentation.

Do not open the initial pull request in LibPlaceholder Index. The Index stores release metadata only and is updated automatically after an official version is built and published.

Developers who prefer to maintain an expansion in their own repository may do so and submit its released package metadata directly to LibPlaceholder Index. See CONTRIBUTING.md for the complete workflow.

Available Expansions

Identifier	Dependency	Purpose
bedrockeconomy	BedrockEconomy 4.0.4+	Cached balances, positions, and currency metadata
bedrockclans	BedrockClans 3.12+	Clan identity, members, ranks, bank, home, and chat state
cplot	CPlot API 1.0.0	Cache-only current plot, ownership, membership, and role
groupsystem	GroupSystem 3.4.0+	Current group, formats, expiration, and permissions
libworld	LibWorld 1.0.0+ or embedded LibWorld	Worlds, regions, selections, and edit operations
multiworld	MultiWorld 2.1.2+	Default, loaded, and current world state
piggyfactions	PiggyFactions 2.1.0+	Player power and faction information
ranksystem	RankSystem 1.1.4+	Ranks, prefixes, formats, and permissions
skyblockspm	SkyBlocksPM 1.1.1+	Island identity, membership, settings, spawn, and chat state

The plugin versions above are the API contracts used during development. LibPlaceholder verifies that the dependency plugin is enabled; each expansion then uses only the documented public API needed by its resolver.

Installation

Server administrators normally install these packages through LibPlaceholder:

/papi expansions refresh
/papi expansions search ranks
/papi expansions download ranksystem

New installations are hot-loaded by LibPlaceholder when safe. Updates or removals of an expansion that is already loaded are still queued for the next restart, because PHP cannot unload/redeclare classes safely.

Official expansion metadata targets LibPlaceholder ^1.0 while the current runtime remains 1.0.0. Do not publish official 1.0.x expansion manifests with a ^1.1 API requirement unless LibPlaceholder itself is intentionally bumped to that minor line.

Manual installation is also supported by placing the package and its generated manifest under:

plugin_data/LibPlaceholder/expansions/installed/<identifier>/

Placeholder Reference

All player-dependent placeholders preserve the original token when no player context or plugin data is available. Optional faction fields resolve to an empty string when the player has no faction.

BedrockEconomy

Balance values are read from BedrockEconomy's ONLINE or TOP cache. Parsing never performs a database query.

Placeholder	Value
%bedrockeconomy_balance%	Plain balance with configured decimals
%bedrockeconomy_balance_formatted%	Balance formatted by BedrockEconomy
%bedrockeconomy_balance_major%	Whole-number balance component
%bedrockeconomy_balance_decimals%	Two-digit decimal component
%bedrockeconomy_top_position%	Cached economy ranking position
%bedrockeconomy_currency_name%	Currency name
%bedrockeconomy_currency_code%	Currency code
%bedrockeconomy_currency_symbol%	Currency symbol

Currency metadata does not require a player.

BedrockClans

Placeholder	Value
%bedrockclans_clan_name%	Clan save name
%bedrockclans_clan_display_name%	Formatted clan display name
%bedrockclans_clan_color%	Clan color code
%bedrockclans_clan_leader%	Leader player name
%bedrockclans_clan_members%	Comma-separated member names
%bedrockclans_clan_members_count%	Total member count
%bedrockclans_clan_bank%	Clan bank balance
%bedrockclans_clan_rank%	Player rank inside the clan
%bedrockclans_clan_is_leader%	1 when the player is leader, otherwise 0
%bedrockclans_clan_creation_timestamp%	Clan creation Unix timestamp
%bedrockclans_clan_creation_date%	Clan creation date
%bedrockclans_clan_home_world%	Clan home world folder
%bedrockclans_clan_home%	Clan home as x, y, z
%bedrockclans_chat_mode%	1 when clan chat mode is enabled

CPlot

CPlot resolution is intentionally cache-only. The expansion does not start database work or wait for asynchronous promises. If the current world or plot has not yet entered CPlot's runtime cache, the original placeholder remains unchanged until CPlot loads it.

Placeholder	Value
%cplot_plot_id%	Plot coordinates as x;z
%cplot_plot_alias%	Plot alias
%cplot_plot_world%	Plot world folder
%cplot_plot_x%	Plot grid X coordinate
%cplot_plot_z%	Plot grid Z coordinate
%cplot_plot_claimed%	1 when the plot has an owner
%cplot_plot_owners%	Comma-separated owner names
%cplot_plot_owners_count%	Owner count
%cplot_plot_trusted_count%	Trusted player count
%cplot_plot_helpers_count%	Helper count
%cplot_plot_denied_count%	Denied player count
%cplot_plot_merged_count%	Number of plots in the merged plot
%cplot_plot_role%	owner, trusted, helper, denied, or visitor

GroupSystem

Placeholder	Value
%groupsystem_group%	Current group name
%groupsystem_group_colored%	Current colored group name
%groupsystem_group_color%	Current group color code
%groupsystem_nametag%	Group nametag with {name} resolved
%groupsystem_display_name%	Group display name with {name} resolved
%groupsystem_chat_format%	Chat format with {name} resolved
%groupsystem_expire_at%	Expiration date or never
%groupsystem_expire_timestamp%	Unix expiration timestamp or 0
%groupsystem_expire_remaining%	Compact remaining time or permanent
%groupsystem_groups%	Current and remaining group names
%groupsystem_groups_count%	Number of unique assigned groups
%groupsystem_permissions_count%	Number of direct session permissions

LibWorld

The same package works when LibWorld is installed as the standalone plugin or provided by EasyLibrary's embedded component. It detects WorldAPI at parse time instead of requiring one specific plugin name.

Placeholder	Value
%libworld_loaded_worlds%	Loaded world count
%libworld_registered_regions%	Registered LibWorld region count
%libworld_active_operations%	Active asynchronous edit count
%libworld_world%	Current world folder
%libworld_world_display_name%	Current world display name
%libworld_world_players%	Players in the current world
%libworld_world_time%	Current world time
%libworld_world_difficulty%	Current world difficulty ID
%libworld_region%	Highest-priority region at the player
%libworld_regions%	All regions at the player
%libworld_regions_count%	Number of regions at the player
%libworld_selection_complete%	1 when both selection positions exist
%libworld_selection_world%	Selection world folder
%libworld_selection_position_one%	First position as x, y, z
%libworld_selection_position_two%	Second position as x, y, z
%libworld_selection_volume%	Selected cuboid volume

MultiWorld

Placeholder	Value
%multiworld_loaded_worlds%	Loaded world count
%multiworld_default_world%	Default world folder
%multiworld_world%	Current world folder
%multiworld_world_display_name%	Current world display name
%multiworld_world_players%	Players in the current world
%multiworld_world_time%	Current world time
%multiworld_world_difficulty%	Current world difficulty ID
%multiworld_world_auto_save%	1 when world auto-save is enabled

PiggyFactions

Placeholder	Value
%piggyfactions_player_role%	Player faction role
%piggyfactions_player_power%	Player power
%piggyfactions_player_max_power%	Player maximum power
%piggyfactions_faction_name%	Faction name
%piggyfactions_faction_description%	Faction description
%piggyfactions_faction_motd%	Faction message of the day
%piggyfactions_faction_creation_date%	Faction creation date
%piggyfactions_faction_power%	Combined faction power
%piggyfactions_faction_max_power%	Combined maximum faction power
%piggyfactions_faction_money%	Faction bank balance
%piggyfactions_members%	Total member count
%piggyfactions_online_members%	Online member count
%piggyfactions_leader%	Leader username
%piggyfactions_allies%	Ally count
%piggyfactions_enemies%	Enemy count
%piggyfactions_home_world%	Faction home world folder

RankSystem

Placeholder	Value
%ranksystem_highest_rank%	Highest rank name
%ranksystem_ranks%	Comma-separated effective ranks
%ranksystem_ranks_count%	Effective rank count
%ranksystem_temporary_ranks%	Comma-separated temporary ranks
%ranksystem_temporary_ranks_count%	Temporary rank count
%ranksystem_nametag%	Fully resolved RankSystem nametag
%ranksystem_nametag_prefix%	Highest-rank nametag prefix
%ranksystem_nametag_prefixes%	Combined nametag prefixes
%ranksystem_nametag_name_color%	Highest-rank nametag name color
%ranksystem_chat_prefix%	Highest-rank chat prefix
%ranksystem_chat_prefixes%	Combined chat prefixes
%ranksystem_chat_name_color%	Highest-rank chat name color
%ranksystem_chat_format%	Highest-rank chat separator/format
%ranksystem_permissions_count%	Effective permission count

SkyBlocksPM

Placeholder	Value
%skyblockspm_island_uuid%	Island UUID
%skyblockspm_island_name%	Island name
%skyblockspm_island_leader%	Island leader
%skyblockspm_island_members%	Comma-separated members
%skyblockspm_island_members_count%	Member count
%skyblockspm_island_world%	Island world folder
%skyblockspm_island_role%	leader or member
%skyblockspm_island_spawn%	Island spawn as x, y, z
%skyblockspm_island_visit%	1 when visits are enabled
%skyblockspm_island_pvp%	1 when PvP is enabled
%skyblockspm_chat_mode%	1 when island chat mode is enabled

Compatibility Decisions

Capital is not currently published as an official expansion. Its upstream plugin manifest targets PocketMine API 4.0.0, while LibPlaceholder supports PocketMine 5. Publishing that package would make it uninstallable on every supported server. A Capital expansion can be added after an upstream PMMP 5 release or a stable, API-compatible successor exists.

Repository Layout

LibPlaceholderExpansions/
|-- expansions/
|   |-- bedrockclans/src/
|   |-- bedrockeconomy/src/
|   |-- cplot/src/
|   |-- groupsystem/src/
|   |-- libworld/src/
|   |-- multiworld/src/
|   |-- piggyfactions/src/
|   |-- ranksystem/src/
|   `-- skyblockspm/src/
|-- scripts/
|   |-- build.php
|   |-- export-index.php
|   `-- validate.php
|-- tests/
|-- catalog.json
`-- .github/workflows/

catalog.json is the single source for package metadata and documented placeholders. scripts/export-index.php combines it with the built PHAR's exact size and SHA-256 digest.

Development

Validate metadata and resolver contracts:

composer test

Build one package:

php -d phar.readonly=0 scripts/build.php ranksystem

Build every package:

for expansion in bedrockclans bedrockeconomy cplot groupsystem libworld multiworld piggyfactions ranksystem skyblockspm; do
  php -d phar.readonly=0 scripts/build.php "$expansion"
done

Resolvers must remain synchronous and cheap. Database, network, and filesystem operations do not belong in a placeholder parse path; integrations should read plugin-owned in-memory state or caches.

Publishing Expansions

The Release Expansion workflow runs manually or when an official <identifier>-v<version> tag is pushed. It validates the repository, builds the PHAR, publishes the expansion release, and updates LibPlaceholder Index from the exact published artifact.

Contributors only need to update the source, catalog metadata, tests and changelog in this repository. Release credentials and catalog publication are maintainer-managed repository settings.

License

This repository is licensed under the MIT License. Integrated plugins remain the property of their respective authors.