PROTECTS ALLAM - COMPLETE DOCUMENTATION
TABLE OF CONTENTS
1. Introduction
2. Installation & Setup
3. Commands Reference
4. Permissions System
5. Configuration Guide
6. Protection Flags
7. Multi-Language System
8. Claim Prevention
9. Effects System
10. Troubleshooting
1. INTRODUCTION
Protects Allam is a professional area protection plugin designed for Minecraft servers running Spigot, Paper, or compatible forks. It provides comprehensive territory management with dual protection methods, advanced configuration options, and multi-language support.
Key Highlights:
- Two protection creation methods (AxA and Selection-based)
- JSON storage with automatic backup and recovery
- 7 independent protection flags per area
- Claim prevention system for popular land protection plugins
- Multi-language support (6 languages included)
- Sound and particle effects for user feedback
- Zero external dependencies
2. INSTALLATION & SETUP
Requirements:
- Minecraft Server: 1.17.x to 1.21.x
- Server Software: Spigot, Paper, or compatible fork
- Java Version: 17 or higher
Installation Steps:
1. Download the ProtectsAllam.jar file
2. Place it in your server's plugins folder
3. Restart your server
4. Plugin will generate default configuration files
5. Configure settings in config.yml
6. Reload with /protectreload
Generated Files:
Code (Text):
plugins/ProtectsAllam/
├── config.yml (Main configuration)
├── protections/ (Protection data)
│ ├── world.json (Protections for 'world')
│ ├── world_nether.json (Protections for nether)
│ └── world_the_end.json (Protections for end)
├── backups/ (Automatic backups)
│ ├── world_backup_1.json
│ └── ...
└── languages/ (Translation files)
├── en.yml
├── pt_br.yml
├── es.yml
├── it.yml
├── ru.yml
└── zh_cn.yml
3. COMMANDS REFERENCE
AREA CREATION COMMANDS
/areaprotect <X> <Z> <name>
Description: Creates an AxA protection at coordinates X,Z
Permission: protects.create
Usage Examples:
Code (Text):
/areaprotect 50 50 SmallSpawn
Creates a 50x50 protection centered at your current X,Z
/areaprotect 200 200 MainSpawn
Creates a 200x200 protection centered at your current X,Z
/pset 1
Description: Sets the first selection point at your current location
Permission: protects.create
Notes: Stand at the first corner and run this command
/pset 2
Description: Sets the second selection point at your current location
Permission: protects.create
Notes: Stand at the opposite corner and run this command
/protect <name>
Description: Creates protection using your two selected points
Permission: protects.create
Requirements: Must have both points set with /pset 1 and /pset 2
Usage Example:
Code (Text):
/protect MyBase
Creates protection with previously set points
MANAGEMENT COMMANDS
/protectlist
Description: Lists all protected areas with detailed information
Permission: protects.list
Output: Shows name, world, size, creator, and creation date
/protectinfo <name>
Description: Displays detailed information about a specific area
Permission: protects.info
Usage Example:
Code (Text):
/protectinfo Spawn
Shows coordinates, dimensions, creator, and all protection flags
/unprotect <name>
Description: Removes protection from an area
Permission: protects.remove
Warning: This action is permanent and cannot be undone
Usage Example:
Code (Text):
/unprotect OldBase
Completely removes the protection named "OldBase"
/protectreload
Description: Reloads plugin configuration and language files
Permission: protects.reload
Notes: Does not reload protection data (auto-saved)
4. PERMISSIONS SYSTEM
Admin Permissions:
Code (Text):
protects.admin
Description: Full access to all plugin features
Includes: All permissions below
Default: OP
Management Permissions:
Code (Text):
protects.create
Description: Create new protected areas
Commands: /areaprotect, /pset, /protect
Default: OP
protects.remove
Description: Remove protected areas
Commands: /unprotect
Default: OP
protects.list
Description: List all protected areas
Commands: /protectlist
Default: OP
protects.info
Description: View protection information
Commands: /protectinfo
Default: OP
protects.reload
Description: Reload plugin configuration
Commands: /protectreload
Default: OP
Bypass Permissions:
Code (Text):
protects.bypass
Description: Bypass all protection restrictions
Ignores: All protection checks
Default: OP (if enabled in config)
protects.bypass.item-drop
Description: Bypass item drop restrictions only
Default: None
protects.claim.bypass
Description: Bypass claim prevention system
Default: None
5. CONFIGURATION GUIDE
config.yml Structure:
Language Settings
Code (Text):
language:
default-language: en
# Default language if auto-detection fails
# Options: en, pt_br, es, it, ru, zh_cn
auto-detect: true
# Automatically detect player's client language
# Set to false to use default-language for all players
Protection Settings
Code (Text):
protection:
prevent-explosions: true
# Prevent TNT, creeper explosions in protected areas
prevent-fire-spread: true
# Prevent fire from spreading in protected areas
Message Settings
Code (Text):
messages:
actionbar-enabled: true
# Show denial messages above hotbar
# Recommended: true (non-intrusive)
chat-messages-enabled: false
# Also send denial messages in chat
# Recommended: false (can be spammy)
Effect Settings
Code (Text):
effects:
sound:
enabled: true
type: ENTITY_VILLAGER_NO
volume: 1.0
pitch: 1.0
particles:
enabled: true
type: SMOKE_NORMAL
count: 20
Claim Prevention
Code (Text):
claim-prevention:
enabled: true
# Enable/disable claim prevention system
prevent-item-claims: true
# Block item-based claims (golden shovel, etc)
prevent-command-claims: true
# Block claim commands from other plugins
custom-claim-items:
- "CUSTOM_ITEM_1"
- "CUSTOM_ITEM_2"
# Add custom items to block list
custom-claim-commands:
- "customclaim"
- "myclaim"
# Add custom commands to block list
Storage Settings
Code (Text):
storage:
auto-save-interval: 300
# Auto-save interval in seconds (300 = 5 minutes)
create-backups: true
# Create backup files before saving
max-backup-files: 10
# Maximum number of backup files to keep
Bypass Settings
Code (Text):
bypass:
ops-bypass-by-default: true
# Allow OPs to bypass protections without permission
Debug Settings
Code (Text):
debug:
enabled: false
# Enable detailed logging
log-protection-checks: false
# Log every protection check (very verbose)
6. PROTECTION FLAGS
Each protected area has 7 independent flags that can be configured in the JSON file:
Flag Configuration (JSON):
Code (Text):
{
"name": "AreaName",
"world": "world",
"minX": 0,
"minY": -64,
"minZ": 0,
"maxX": 100,
"maxY": 319,
"maxZ": 100,
"createdBy": "PlayerName",
"createdAt": 1234567890000,
"blockBreak": true,
"blockPlace": true,
"blockInteract": true,
"blockDamageEntity": true,
"blockBucketUse": true,
"blockClaimCreation": true,
"blockItemDrop": true
}
Flag Descriptions:
1. blockBreak
- Controls: Block breaking
- Default: true (blocked)
- When true: Players cannot break any blocks
- When false: Block breaking is allowed
2. blockPlace
- Controls: Block placement
- Default: true (blocked)
- When true: Players cannot place any blocks
- When false: Block placement is allowed
3. blockInteract
- Controls: Interaction with blocks
- Default: true (blocked)
- Affects: Chests, furnaces, doors, buttons, levers, etc.
- When true: Players cannot interact with protected blocks
- When false: Interaction is allowed
4. blockDamageEntity
- Controls: Entity damage (PvP and mobs)
- Default: true (blocked)
- When true: Players cannot damage entities
- When false: PvP and mob damage is allowed
5. blockBucketUse
- Controls: Water and lava bucket usage
- Default: true (blocked)
- When true: Players cannot use buckets
- When false: Bucket usage is allowed
6. blockClaimCreation
- Controls: Claim creation from other plugins
- Default: true (blocked)
- When true: Prevents conflicts with other land protection plugins
- When false: Other plugins can create claims
7. blockItemDrop
- Controls: Item dropping from inventory
- Default: true (blocked)
- When true: Players cannot drop items
- When false: Item dropping is allowed
Configuration Examples:
Example 1: Full Protection (Spawn)
Code (Text):
{
"name": "Spawn",
"blockBreak": true,
"blockPlace": true,
"blockInteract": true,
"blockDamageEntity": true,
"blockBucketUse": true,
"blockClaimCreation": true,
"blockItemDrop": true
}
Result: Completely protected, nothing can be done
Example 2: Build Zone
Code (Text):
{
"name": "BuildZone",
"blockBreak": false,
"blockPlace": false,
"blockInteract": false,
"blockDamageEntity": true,
"blockBucketUse": false,
"blockClaimCreation": true,
"blockItemDrop": false
}
Result: Free building, no PvP, no claims from other plugins
Example 3: PvP Arena
Code (Text):
{
"name": "PvPArena",
"blockBreak": true,
"blockPlace": true,
"blockInteract": false,
"blockDamageEntity": false,
"blockBucketUse": true,
"blockClaimCreation": true,
"blockItemDrop": true
}
Result: Only PvP and chest interaction allowed
7. MULTI-LANGUAGE SYSTEM
Supported Languages:
- English (en)
- Portuguese Brazil (pt_br)
- Spanish (es)
- Italian (it)
- Russian (ru)
- Chinese Simplified (zh_cn)
Language File Structure:
Code (Text):
# commands section
commands:
area-protected:
protection-removed:
# ... more messages
# success section
success:
point-set:
protection-created:
# ... more messages
# error section
errors:
already-protected:
invalid-size:
# ... more messages
# denial section
denial:
break-block:
place-block:
interact:
damage-entity:
use-bucket:
claim-creation:
claim-command:
item-drop:
generic:
# info section
info:
list-header:
area-details:
# ... more messages
Adding Custom Language:
1. Copy an existing language file (e.g., en.yml)
2. Rename it with your language code (e.g., de.yml for German)
3. Translate all messages
4. Set in config.yml: default-language: de
5. Reload with /protectreload
8. CLAIM PREVENTION SYSTEM
The claim prevention system blocks other land protection plugins from creating claims within protected areas.
Supported Plugins:
- GriefPrevention (golden shovel, /claim commands)
- WorldGuard (/region define commands)
- Residence (/res create commands)
- Towny (/town claim commands)
- Lands (/lands claim commands)
- PlotSquared (/plot claim commands)
- Factions (/f claim commands)
How It Works:
1. Item-Based Prevention:
- Detects common claim items (golden shovel, sticks, etc.)
- Cancels interaction when used in protected areas
- Shows denial message and effects
2. Command-Based Prevention:
- Intercepts claim commands before execution
- Matches against known claim command patterns
- Prevents command execution in protected areas
Configuration:
Code (Text):
claim-prevention:
enabled: true
prevent-item-claims: true
prevent-command-claims: true
custom-claim-items:
- "DIAMOND_SHOVEL"
- "BLAZE_ROD"
custom-claim-commands:
- "landclaim"
- "protectland"
Default Blocked Items:
- GOLDEN_SHOVEL
- STICK
- BLAZE_ROD
- WOODEN_SHOVEL
- IRON_SHOVEL
- DIAMOND_SHOVEL
Default Blocked Commands:
- claim, claimland
- region define, rg define
- res create, residence create
- town claim, t claim
- lands create, lands claim
- plot claim, plot auto
- f claim, faction claim
9. EFFECTS SYSTEM
Sound Effects:
Code (Text):
effects:
sound:
enabled: true
type: ENTITY_VILLAGER_NO
volume: 1.0
pitch: 1.0
Available Sound Types:
- ENTITY_VILLAGER_NO (default, recommended)
- BLOCK_NOTE_BLOCK_BASS
- ENTITY_ENDERMAN_TELEPORT
- UI_BUTTON_CLICK
Particle Effects:
Code (Text):
effects:
particles:
enabled: true
type: SMOKE_NORMAL
count: 20
Available Particle Types:
- SMOKE_NORMAL (default, recommended)
- CLOUD
- CRIT
- SPELL_WITCH
Message Display:
- Actionbar: Non-intrusive, above hotbar
- Chat: Optional, can be spammy
10. TROUBLESHOOTING
Common Issues:
Issue: Protection not working
Solution:
1. Check player has no bypass permission
2. Verify OPs bypass setting in config
3. Enable debug mode to see checks
4. Verify area exists with /protectlist
Issue: Commands not working
Solution:
1. Check permissions are set correctly
2. Verify command syntax
3. Check console for errors
4. Try /protectreload
Issue: Language not changing
Solution:
1. Verify language file exists
2. Check default-language in config
3. Test with /protectreload
4. Check auto-detect setting
Issue: Claims still being created
Solution:
1. Verify claim-prevention.enabled: true
2. Check both prevent-item-claims and prevent-command-claims
3. Add plugin's items/commands to custom lists
4. Enable debug mode to see detections
Issue: JSON file corrupted
Solution:
1. Plugin automatically creates backups
2. Check backups folder
3. Restore from backup manually
4. Plugin will attempt auto-recovery
Debug Mode:
Code (Text):
debug:
enabled: true
log-protection-checks: true
Enable for detailed logging of:
- Protection checks
- Permission verifications
- Claim prevention detections
- File operations
- Error details
Getting Support:
1. Enable debug mode
2. Reproduce the issue
3. Check console logs
4. Gather relevant information
5. Contact developer with details