Config YML: Thresholds, Scan Cadence, and Border Vignette

CriticalHealthFX is intentionally built around one public config file. This page covers the global settings that decide when the plugin activates and how strong the red border pressure feels before you even touch individual tiers.

The global trigger block

These settings decide whether the plugin runs at all and who it can affect:

enabled: true
critical_threshold_hp: 10.0
allowed_gamemodes:
  - SURVIVAL
  - ADVENTURE
scan_period_ticks: 2

enabled

Master switch for the whole plugin.

critical_threshold_hp

The HP value where CriticalHealthFX begins. 20.0 HP is full health. 10.0 HP is 5 hearts. The shipped MCWAR default is 10.0.

allowed_gamemodes

Only players in these gamemodes can receive the effect loop. The defaults are:

• SURVIVAL
• ADVENTURE

If an admin reports that the effect is missing in Creative or Spectator, that is expected unless you explicitly add those modes.

scan_period_ticks

How often the runtime evaluates online players.

• lower values feel smoother
• higher values reduce update frequency
• the default 2 ticks is a good live-server baseline

The WorldBorder vignette layer

CriticalHealthFX does not use packets or NMS for the red edge. It uses a per-player WorldBorder warning overlay, which is the safest part of the design.

The global border settings are:

center_update_period_ticks: 2
center_update_min_distance: 0.0
warning_blocks: 24
warning_time: 0
cancel_other_worldborder_packets_while_active: true

center_update_period_ticks

How often the per-player border is re-centered while the effect is active.

center_update_min_distance

The player must move at least this far before the border is re-centered. Use a small non-zero value only if you are trying to reduce tiny movement updates.

warning_blocks

This is the main global intensity knob.

• higher values make the red warning appear more aggressively
• lower values make it subtler

The default 24 is the base before any tier overrides.

warning_time

Usually keep this at 0. CriticalHealthFX is using warning distance for the visible pressure, not warning countdown behavior.

cancel_other_worldborder_packets_while_active

The current code cannot literally cancel another plugin's packets without a packet library, but this setting keeps re-applying the CHFX border while active so CriticalHealthFX can hold its visual state more reliably against other border users.

The two big intensity levers

For the red effect itself, most tuning comes from two places:

1. global or per-tier warning_blocks
2. per-tier diameter

Use this rule of thumb:

• smaller diameter = stronger red
• larger warning_blocks = stronger red

If the red edge is weak even when the player is almost dead, check both.

A good starting baseline

If you want the shipped public default feel, keep this global baseline:

critical_threshold_hp: 10.0
scan_period_ticks: 2
center_update_period_ticks: 2
center_update_min_distance: 0.0
warning_blocks: 24
warning_time: 0

Then let the tiers do the deeper escalation.

When to use global settings vs tier overrides

Use global settings when

• you want the whole plugin to feel lighter or heavier
• every tier should inherit the same baseline
• you are still early in setup and do not want to fine-tune every step yet

Use tier overrides when

• only the lowest tiers need much stronger red pressure
• you want one-heart and half-heart to feel drastically harsher than four or five hearts
• the default global values are fine for most of the curve

Good first mistakes to avoid

Do not lower the threshold if your complaint is "the effect is not red enough"

That only makes the plugin start later. It does not make the existing tiers more intense.

Do not only change warning_blocks

If the low tiers still feel weak, check diameter too. The strongest shipped tiers use much smaller diameters than the higher tiers.

Keep gamemodes in mind during testing

Many false bug reports come from testing in Creative while allowed_gamemodes still only includes Survival and Adventure.

Where to go next

• heartbeat, Blackout, Darkness, and Frost Overlays
• tiers, Heartbeat Curve, and Health Tuning