Performance Guide

Obfeco is built so a balance change never waits on the database. The defaults suit almost every server; this page explains what's happening so you know which knob to turn if you need to.

How balances are handled

• Join: all of a player's balances are loaded with one query, whatever the number of currencies.
• While online: reads and changes happen in memory. Changes are marked to be saved.
• Batch save: every cache.batch-save-interval seconds (default 120), changed balances are written to storage. Players offline for more than a minute with nothing left to save are then dropped from memory.
• Quit: with cache.auto-save-on-quit: true (default), a player's changes are saved right away. A quick rejoin always reads what that save wrote.
• Shutdown: everything still unsaved is written before the plugin disables.

Database work runs on Obfeco's own threads, never the server thread. Each player always uses the same database thread, so a quit save and the next join load can't overtake each other. Leaderboards and totals use a separate thread so they never hold up a join. SQLite uses one database thread, YAML two, and MySQL up to four depending on pool-size.

Offline players (a give to someone who isn't online, a Vault plugin paying an offline seller) are loaded on demand and saved with the next batch.

Tuning

cache.batch-save-interval

Seconds between batch saves.

• Lower (30–60) means less to lose if the server crashes and leaderboards that catch up faster, for slightly more database writes.
• Higher (300+) means fewer writes. Only worth it on a slow remote database.

The default of 120 is a good middle ground. Only changed balances are written, so a lower value costs little on SQLite.

cache.auto-save-on-quit

Leave this on, especially on a network sharing MySQL: it's what makes a player's balance follow them to the next server. With it off, a quitting player's changes wait for the next batch save.

placeholder.top-cache-minutes

How long leaderboard and total results are kept before a background refresh. Lower it (1–2) for a livelier scoreboard, raise it if you have thousands of currencies on leaderboards and a busy database. Placeholders never wait for the refresh either way.

Choosing storage

Server	Storage
Single server, any size	SQLITE
Network sharing balances	MYSQL
Small server, wants to edit balances by hand	YAML

YAML leaderboards and totals read every player file, so they get slower as the player count grows. SQLite and MySQL use an index on (currency_id, balance). See Database Setup.

Many currencies

Each currency is a small YAML file, read in parallel on start and on /obfeco reload. Balances for every currency sit in one table, so loading a player is still one query with hundreds of currencies. Use Categories to keep the manager GUI usable.