Saves PlaceholderAPI values for online players to MySQL so external tools (Observatory) can read them. It does nothing else: no web server, no scoreboards, no webhooks.
Built for Paper 1.21.11+ on Java 25. Requires PlaceholderAPI.
- Placeholders are read on the main thread, for online players only. Offline players keep their last stored value, since most placeholders can't be resolved offline.
- Each online player is re-read every
refresh.interval-seconds, a few players per tick (refresh.players-per-tick) so the work is spread out. - A player is also read when they quit (including kicks, so Stopinator's kick-before-restart is covered), one tick after they die or complete an advancement, and once when they join.
- Only values that changed are written. On join the player's stored values are loaded as the baseline, so the first read doesn't rewrite everything.
- Writes run on a single background thread through HikariCP, in one transaction per flush, every
flush.interval-seconds. A quit, death or advancement that changed something triggers a write straight away. - If a write fails, the values stay queued and are retried on the next flush. The first failure is logged with a stack trace; repeats are not logged until writes work again. If the database is down at startup, the plugin still starts and retries.
- On shutdown, anything still queued is written before the plugin finishes disabling.
These results are treated as "no value" and never overwrite a stored value:
- null, blank, or the unparsed placeholder text (the expansion isn't installed or didn't handle it)
NO_PLAYER_ONLINEandNO_WORKING- anything listed in that placeholder's
empty-values
Values longer than 255 characters are truncated (logged once per placeholder). An exception from an expansion is logged once per placeholder until the next reload, and the player's other placeholders are still read.
One database shared by all servers, one table per server: values_<server-id>. The table is created automatically in the configured database (CREATE TABLE IF NOT EXISTS); the database itself must exist.
CREATE TABLE values_<server-id> (
uuid CHAR(36) NOT NULL, -- with dashes
name VARCHAR(64) NOT NULL, -- the config name, e.g. DD_Affinity
value VARCHAR(255) NOT NULL, -- the value as returned, trimmed
num_value DOUBLE NULL, -- the value if it's a plain number, else NULL
updated_at DATETIME(3) NOT NULL, -- UTC, when the changed value was read
PRIMARY KEY (uuid, name),
KEY idx_name_num (name, num_value)
);num_value is only set for plain numbers such as 42, -3.5 or .5. Values with units, %, thousands separators or text are stored in value only.
Example leaderboard query:
SELECT uuid, value FROM values_hc3ages WHERE name = 'DD_Affinity' ORDER BY num_value DESC;Setup (once):
CREATE DATABASE papisync CHARACTER SET utf8mb4;
CREATE USER 'papisync'@'10.%' IDENTIFIED BY '...';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE ON papisync.* TO 'papisync'@'10.%';All commands need papisync.admin.
| Command | What it does |
|---|---|
/papisync or /papisync status |
Server ID, table state, connections, loaded players, queued values, last write, last error, and per-placeholder counts of values / empty / errors since start or reload. |
/papisync check <player> |
Resolves every placeholder for an online player and shows the raw result, whether it counts as a value, empty or an error, and the value currently stored or queued. Doesn't queue anything. |
/papisync flush |
Reads every online player now and writes all queued values, then reports how many were written. |
/papisync reload |
Reloads config.yml. Placeholders, refresh and flush settings apply immediately. server-id and database changes need a restart. |
/papisync prune |
Lists stored names that are no longer in the config, with row counts. |
/papisync prune confirm |
Deletes the rows for the names listed by the last prune, within 60 seconds. Names that are back in the config are skipped. Can't be undone. |
Rows for placeholders removed from the config are never deleted automatically, since offline players' values can't be read again.
| Permission | Default | Gates |
|---|---|---|
papisync.admin |
op | /papisync and all subcommands |
| Key | Default | Meaning |
|---|---|---|
server-id |
'' |
Required. Table suffix, [a-z0-9_], 1-48 characters. The plugin won't start until it's set. Restart to change. |
database.host |
localhost |
MySQL host. |
database.port |
3306 |
MySQL port. |
database.name |
papisync |
Database name. |
database.username |
papisync |
MySQL user. |
database.password |
'' |
MySQL password. |
database.pool-size |
2 |
Maximum pool connections. |
database.properties |
{} |
Extra JDBC URL properties, e.g. useSSL: 'false'. The session time zone is always UTC. |
refresh.interval-seconds |
300 |
How often every online player is re-read (minimum 10). |
refresh.players-per-tick |
5 |
Players read per tick during a refresh cycle. |
refresh.on-death |
true |
Re-read a player one tick after they die. |
refresh.on-advancement |
true |
Re-read a player one tick after they complete an advancement (recipe unlocks are ignored). |
flush.interval-seconds |
60 |
How often queued values are written (minimum 5). |
placeholders |
DD examples | List of {placeholder, name, empty-values}. name is the stored key: unique, letters, digits and underscores, up to 64 characters. empty-values is optional. Invalid or duplicate entries are skipped with a warning. |
Example entry:
placeholders:
- placeholder: '%dd_user_affinity%'
name: DD_Affinity
- placeholder: '%Advancements_completedAmount%'
name: Adv_Total_Completed
empty-values: ['0']JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew buildThe shaded jar is build/libs/PapiSync-<version>.jar. HikariCP and the MySQL driver are bundled and relocated under au.com.addstar.papisync.lib. BUILD_NUMBER sets the version to 1.0.<build> on CI.