# ProShield Documentation (v1.2.5)

---

## How to Claim Land

### Option 1 – The ProShield Compass (GUI)
- OPs auto-receive **Admin Compass** on join.
- Other players: `/proshield compass`
- Right-click to open the menu:
- Slot 11 → Claim current chunk
- Slot 13 → View claim info
- Slot 15 → Unclaim current chunk
- Slot 21 → Request Expansion (NEW in 1.2.5)
- Slot 31 → Help (commands visible per player’s role/permissions)
- Slot 33 → Admin menu (if permissions allow)

### Option 2 – Commands
- `/proshield claim` → Claim current chunk
- `/proshield unclaim` → Remove claim
- `/proshield info` → View claim details
- `/proshield trust <player> [role]` → Trust someone with optional role
- `/proshield untrust <player>` → Remove trust
- `/proshield trusted` → List trusted players

---

## ⌨️ Commands

- `/proshield` → Main help/menu
- `/proshield claim` → Claim chunk
- `/proshield unclaim` → Unclaim chunk
- `/proshield info` → Claim info
- `/proshield trust <player> [role]` → Trust a player with role
- `/proshield untrust <player>` → Remove trust
- `/proshield trusted` → List trusted players
- `/proshield compass` → Get ProShield compass
- `/proshield bypass <on|off|toggle>` → Admin bypass
- `/proshield reload` → Reload configs
- `/proshield purgeexpired <days> [dryrun]` → Purge expired claims
- `/proshield transfer <player>` → Transfer claim ownership
- `/proshield preview` → Show claim borders before confirming
- `/proshield debug <on|off>` → Toggle debug logs
- `/proshield expansionrequests` → View pending expansion requests (admins)

---

## Permissions

| Node | Description | Default |
|---------------------------------|----------------------------------------------------|---------|
| `proshield.use` | Use ProShield commands & GUI | ✅ true |
| `proshield.admin` | Admin tools (bypass, unclaim, teleport, approve/deny requests) | ❌ op |
| `proshield.compass` | Receive/use compass | ❌ op |
| `proshield.bypass` | Toggle bypass | ❌ op |
| `proshield.unlimited` | Ignore max-claims limit | ❌ op |
| `proshield.admin.tp` | Teleport to claims | ❌ op |
| `proshield.admin.reload` | Reload configs | ❌ op |
| `proshield.admin.expired.purge` | Purge expired claims | ❌ op |
| `proshield.admin.keepitems` | Toggle claim item-drop protection (1.2.2+) | ❌ op |
| `proshield.admin.transfer` | Transfer claim ownership (1.2.3+) | ❌ op |
| `proshield.admin.spawn` | Bypass spawn-guard restrictions (1.2.4+) | ❌ op |
| `proshield.admin.mobrepel` | Toggle mob repel borders in admin GUI (1.2.4+) | ❌ op |
| `proshield.admin.expansion` | Approve/deny expansion requests (1.2.5+) | ❌ op |

---

## Perfect For

- SMP & survival servers
- Community-based worlds
- Servers wanting performance + protection without bloat

---

# ❓ ProShield FAQ (v1.2.5)

