Iris/docs/09 - PlaceholderAPI.md

09 - PlaceholderAPI

Iris registers the iris PlaceholderAPI expansion on Bukkit-family servers when PlaceholderAPI is enabled at Iris enable time. It publishes sixteen keys: seven world-family readings for the player and nine global pregeneration keys. This is an operator board contract, not a Java API; plugins that need the same data with more precision use 90 - API - Getting Started.md, 91 - API - Terrain.md, and 92 - API - World Events.md. PlaceholderAPI is not available on Fabric/Forge/NeoForge; related runtime and integration details are in 07 - Pregeneration.md and 28 - Integrations.md.

Tutorial: verify a placeholder before using it in another plugin

Prerequisites: Bukkit-family Iris, PlaceholderAPI installed before Iris enables, a full server restart, and a player in a loaded Iris world.

1. Confirm registration: /papi info iris. The output must list expansion id iris and its published paths.
2. Confirm the service: /papi parse me %iris_available%. Expect true while Iris terrain service is live.
3. Confirm player context: /papi parse me %iris_world.available%. Expect true while the named player is in an Iris world.
4. Parse a concrete terrain value: /papi parse me %iris_world.biome-key%. Expect a load key such as desert/hot-dunes, not ---.
5. While standing in the Iris world, run /iris pregen start 352 center=0,0 gui=false, then parse /papi parse me %iris_pregen.percent%. Expect a numeric value from 0.00 through 100.00 with no percent sign.
6. Stop with /iris pregen stop or let the job finish, then run /papi parse me %iris_pregen.available%. Expect false; other pregen values return --- after the snapshot clears.
7. Copy the exact verified placeholder into the scoreboard, chat, or HUD plugin and test that consumer once more.

The workflow passes when registration, player-scoped terrain, and global pregen values each produce their documented value shape. Do not debug formatting in the consuming plugin until direct /papi parse succeeds.

Recovery

Symptom	Meaning	Recovery
/papi info iris has no expansion	PlaceholderAPI was unavailable when Iris scheduled registration	Perform a full restart with both plugins installed; /papi reload alone does not trigger Iris registration
Placeholder remains literal	Path is unknown or uses a removed pre-2.0 name	Copy an exact path from /papi info iris or the full table below
World value is ---	No online player context, player is outside Iris, or terrain service has no reading	Parse as a named online player after entering a loaded Iris world
world.available is true but biome lags movement	Player view cache is within its one-second TTL	Wait one second or trigger an immediate publish by teleport/world change before diagnosing the consumer
Pregen value is ---	No global job snapshot is active	Start a job and wait for its first event; use pregen.available as the guard in board templates
Scoreboard adds % twice	pregen.percent deliberately omits the suffix	Add one literal % in the consumer format, not in the placeholder

Registration

Item	Value
Expansion id	iris
Expansion version	2.0.0
Author string	Volmit Software
Required plugin	Iris
Soft-depend	PlaceholderAPI in plugin.yml
persist()	true — survives /papi reload without Iris restart

Iris schedules setup after enable. If PlaceholderAPI is not enabled then, the expansion is not registered and there is no late PluginEnableEvent re-attempt. Soft-depend alone does not load PlaceholderAPI.

List published paths with /papi info iris.

Value grammar

Rule	Detail
Path form	Dot-separated, lowercase, no underscores. Iris lowercases the path before resolve, so %iris_WORLD.BIOME% works, but write lowercase
Plain text only	No color codes, no unit suffixes, no % in values, . as decimal separator, no thousands grouping
Pack name scrubbing	Section-sign sequences and % characters inside pack-authored names are stripped before return
Real zero	0 (or 0.00 for two-decimal numbers), never ---

Three answers:

Answer	When	Board shows
A value	Known key with data	The value
---	Known key with no data right now	---
Nothing (null to PAPI)	Unknown path	Literal %iris_...%

Unknown paths stay visible on purpose. There is no catch-all blank fallback.

Full key table

World family

Placeholder	Value
%iris_available%	true when the Iris terrain service is live, false otherwise
%iris_world.available%	true when the reading player is in an Iris world and a reading exists
%iris_world.biome%	Surface biome display name at the player column (example: Hot Desert Dunes)
%iris_world.biome-key%	Surface biome load key (example: desert/hot-dunes)
%iris_world.region%	Region display name at the player column
%iris_world.region-key%	Region load key
%iris_world.dimension%	Dimension (pack) load key of the player's world

