Configuration Files
All configuration files are generated automatically on first server start with default values. No manual creation is required.
Paper plugin path: plugins/ProtectedAreaPlugin/
Fabric server mod path: config/ProtectedArea/
| File | Purpose |
|---|---|
Config/Config.yml | Global settings: mod enforcement, kick message, and hidden areas. |
AreaNotification/Rules.yml | Messages shown to players when a basic rule blocks their action. |
AreaNotification/AdvancedRules.yml | Messages shown when an advanced rule blocks a specific block, entity, or item. |
Areas/ | One YAML file per cube area. Managed automatically. |
Areas/.flat/ | One YAML file per flat area. Managed automatically. |
Areas/.dimension/ | One YAML file per Minecraft dimension. Provisioned automatically at server start. See Dimension Area Files. |
assets/skybox/ | PNG textures for skyboxes (Fabric server mod only — for distribution to clients). |
Config/Config.yml
# Whether players MUST have the client mod installed to join.
# When true, players without the mod are kicked on join.
mod-required: false
# The message shown to kicked players.
# Supports legacy Minecraft color codes (§).
kick-message: "§c¡Necesitas tener el mod de cliente instalado para jugar en este servidor!"
# Folder prefixes to hide from tab-completion suggestions.
# Areas in these folders still exist and commands still work on them manually.
# Use ".flat//" for flat areas, "/" for cube areas.
areas-hidden:
- interno/ # cube areas inside Areas/interno/
- .flat/sistema/ # flat areas inside Areas/.flat/sistema/ | Key | Type | Default | Description |
|---|---|---|---|
mod-required |
Boolean | false |
If true, players without the client mod are kicked on join. |
kick-message |
String | See default above | The kick screen message. Supports legacy §-codes. |
areas-hidden |
List<String> | [] |
Folder prefixes whose areas are hidden from tab-completion. See Hidden Areas. |
After editing Config.yml, run /area reload config to apply changes.
Dimension Area Files
Dimension areas live under Areas/.dimension/, one YAML file per Minecraft dimension.
You never create these files: at server start the plugin scans every loaded world and writes a file
for each dimension that does not already have one. An existing file is never overwritten, and the
file of a dimension that has disappeared is never deleted.
The filename comes from the dimension key with its namespace turned into a folder, because
: cannot appear in a filename on Windows. The dimension key
minecraft:the_nether gives the area ID minecraft/the_nether and the path
Areas/.dimension/minecraft/the_nether.yml. The dimension key inside the
file still holds the real key, colon included.
# Written automatically on first server start.
id: minecraft/the_nether
type: dimension
dimension: minecraft:the_nether
alias: ''
priority: -1
skybox: ''
rules: []
# Added only once you grant an exception with
# /area dimension exception add "minecraft/the_nether" <player> <rule>
exceptions:
no_break:
- Marquinho
all:
- Steve| Key | Type | Default | Description |
|---|---|---|---|
id |
String | — | The area ID, derived from the dimension key with the namespace as a folder (minecraft/the_nether). It matches the file path under Areas/.dimension/. |
type |
String | dimension |
Marks the file as a dimension area. This is what tells the loader to skip coordinate parsing. |
dimension |
String | — | The real Minecraft dimension key, colon included (minecraft:the_nether). This is the value matched against the world a player is in. |
alias |
String | '' |
Optional human-readable name. |
priority |
Integer | -1 |
Controls whether areas inside the dimension inherit from it. Because cube areas default to 0, nothing inherits from a dimension area until this is raised. See Priority. |
skybox |
String | '' |
PNG texture name for a dimension-wide sky, without the .png extension. Empty means no skybox. See Skybox. |
rules |
List<String> | [] |
Basic rule keys applied across the whole dimension. |
exceptions.<rule> |
List<String> | absent | Player names allowed to bypass that rule. The all key bypasses every rule. The section only appears once an exception is granted. |
Keys that are deliberately absent
A dimension area has no geometry and no boundary, so the following cube and flat keys never appear in these files and are ignored if you add them by hand:
| Key | Why it is absent |
|---|---|
xyz1 / xyz2 | A dimension area is coordinate-less; it covers the whole dimension. |
color | There is no border to render an outline for. |
playerLimit / limitBlocked | The player limit works by pushing players back outside the area, and a dimension has no outside. |
commandEntry / commandExit | These fire on crossing the area boundary, which does not exist here. |
flatPosition | Flat-area only — the coordinate of a crossing plane. |
pass.negative / pass.positive | Flat-area only — per-side passage control. |
Advanced rules are stored separately from the area file, under
Advanced/Rules/.dimension/<id>.yml — the same layout cube areas use, with the
.dimension/ prefix mirroring the area folder.
Notifications
Notification messages are sent to players when a rule blocks their action.
All messages use MiniMessage format, which supports colors, gradients,
bold, italic, hover text, and more.
You can preview and build MiniMessage strings at
webui.advntr.dev.
Setting a message to an empty string ("") suppresses it entirely.
MiniMessage Format
| Tag | Result |
|---|---|
<red>text</red> | Red text |
<gold>text</gold> | Gold text |
<bold>text</bold> | Bold text |
<#FF4400>text</> | Custom hex color |
<gradient:#FF0000:#0000FF>text</gradient> | Color gradient |
AreaNotification/Rules.yml
Controls messages for basic rule violations.
no_break: "<red>You cannot break blocks in this area.</red>"
no_place: "<red>You cannot place blocks in this area.</red>"
no_place_fluid: "<red>You cannot place fluids in this area.</red>"
no_interact: "<red>You cannot interact in this area.</red>"
no_interact_entity: "<red>You cannot interact with entities in this area.</red>"
no_interact_vehicle: "<red>You cannot mount vehicles in this area.</red>"
no_interact_inventory: "<red>You cannot open inventories in this area.</red>"
no_pvp: "<red>You cannot attack players in this area.</red>"
no_entityattack: "<red>You cannot attack entities in this area.</red>"
no_drop: "<red>You cannot drop items in this area.</red>"
no_collect: "<red>You cannot pick up items in this area.</red>"
# Set to "" to send no message for barrier collisions
no_entry_collision: ""
no_exit_collision: ""
no_exit_returned: ""| Key | When triggered |
|---|---|
no_break | Player tries to break a block. |
no_place | Player tries to place a block. |
no_place_fluid | Player tries to place water or lava with a bucket. |
no_interact | Player tries to interact with a block (container, button, etc.). |
no_interact_entity | Player tries to right-click an entity. |
no_interact_vehicle | Player tries to mount a vehicle (boat, minecart, horse). |
no_interact_inventory | Player tries to open an entity's inventory (chest minecart, etc.). |
no_pvp | Player tries to hit another player. |
no_entityattack | Player tries to hit a non-player entity. |
no_drop | Player tries to drop an item. |
no_collect | Player tries to pick up an item. |
no_entry_collision | Player is physically stopped by a no_entry barrier. |
no_exit_collision | Player is physically stopped by a no_exit barrier. |
no_exit_returned | Player is teleported back into the area after escaping a no_exit area. |
AreaNotification/AdvancedRules.yml
Controls messages for advanced rule violations. These support placeholders that are replaced with the actual block, entity, or item involved in the action.
no_break_specific: "<red>You cannot break <gold>{blockid}</gold> in this area.</red>"
no_place_specific: "<red>You cannot place <gold>{blockid}</gold> in this area.</red>"
no_place_fluid_specific: "<red>You cannot place <gold>{blockid}</gold> in this area.</red>"
no_interact_block: "<red>You cannot interact with <gold>{blockid}</gold> in this area.</red>"
no_interact_entity: "<red>You cannot interact with <gold>{entityid}</gold> in this area.</red>"
no_interact_vehicle: "<red>You cannot mount <gold>{entityid}</gold> in this area.</red>"
no_interact_inventory: "<red>You cannot open the inventory of <gold>{entityid}</gold>.</red>"
no_drop_specific: "<red>You cannot drop <gold>{itemid}</gold> in this area.</red>"
no_collect_specific: "<red>You cannot pick up <gold>{itemid}</gold> in this area.</red>"Available Placeholders
| Placeholder | Value | Example |
|---|---|---|
{blockid} | The full Minecraft block ID including namespace. | minecraft:stone |
{block} | The block name without the minecraft: prefix. | stone |
{entityid} | The full Minecraft entity type ID including namespace. | minecraft:villager |
{entity} | The entity name without the minecraft: prefix. | villager |
{itemid} | The full item ID including namespace. | minecraft:diamond |
{item} | The item name without the minecraft: prefix. | diamond |
{areaid} | The area identifier. | spawn |
{player} | The player's name. | Marquinho |
Mod Verification
The plugin can optionally require all players to have the client mod installed. When enforcement is enabled, the server sends a verification packet to each player on join. Players who do not respond with the correct handshake within a short window are kicked with the configured message.
Verification Flow
-
Player joins
The
ModVerificationListenerdetects the join event and sends a verification packet to the client. -
Client responds
If the client mod is installed, it automatically sends back a verification response on the
protectedarea:mainchannel. -
Server evaluates
Players who respond correctly are marked as verified and continue normally. Players who do not respond (e.g. vanilla clients) are kicked with the message defined in
Config/Config.yml.
Commands
| Command | Description |
|---|---|
/area config mod-required | Display current enforcement status and the kick message. |
/area config mod-required true | Enable enforcement. Players without the mod are kicked on join. |
/area config mod-required false | Disable enforcement. The mod becomes optional. |
/area reload config | Reload Config.yml to pick up manual edits. |
Configuration
mod-required: true
kick-message: "§cYou need the ProtectedArea client mod to play on this server."
The kick message supports legacy Minecraft color codes using the § character.
It is shown on the connection-refused screen and supports multiple lines using \n.