ThreatMeter

ThreatMeter

ThreatMeter is a lightweight danger-awareness plugin for Paper servers. It calculates each player's current threat level from nearby mobs, health, recent damage, darkness, hunger, fire, air, environment, world danger, and optional PvP pressure.

It is designed for SMP servers that want useful survival feedback without changing combat or revealing unfair information.

Threat Levels

• SAFE
• LOW
• MODERATE
• HIGH
• EXTREME

Features

• Scores nearby hostile mobs by type, distance, and configured weight.
• Counts major threats such as Wardens, Withers, Ender Dragons, Ravagers, Evokers, Creepers, and other dangerous mobs.
• Tracks low health, critical health, and absorption-aware effective health.
• Tracks recent meaningful damage with configurable decay.
• Adds threat from darkness, hunger, fire, low air, and optional nearby lava scanning.
• Supports per-world score multipliers.
• Supports optional PvP threat, disabled by default to avoid turning the plugin into player radar.
• Supports actionbar, bossbar, and chat-on-change display modes.
• Lets players toggle their own display with /threatmeter toggle.
• Includes debug output showing the main threat contributions.
• Provides storage status, forced save, backup, and reload commands.
• Emits an event when a player's threat level changes.
• Registers an API so other plugins can read current threat snapshots.

Integrations

ThreatMeter works standalone, but it can integrate with other plugins.

Teamwork:

• If Teamwork is installed, ThreatMeter can read the player's active trusted teammate count.
• Trusted nearby teammates can reduce the current threat score by a configurable capped amount.
• This makes organised groups feel safer without removing danger completely.
• Controlled in config.yml under integrations.teamwork.

Developer/API integrations:

• Registers ThreatMeterApi.
• Other plugins can request a player's current or last known ThreatSnapshot.
• Emits PlayerThreatLevelChangeEvent when a player's level changes.
• Other plugins can listen for threat changes and react with rewards, warnings, quests, stats, or custom mechanics.

Permissions:

• ThreatMeter uses standard Bukkit permission nodes, so it works with Bukkit-compatible permission managers.

Display Modes

Available display modes:

• ACTIONBAR
• BOSSBAR
• CHAT_ON_CHANGE
• OFF

The default actionbar mode is quiet. It only appears when the threat level changes, and SAFE is hidden by default. Server owners can enable continuous actionbar updates in the config.

Commands

Main command aliases:

• /threatmeter
• /threat

Common commands:

• /threatmeter status
• /threatmeter status <player>
• /threatmeter toggle
• /threatmeter debug
• /threatmeter storage
• /threatmeter save
• /threatmeter backup
• /threatmeter reload
• /threatmeter help

Permissions

• threatmeter.command
• threatmeter.view
• threatmeter.toggle
• threatmeter.status
• threatmeter.debug
• threatmeter.storage
• threatmeter.save
• threatmeter.backup
• threatmeter.reload
• threatmeter.admin

Storage and Security

ThreatMeter stores player display preferences by UUID. YAML storage works out of the box, and SQLite, MySQL, and MariaDB are available for larger setups.

Security-focused storage behaviour includes:

• Secure MySQL and MariaDB JDBC examples using certificate or hostname verification.
• JDBC credential redaction in storage status and diagnostics.
• Credential-like JDBC query parameters stripped before database connections are opened.
• Atomic YAML saves where supported by the filesystem.
• Corrupt YAML data is backed up before defaults are loaded.
• Database save failures are reported and retried instead of silently ignored.

Use /threatmeter storage to verify the active backend, /threatmeter save to force a write, and /threatmeter backup to export current in-memory player settings.

Performance

ThreatMeter scans nearby entities per eligible player at a configurable interval. It skips creative, spectator, and dead players by default, avoids global entity scans, checks light at the player's current block, and cleans up display state on quit, reload, and disable.

Notes

ThreatMeter is observational. It does not modify combat, damage, mob behaviour, spawning, permissions, player movement, or world protection. PvP threat is disabled by default, and player names are not revealed unless explicitly enabled.