Skip to content
AddstarMCPublic

About

Sync PlaceholderAPI data to a database

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

PapiSync

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.

How it works

  • 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.

Empty values

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_ONLINE and NO_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.

Database

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.%';

Commands

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.

Permissions

Permission Default Gates
papisync.admin op /papisync and all subcommands

Configuration

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']

Building

JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew build

The 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.

About

Sync PlaceholderAPI data to a database

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages