AwesomeKeycards

Author: NeonDev
Platform: PaperMC 1.21.8
Language: Kotlin (2.3.0-Beta2) using Gradle + Shadow + run-paper.
Version: 1.4.1

AwesomeKeycards lets you turn any item into a digital keycard, lock interactive blocks, and share access with trusted players. It is designed for modern survival servers that want lightweight door/loot protection without relying on heavy land-claim systems.

---

Feature Highlights

• 🔐 Custom-labeled keycards – /keycard create [global|team <team>] <label> converts the held item with a unique ID, plus optional color/style/auto-close/double/notify/cooldown presets.
• 🚪 Block locking – lock doors, trapdoors, fence gates, buttons, chests, barrels, furnaces, shulkers, etc. Only matching keycards (or shared users) can interact.
• 👥 Shareable access – card owners can grant or revoke access via /keycard access add/remove/list, perfect for roommates or faction mates.
• 🧩 Flexible key types – create personal (default), global, or team <name> keys to match open-access lobbies or scoreboard-managed squads.
• 🎛️ Command presets – set accent color, effect style, auto-close timer, double-door sync, owner alerts, and cooldown defaults right on the create command.
• 📦 Admin vault – /keycard vault lists every keycard with quick cloning and revoke options that also clean up locks.
• 👁️ Lock inspection – shift-right-click a locked block with any keycard to see its linked key, owner, and a copyable ID (admins only).
• 🚪 Door customization – /keycard door (owner, no admin perm) controls auto-close timers, double-door syncing, owner alerts, cooldowns, style presets, nicknames, and a copy/paste clipboard for fast setup.
• 🌈 Style presets – pick classic, stealth, or spark effects per lock to change particle colors and sounds.
• 🔔 Owner alerts – optional pings when someone uses your lock, throttled to avoid spam.
• ⏱️ Use cooldowns – rate-limit rapid spam on doors or buttons with a per-lock delay.
• 🧾 Door status HUD – instant summary of the targeted lock’s nickname and toggles via /keycard door status.
• 🗂️ Config clipboard – copy/paste lock settings between doors to set up bases quickly.
• 🎨 Visual feedback – particle trails + jingles on lock/unlock and a subtle denied tone when access is blocked.
• 💾 Persistent storage – locks saved to locks.yml, cards + ACL to keycards.yml, ensuring safety across restarts.
• ⚙️ Fine-grained permissions – admin-only workflow for creating/locking, but anyone with the access permission can manage sharing for their own cards.
• 🧠 Team watchdog – optional allow/deny lists plus automatic pruning of team keys tied to removed teams keep ACLs clean.
• 📜 Audit log – /keycard audits tail recent lock/unlock attempts with player, key short ID, and location.

---

Commands

Command	Permission	Description
/keycard create [global/team <team>] <label> [color=<name>] [style=<preset>] [autoclose=<seconds/off>] [double=<on/off>] [notify=<on/off>] [cooldown=<seconds/off>]	awesomekeycards.admin	Converts the held item into a labeled keycard with optional defaults for future locks.
/keycard lock	awesomekeycards.admin	Links the held keycard to the block you are looking at (6 block reach).
/keycard unlock	awesomekeycards.admin	Unlocks a block if you hold the linked keycard.
/keycard access add <player>	awesomekeycards.access	Grants another player the ability to use the current keycard.
/keycard access remove <player>	awesomekeycards.access	Revokes access for a player.
/keycard access list	awesomekeycards.access	Lists everyone who can use the current keycard.
/keycard view	awesomekeycards.access	Displays owner, scope, and sharing details for the held keycard.
/keycard door <status/autoclose/double/notify/cooldown/style/nickname/copy/paste>	awesomekeycards.access (owner or admin)	Customize the targeted locked block: timers, double-door syncing, alerts, styles, nicknames, and clipboard actions.
/keycard vault [page]	awesomekeycards.admin	Browse all stored keycards, clone them, or revoke + clean locks.
/keycard audits [player] [count]	awesomekeycards.admin	Show the most recent audit lines; defaults to 10 entries.

Hold the keycard item in your main hand before running any command.
By default awesomekeycards.admin is OP-only, while awesomekeycards.access is granted to all players so they can manage their own cards.

Example: /keycard create global Lobby color=gold style=sparks autoclose=5 double=off notify=on cooldown=3

---

Supported Blocks

• All doors, trapdoors, fence gates, and buttons (via Bukkit tags).
• Utility blocks: levers, barrels, chests (normal & trapped), furnaces, smokers, blast furnaces, droppers, dispensers, hoppers, shulker boxes (all colors).
• When locking double-doors, aim at the lower half; the plugin normalizes coordinates so both halves stay linked and, if enabled, will sync open/close on both sides.

---

Keycard Types

• Personal – default behavior. Owner plus manually shared UUIDs can operate linked blocks.
• Global – /keycard create global <label> lets every player interact with blocks locked to that key (great for spawn doors that still log activity).
• Team – /keycard create team <teamName> <label> ties the lock to a vanilla scoreboard team (/team add Guards). Any member of that team can open the block without needing the physical item.

Use /keycard view while holding a card to confirm its scope, owner, and share list before distributing copies.

---

Door Customization (no admin needed)

Owners (or admins) looking at a locked block can run /keycard door ...:

• status – show nickname plus all toggles for the targeted lock.
• autoclose <seconds|off> – close doors/fence gates/trapdoors automatically after a delay.
• double <on|off> – open/close both halves of a double door together.
• notify <on|off> – ping the owner when others use the lock (throttled).
• cooldown <seconds|off> – add a short delay to prevent spammy toggling.
• style <classic|stealth|sparks> – change particles/sounds per lock.
• nickname <name|off> – friendly label shown in status/alerts.
• copy / paste – clone all these settings between locks to set up bases quickly.

Defaults you set on /keycard create (color, style, auto-close, double-door, alerts, cooldown) are saved on the keycard and applied to locks the next time you link that card to a block.
All customization uses the awesomekeycards.access permission (default true) and only requires owning the key, not server admin.

---

Configuration

• teamAccess.allow / teamAccess.deny (lists) gate which scoreboard teams can be used for team keycards; leave allow empty to allow all by default.
• teamAccess.watchdogIntervalTicks controls how often stale/blocked team keycards are pruned.
• Audit logs are written to plugins/AwesomeKeycards/audit.log and can be tailed in-game with /keycard audits.