%iris_available% does not need a player. Every other world.* key needs a tracked online player. Console, offline player, or untracked position: world.available is false and the rest are ---.

Pregeneration family

Placeholder	Value
%iris_pregen.available%	true while a pregeneration job is running
%iris_pregen.world%	World name the running job is pregenerating
%iris_pregen.percent%	Completion 0.00–100.00, no % character
%iris_pregen.eta%	Estimated seconds remaining, whole number
%iris_pregen.eta-text%	Same estimate as 45s, 2m 5s, or 1h 30m
%iris_pregen.chunks%	Chunks generated so far
%iris_pregen.total%	Chunks in the job
%iris_pregen.chunks-per-second%	Current rate, two decimal places
%iris_pregen.paused%	true while the job is paused

pregen.* is global (one job per server). Values match for every player and the console. Snapshot is published on pregen events (STARTED, TICK, PAUSED, RESUMED, SAVING) and cleared on COMPLETED or CANCELLED. After clear, pregen.available is false and other pregen.* keys are ---. Before enough chunks exist for an ETA, eta/eta-text read 0 / 0s.

Paths as reported by /papi info iris

available
pregen.available
pregen.chunks
pregen.chunks-per-second
pregen.eta
pregen.eta-text
pregen.paused
pregen.percent
pregen.total
pregen.world
world.available
world.biome
world.biome-key
world.dimension
world.region
world.region-key

Prefix each with %iris_ and suffix with %.

Surface readings and cache

world.biome, world.biome-key, world.region, and world.region-key are surface column readings: the biome/region the generator places at ground level for that X/Z. A player in a cave under an overhang still reads the surface biome above, not the cave biome.

Position tracking

Event	Publish
Walking (PlayerMoveEvent)	At most once per second per player; skipped while the player stays in the same block column
Join, respawn, world change, portal, any teleport (including /iris goto, /tp, ender pearl, random TP)	Immediate

Standing still never keeps a stale column from a previous place after an immediate publish. Quit releases the player's position and world view.

View rebuild TTL

World views rebuild at most once per second per player (VIEW_TTL_MS = 1000), and only when something reads a world.* key that needs the view. Consequences:

• A board full of world.* keys costs one rebuild per player per second
• Values can lag a sprinting player by up to one second
• An unread board costs no terrain queries

Pregen snapshot

Pregen values come from a single global snapshot updated by IrisPregenerationEvent, not per-player polling.

Permissions

Iris never gates a placeholder on a permission. Values that should not be public (for example world seed) are not published.

Failure policy

Situation	Shown
Unknown path	Nothing (literal %iris_...%)
Known path, no data	---
No player context on world.*	--- and world.available = false
Player not in an Iris world	--- and world.available = false
Terrain service not registered	--- / world.available = false / %iris_available% = false
No pregen job	--- / pregen.available = false
Resolver throws	---; one warning per distinct path, max 64 distinct paths

Failed keys are not quarantined; they keep answering ---.

Migration from pre-2.0 keys

Pre-2.0 underscore keys are gone. No alias and no dual-accept window. Old keys render literally.

Old key	New key	Notes
%iris_biome_name%	%iris_world.biome%	Dot grammar
%iris_biome_id%	%iris_world.biome-key%	id was always the load key
%iris_region_name%	%iris_world.region%	Dot grammar
%iris_region_id%	%iris_world.region-key%	id was always the load key
%iris_biome_file%	removed	Exposed absolute server paths; threw without a backing file
%iris_region_file%	removed	Same as biome_file
%iris_world_seed%	removed	No permission context on scoreboards; use terrain API IrisWorldInfo.seed() when a plugin needs seed
%iris_terrain_height%	removed	Generated height before objects/edits; disagreed with the block underfoot
%iris_terrain_slope%	removed	Expensive pack-authoring diagnostic
%iris_world_mode%	removed	Studio vs production is not a live-board concern
%iris_world_speed%	removed	Mutated engine rate-window state on read; use %iris_pregen.chunks-per-second% for pregen rate

Behavior change inside the renames: old keys sampled two blocks above the player's feet (cave/overhang Y). New keys are always surface for the column. %iris_world.dimension% is new and has no pre-2.0 equivalent.