Scuffed Protection

Install, region-editing, flag, permission, configuration and API reference for server operators. For what players see in protected areas (build denials, safe zones, titles, map tint) see the Scuffed Protection gameplay guide.

• Plugin version: 1.1.54 (plugin name ScuffedProtection)

Scuffed Protection is a chunk-based region and world-protection plugin. A region owns a set of 32 x 32 chunks (full height) or a whole world, and carries a build policy, a list of tri-state flags, members, messages, commands, movement and weather settings. Everything is managed from one in-game page opened with /sp.

Requirements

The jar ships an asset pack (the management page, the border particle and the Unified UI kit). No other plugin is needed.

Protection only runs in worlds that have at least one region, a world region, or an entry in fullWorldProtection. In any other world (dungeon instances, for example) every system returns immediately, so the plugin costs nothing there.

Admin & Staff Commands

There is one command, registered under two names. It is a player command: it cannot be run from the console.

Without the manage or bypass permission the command answers You don't have permission to manage protection regions.

The management page

Every change on the page is applied and saved immediately. There is no save button and no reload step.

A new region starts empty. Each chunk can belong to only one region: adding a chunk that another region owns shows That chunk belongs to another region. There are no overlapping regions and no priorities. The two layers are:

1. A chunk region wins wherever it has a chunk.
2. A world region (one per world) covers every chunk with no region of its own.

If you create a new region while standing in a world that has a world region, the new region starts as a full copy of that world region's flags, members, build policy, messages and commands, so you only change what differs.

Region settings in detail

Command placeholders in enter and exit commands: %player% (player name) and %region% (region name). Titles accept %region%.

Blocked and allowed commands do not apply to members, exempt players or bypass users. They are enforced by wrapping the commands that exist when the plugin starts, so a command registered by a plugin that loads later is not covered.

Server-side enter and exit commands run with console authority. Turn on enterCommandWhitelistEnabled and list the permitted command names in enterCommandWhitelist to restrict them (it filters server commands only, not the player command).

Server settings view

Flags

A flag is tri-state per region: allow, deny or default (unset). Unset flags use the configured default, which differs between a normal chunk region and a world region, meaning a region applied to an entire world (see flagDefaultsRegion and flagDefaultsGlobal). A flag button on the page sets an explicit allow or deny; flags you never touch stay on default.

The key column is the exact name used in claims.json, in the flag default maps and by other mods. Aliases are also accepted in claims.json and through the API (for example fall, chest, lava, harvest).

Notes on the table:

• Twenty flags have a button on the Region settings view: pvp, pve, entry, exit, mob-spawning, entity-entry, chest-access, use, door-access, seat, crafting, damage, fall-damage, mob-damage, knockback, pet-damage, fluid-place, keep-inventory, particles and quest-npcs. fly and map are on the Movement & minimap view. notify, item-pickup and item-drop have no button; set them in claims.json (see Data & storage).
• Access flags (chest-access, use, door-access, seat, crafting, fluid-place): an unset flag uses the configured default, and members pass even when that default is deny. An explicit allow lets everyone through, an explicit deny blocks members too. Exempt players always pass.
• pve, pet-damage, entry and exit: members and exempt players always pass, even with an explicit deny.
• light-access, item-grab, fire-spread, grass-spread and mushroom-spread exist as flag keys so other mods can query and set them, but this plugin does not enforce them itself.
• Bypass users (permission, session toggle or creative bypass) skip the build, access, entry, exit, PvE, pet, crafting, item and command checks. They are not exempt from pvp, damage, fall-damage, mob-damage, knockback or keep-inventory, because those describe the zone and not the player.
• Mob exemptions: the global mobCullBlacklist, the region's mob whitelist, and optionally every NPC that carries a display name (mobCullExemptNamedNpcs).

Build policy and what counts as building

The build policy (MEMBERS, EVERYONE, NOBODY) is checked for: placing, breaking and mining blocks; crop harvesting, fertilizing and watering; block state changes and variant cycling; bucket fluid placement and refilling; capture crates (checked at the target); and explosions (checked at the centre only, so a blast that starts outside and reaches in is not caught). It is enabled by protectionBlocks; explosions use their own switch protectionExplosions.

Denied build actions show You can't build here. or You can't build in '<region>'. (rate limited to one message per 1.5 seconds per player). Chest, door, use, crafting, item and PvP denials are silent. Entry, exit and command denials always message the player (entry and exit at most every 2 seconds).

Whole-world protection

Add a world name (case-insensitive) to fullWorldProtection, or turn a region into a world region with Apply to entire world. The two differ:

Use fullWorldProtection for a lockdown spawn or hub; use a world region when you want a baseline with normal editing, then carve out chunk regions that differ.

Permissions

Only two permission nodes exist. Their names are config values.

Creative mode never grants access to the page; it only bypasses protection when creativeModeBypassProtection is on.

An empty value for either key means "everyone has it". Do not blank managePermission on a live server, or every player can edit regions.

permissionPrefix and permissionOverrides are present in the config file but no permission check reads them.

Configuration

File: config/config.json inside the plugin's ScuffedProtection data folder. It is written with all defaults on first start. Edits made with the management page are saved at once; edits made to the file by hand are read at startup, so restart the server (or reload the plugin) afterwards. Keys missing from the file keep their defaults. A corrupt file is moved aside as config.json.corrupt-<time> and the .bak copy is tried.

Master and protection switches

protectionHarvestTools, protectionMultiBlockTools, protectionFluidFlow and protectionNaturalSpread also appear in the file but nothing reads them: sickle, hammer and fluid-placing protection is always part of protectionBlocks.

