Skip to content

Statistics

Quick Start: Pick your goal.

Career statistics are enabled by default and stored in statistics.db (SQLite). For shared statistics across servers, switch to PostgreSQL and point every instance at the same database.

With PlaceholderAPI installed, placeholders such as %jmanhunt_career_kills% are available. See the full list on the Placeholders page.

How wins are counted

  • Only participants on the winning side receive a win.
  • career_wins is always the sum of the two role-specific win counts.
  • Match statistics track only in-match hunters and speedrunners.
  • Spectators never accrue statistics.
  • The match clock freezes when the match ends.

Match history

Every finished or cancelled match writes:

  • One row in jmanhunt_matches
  • One row per participant in jmanhunt_match_players

Data is saved the moment the match ends.

Match row contains winner, end reason (FINISHED or cancel reason), kill/death totals (with role splits), combined match score, MVP id + score, both team leaders, peak roster counts, modifier count, lobby id, ranked flag.

Player row contains kills, deaths, score, damage dealt/taken, role, MVP flag, ranked Elo delta (populated only for ranked matches; otherwise null, including cancelled ranked matches).

Important rules

  • Scores are clamped at zero for storage, career totals, and placeholders (live ledgers may go negative).
  • The MVP id is stored with the score so later scoring changes never rewrite who earned it.
  • Cancelled matches keep their rows, but career totals and lifetime aggregates ignore them. The overall match count still increments.
  • Player names are stored next to UUIDs; placeholders accept either.

Browse a stored match in-game with /manhunt match history <match-id>. Any field can also be read through the match by id placeholders. Score, MVP, and leader calculations are documented on the Match Score page.

Database configuration

statistics:
  enabled: true
  leaderboards:
    min-matches: 3
  connection:
    type: sqlite          # or postgresql
    pool-size: 4
  sqlite:
    file: statistics.db
  postgresql:
    host: localhost
    port: 5432
    database: jmanhunt
    username: jmanhunt
    password: change-me
    ssl: false
Setting Behaviour
enabled: false Statistics stay in memory only and are lost on restart.
pool-size Number of open connections. SQLite always uses 1 (single-writer); the value only affects PostgreSQL.
leaderboards.min-matches Minimum matches required before a player appears on KDR leaderboards. 0 disables the filter. Takes effect on reload.

Monthly and weekly leaderboard periods need no configuration. Finished matches fold into the current week (Sunday to Sunday, server-local) and calendar month. Older periods prune themselves. The timed _monthly and _weekly placeholders read the live buckets (see Timed periods).

Engine state

The world-engine cell index and the crash-cleanup roster live in engine.db. This file is always SQLite and requires no configuration.

After a crash, listed players are wiped back to normal on their next join. Clean restarts wipe nobody.

Upgrading

Upgrading from jmanhunt.db:

  • Rename that file to statistics.db to keep your stored statistics.
  • Reload. Existing database settings move to the new statistics section automatically.
  • The cell index starts fresh in a new engine.db file.
  • Older databases receive new columns on first boot via ALTER TABLE (duplicate-column errors are ignored). No other migration is performed.