Operate ShieldPlay with confidence.

What ShieldPlay does

ShieldPlay combines a Paper-compatible Minecraft agent with a cloud dashboard. The agent observes server-authoritative gameplay events, submits bounded telemetry and violations, while the dashboard gives owners and staff one place to review evidence, server health, access and notifications.

The product is designed around a conservative principle: a flag is evidence for review, not an automatic verdict. Combat heuristics and X-Ray findings remain review-only by default; automatic punishment requires separately eligible, sustained and independent evidence.

Before you install

Use a modern Paper/Purpur/Spigot-compatible server and Java 21 for the current agent build.

Do not place a dashboard session token or Stripe credential in the Minecraft configuration. The agent only needs its own server-specific API key.

Install and connect the agent

• Download the current ShieldPlay agent JAR from the Download page.
• Stop the Minecraft server and copy the JAR to its plugins directory.
• Start the server once to create the plugin configuration, then stop it or use the reload command after editing.
• In the dashboard, register the Minecraft server and create or rotate its server API key.
• Set the cloud URL and key in the agent configuration, then start the server and confirm the connection in the dashboard.

cloud:
  api-base-url: "https://api.shieldplay.it/api/v1"
  api-key: "PASTE_THE_SERVER_SPECIFIC_KEY_HERE"
  heartbeat-interval-seconds: 30
  request-timeout-seconds: 12

Treat api-key as a secret. Do not publish it in screenshots, Git repositories, Discord messages or client-side code.

Commands and access

The in-game administration permission is anticheat.admin. Dashboard staff access is separately synchronized by UUID. Keep that roster narrow and use per-check exemptions only for controlled testing or trusted operational tools.

Detection and review policy

ShieldPlay deliberately distinguishes data collection, an alert and a sanction. A low-confidence signal can be logged without increasing risk or opening an incident. Correlations can help staff understand repeated behavior, but they are not autonomous evidence for automatic punishment.

The geometric Hitbox check traces the player eye ray against an expanded server-side target bounding box. It skips unstable contexts such as high ping, low TPS, recent movement transitions and special movement states. Paper provides event-time server geometry rather than full client-view rewind, so the result is intentionally review-only.

Configure X-Ray thoughtfully

X-Ray is evaluated only when a player breaks monitored rare blocks. A pattern must meet several conditions together: enough blocks mined, enough concealed rare ores, sufficient density and a bounded burst duration. Air, water and lava exposure is excluded to reduce false positives.

checks:
  movement:
    xray:
      rare-ores:
        - DIAMOND_ORE
        - DEEPSLATE_DIAMOND_ORE
        - EMERALD_ORE
        - DEEPSLATE_EMERALD_ORE
        - ANCIENT_DEBRIS

The Owner can also select the allowed vanilla materials in the Minecraft Staff dashboard. Removing the dashboard override returns control to config.yml.

Staff, language and exemptions

Owners manage the server staff roster in the Minecraft Staff module. They can choose Italian or English for the in-game GUI and staff alerts, and can grant an exemption for an individual check to an individual staff UUID. Exemptions are exact, checked before profiling and reporting, and never use wildcard rules.

Discord and outgoing webhooks

Create a channel webhook in Discord, then add it in Dashboard → Webhooks and subscribe it to Flag X-Ray. ShieldPlay renders Discord endpoints as an embed with player, server, ore and review-only status. Generic webhooks keep a JSON event envelope for external systems.

notifications:
  discord:
    xray:
      enabled: true
      embed:
        title: "ShieldPlay · Flag X-Ray"
        description: "{player} mined {hidden_ores} concealed ores. Last: {ore}."
        color: "#F59E0B"
      rate-limit:
        cooldown-seconds: 60

The effective X-Ray Discord cooldown is clamped to 15–600 seconds per webhook. Flags are still stored during the cooldown; only repeated chat notifications are suppressed.

Operational checklist

• Check the server heartbeat, TPS and agent version after each plugin update.
• Review new violations alongside ping, TPS, context exclusions and prior evidence before acting.
• Use the unban flow in the dashboard so the persisted punishment and Paper profile pardon stay aligned.
• Rotate a server key if it was exposed, then update only that server’s config.yml.
• Use the Webhooks Test action before relying on an alert channel during an incident.

Troubleshooting