Feature: Block Break Guard

Feature: Block Break Guard

This feature validates block-break progress server-side before accepting the break.

Config Surface

stratum.default.json has a dedicated BlockBreakGuards section:

"BlockBreakGuards": {
  "Enabled": true,
  "RequireServerSelection": false,
  "DropViolations": true,
  "LogViolations": false,
  "KickViolations": false,
  "KickAfterViolations": 12,
  "ViolationWindowSeconds": 20,
  "RequiredProgressRatio": 0.5,
  "GraceSeconds": 0.5,
  "MinimumTrackedBreakSeconds": 0.5,
  "KickMessage": "Disconnected by Stratum block break protection"
}

Runtime Flow

Implementation class: StratumBlockBreakGuard.

1. Mining observation

ObserveMining tracks progress while the player is actively mining:

state.RequiredResistance = resistance;
state.DamagePerSecond = damagePerSecond;
state.ObservedDamage += damage;
state.LastObservedMs = server.ElapsedMilliseconds;

2. Break validation

TryAcceptBreak checks whether observed progress meets the configured threshold.

Fast breaks can bypass tracking by design:

if (resistance <= 0f || expectedBreakSeconds <= Math.Max(0f, config.MinimumTrackedBreakSeconds))
{
    return true;
}

Progress requirement:

float ratio = Math.Max(0.1f, Math.Min(1f, config.RequiredProgressRatio));
float requiredDamage = resistance * ratio;
float observedWithGrace = state.ObservedDamage + Math.Max(0f, config.GraceSeconds) * Math.Max(state.DamagePerSecond, damagePerSecond);
if (observedWithGrace < requiredDamage)
{
    reason = $"insufficient mining progress {observedWithGrace:0.###}/{requiredDamage:0.###} on {requestedSelection.Position}";
}

3. Violation action

state.RegisterViolation(now, Math.Max(1, config.ViolationWindowSeconds));
shouldKick = config.KickViolations && config.KickAfterViolations > 0 && state.ViolationsInWindow >= config.KickAfterViolations;

Result behavior:

• Accept break
• Drop break
• Kick client (if enabled and threshold reached)

What The Defaults Mean

• DropViolations=true: reject suspicious breaks without always disconnecting
• KickViolations=false: default behavior is protection without aggressive disconnects
• MinimumTrackedBreakSeconds=0.5: very fast blocks can bypass progress tracking
• RequiredProgressRatio=0.5: accept breaks once at least half required progress is observed, plus grace window

Related Code

• sources/VintagestoryLib/Vintagestory/Server/StratumBlockBreakGuard.cs
• sources/VintagestoryLib/Vintagestory/Server/StratumConfig.cs (StratumBlockBreakGuardsConfig)
• StratumServer/stratum.default.json
• sources/VintagestoryLib/Vintagestory/Server/CmdStratum.cs (/stratum packets report)