Lists and defaults

Example: make chests open by default in every normal region and keep PvP off.

"flagDefaultsRegion": { "chest-access": "allow", "pvp": "deny" }

Titles

Map and particles

mapEnabled, updatesNotify, titlesPriority, particlesOnlyRealBoundaries and particlesMatchByXZOnly are in the file but unused. Only explicitly claimed chunks are tinted and given border particles; a world region does not paint the whole map.

Language file

lang/en_US.properties is created on first start. Edit the values to reword or translate; missing keys are added back, and extra keys you add are kept. Messages are prefixed with [ScuffedProtection] (prefix.text, prefix.color) and coloured by level (color.info, color.success, color.warn, color.error).

The file also defines deny.pickup, deny.use, deny.container, deny.door, deny.light, deny.pvp, deny.item_drop (each with a _region variant for most), region.enter, region.exit, create.ok and delete.ok. The plugin does not currently send these. A region's own deny message replaces the text of the five keys in the table.

Data & storage

All files live in the plugin's ScuffedProtection data folder.

Every JSON write goes to a temp file, is flushed, keeps the previous version as <file>.bak, then replaces the live file atomically. A file that fails to parse is moved aside as <file>.corrupt-<time> and the .bak is loaded instead, so one bad file never stops the plugin from starting. Region edits are saved about 0.9 seconds after the last change and again at shutdown.

claims.json holds a formatVersion (currently 2), a regions list and a chunks list.

Edit claims.json only while the server is stopped; the plugin rewrites it from memory. A chunk entry that names a missing region is dropped on load. Deleting a region unassigns all of its chunks.

Integrations

EndlessGuilds

Protection and Guilds both wrap the same engine interactions (fluid placement, block changes, crop harvest, fertilizing, farming stages, bucket refill and several more), and only one plugin can own each. Protection takes these back before assets decode and, at startup, registers a hook that asks Guilds about every decision made inside a guild claim. The hook can only add denials, never lift one: if either system denies, the action is denied. Guild harvest uses the HARVEST permission, fertilizing, watering and state changes use INTERACT, and other terrain edits use BUILD. Guild wartime farm and animal protection is respected. A Protection bypass does not bypass Guilds; use Guilds' own bypass for that. If Guilds is reloaded, reload or restart Protection afterwards. If another plugin re-registers one of the guarded interaction ids, the log warns that Protection took them back and that the other plugin's own checks for those ids will not run.

World map conflicts

Protection installs its own world-map provider. If another map mod (WorldProtect, for example) sets a provider on the same world, the region tint may not show; remove the other provider.

PlaceholderAPI placeholders

Identifier scuffedprotection, author Zbeve.

API for other mods

Everything below is plain Java in the package com.zbeve.scuffedprotection.api.

ScuffedProtectionApi

ScuffedProtectionApi.get() returns the instance, or null before Protection has started. Static helpers need no instance.

RegionInfo exposes id(), displayName(), members(), exempt(), isMember(uuid), isExempt(uuid), chunkCount(), isFlagAllowed(flagKey) and overriddenFlags(). It is read-only. These queries return "allowed" when Protection is disabled or the land is unprotected.

Hooks

registerHook(ProtectionHook) and unregisterHook(...) let a mod influence allow and deny decisions. The hook receives a ProtectionQuery (action, player, world, x, y, z, regionId, and interactionId for engine interactions such as HarvestCrop) and returns ALLOW, DENY or NEUTRAL.

• action is build for block edits, or a flag key such as chest-access, use, door-access, seat, crafting or fluid-place.
• Any DENY wins; otherwise any ALLOW grants access even where the region would deny; otherwise the region's own answer stands.
• Hooks run on the hot path. Keep them fast and side-effect free. A hook that throws is treated as NEUTRAL and logged once.
• Hooks apply to build and access-flag checks only, not to PvP, damage or spawning.

Map claim providers

registerMapClaimProvider(key, provider) and unregisterMapClaimProvider(key). A MapClaimProvider returns tintAt(world, chunkX, chunkZ) as 0xRRGGBB, or 0 for no claim. Protection draws it on the world map wherever it has no region of its own. Call invalidateMapChunk(world, chunkX, chunkZ) after a claim changes.

Weather

• registerWeatherProvider(key, (worldName, packedChunkIndex) -> weatherId) lets a mod with its own land force a sky on whoever stands in it. A region's own weather beats a provider, and providers are skipped while the world itself forces a weather. The function runs on the world thread for every player each tick, so it must be an in-memory lookup. unregisterWeatherProvider(key) removes it. Only JDK types cross this boundary.
• previewWeather(playerUuid, weatherId, seconds) shows a weather on one player for up to 120 seconds, saves nothing, and returns false if the weather does not exist. endWeatherPreview(playerUuid) stops it early.

External no-spawn areas (SpawnProtectionAPI)

SpawnProtectionAPI.register(owner, predicate) adds an area where new NPC spawns are removed. The predicate is a BiPredicate<String, int[]> called with the world name and {blockX, blockY, blockZ}. It must be fast, thread-safe and do no disk or network work. The call returns an AutoCloseable; close it when your mod stops. Registering the same owner twice throws. The area goes through the normal new-spawn filter: protectionMobSpawning must be on, the cull blacklist, region whitelists and named-NPC exemption still apply, and mobCullHideInsteadOfRemove decides whether mobs are hidden or removed. Registering does not remove mobs that already exist and does not change saved regions. A failing provider is logged once and does not cause a spawn to be suppressed or break the tick.

Troubleshooting