This FAQ covers the most common questions, problems, and solutions for running ProShield.
If your issue isn’t listed here, please [open a GitHub issue]( https://github.com/snazzyatoms/ProShield/issues).

---

## ✅ General

**Q: What Minecraft versions are supported?**
A: ProShield supports **1.18 → 1.21** on **Spigot and Paper**.
Newer versions will be tested as they release.

---

**Q: Do I need a permissions plugin?**
A: **No.** ProShield works with Bukkit’s native permissions out-of-the-box.
If you run **LuckPerms, PermissionsEx, or GroupManager**, ProShield integrates seamlessly.

---

**Q: How do players claim land?**
A: Players can claim in **two ways**:

**Compass GUI**
- Use the ProShield Compass (right-click).
- Slot 11 → Claim current chunk
- Slot 13 → Claim info (owner + trusted players)
- Slot 15 → Unclaim
- Slot 21 → Request Expansion (NEW in 1.2.5)
- Slot 31 → Help (shows commands based on your permissions)
- Slot 33 → Admin menu (if you have admin perms)

**Commands**
- `/proshield claim` → Claim your current chunk
- `/proshield unclaim` → Unclaim
- `/proshield info` → View claim details

---

**Q: What is Claim Expansion? (NEW in 1.2.5)**
A: Players can request additional chunks to expand their claim.
- Requests go into a **pending queue**.
- Admins approve or deny requests via the **Expansion Requests GUI**.
- Decisions are logged in the **Expansion History menu**.

---

**Q: What is the World Controls GUI? (NEW in 1.2.5)**
A: Admins can toggle **global protections in-game** without editing YAML:
- Fire spread, TNT, creeper/wither explosions, PvP, mob griefing, etc.
- Accessible from the Admin menu.

---

**Q: What is Safezone Mob Control? (NEW in 1.2.5)**
A: Inside claims marked as **safezones**, hostile mobs are:
- Repelled at claim borders.
- Auto-despawned inside safezones.
- Prevented from targeting players inside claims.

---

**Q: I didn’t get the compass when joining. What’s wrong?**
A: Check these points:
- You are **OP** (ops automatically get the **Admin Compass**) or have `proshield.compass` / `proshield.admin`.
- In `config.yml`, `autogive.compass-on-join: true`.
- Use `/proshield compass` to get one manually if missing.

---

**Q: Can I reload configs without restarting?**
A: Yes! Run `/proshield reload`.
This refreshes **config.yml**, protections, claim expiry, and role settings without restarting.
New in **1.2.4**: A **Reload button** is available in the **Admin GUI**.

---

**Q: How does claim expiry work?**
A: Expiry **automatically removes claims** from inactive players:
- Enable with `expiry.enabled: true`.
- `expiry.days` sets the inactivity limit.
- Runs on **startup** and **daily**.
- Admins can force it with `/proshield purgeexpired`.

---

**Q: What are Claim Roles?**
A: Claim Roles let owners assign **different access levels** to trusted players:
- **Visitor** → Walk only, no interaction.
- **Member** → Basic interaction (doors, buttons, levers).
- **Container** → Can use chests, barrels, furnaces.
- **Builder** → Build and break blocks.
- **Co-Owner** → Full access, almost like the owner.

Configured in `config.yml` and manageable via **commands & GUI**.
More role customization coming in **v2.0**.

---

**Q: What is Claim Transfer?**
A: Owners can transfer their claim to another player with:
- `/proshield transfer <player>`

---

**Q: What is Claim Preview?**
A: Use `/proshield preview` to see a **particle outline** of your claim before confirming.

---

**Q: What is Spawn Guard? (1.2.4+)**
A: Spawn Guard prevents claims too close to the **world spawn**:
- Configurable radius via `spawn.radius`.
- Default = 32 blocks.
- Admins with `proshield.admin.spawn` can override it.

---

**Q: How does Mob Repel work? (1.2.4+)**
A: Hostile mobs are **pushed back** at claim borders:
- Configurable in `protection.mobs.border-repel`.
- Radius, push force, and tick interval can be changed.
- Prevents mobs from entering claims at all.

---

**Q: Where are claims stored? Can I back them up?**
A: Claims and trust data are stored in:
`/plugins/ProShield/config.yml`

✅ Always back up this file (or the full ProShield folder) before updates.

---

**Q: Do I need to delete my config for 1.2.5?**
A: ⚠️ Yes, if upgrading from **1.2.3 or older**, or if configs fail to load.
1. Stop the server.
2. Delete `/plugins/ProShield/`.
3. Restart to regenerate fresh configs.
4. Reapply your custom edits.

---

**Q: Where do I report bugs or request features?**
A: Use the [GitHub Issues page]( https://github.com/snazzyatoms/ProShield/issues) or the **Spigot discussion thread**.

---

## ️ Troubleshooting

**Problem:** GUI buttons don’t work
✅ Fix: Update to **1.2.5**, which fixes Back/Exit and wiring for all GUIs.

---

**Problem:** Players can’t build/interact in claims (but should)
✅ Fix:
- Confirm they are trusted with `/proshield trust <player>`.
- Check their **role**.
- Review `protection.interactions` in `config.yml`.

---

**Problem:** Fire, TNT, creepers, or mobs still grief claims
✅ Fix:
- Review `protection.*` flags in `config.yml`.
- Check **World Controls GUI** (1.2.5) hasn’t disabled the protections.
- Run `/proshield reload` after edits.

---

**Problem:** Expansion Requests not working
✅ Fix:
- Ensure `proshield.admin.expansion` is granted to staff.
- Check that `expansions.enabled: true` is set in config.
- Review logs for approval/denial entries.

---

## Notes

- Always back up `/plugins/ProShield/` before updating.
- For **1.2.5**, regenerate configs if upgrading from 1.2.3 or older.
- Test updates on a dev/test server before going live.
- Join the **Spigot discussion thread** for help & tips.