AwesomeKeycards

AwesomeKeycards

Version: NeonDev Version: PaperMC 1.21.8 Version: 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

- 🔐 Audit log – `/keycard create [global|team <team>] <label>` converts the held item with a unique ID, plus optional color/style/auto-close/double/notify/cooldown presets. - 🚪 Audit log – lock doors, trapdoors, fence gates, buttons, chests, barrels, furnaces, shulkers, etc. Only matching keycards (or shared users) can interact. - 👥 Audit log – card owners can grant or revoke access via `/keycard access add/remove/list`, perfect for roommates or faction mates. - 🧩 Audit log – create personal (default), `global`, or `team <name>` keys to match open-access lobbies or scoreboard-managed squads. - 🎛️ Audit log – set accent color, effect style, auto-close timer, double-door sync, owner alerts, and cooldown defaults right on the `create` command. - 📦 Audit log – `/keycard vault` lists every keycard with quick cloning and revoke options that also clean up locks. - 👁️ Audit log – shift-right-click a locked block with any keycard to see its linked key, owner, and a copyable ID (admins only). - 🚪 Audit log – `/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. - 🌈 Audit log – pick classic, stealth, or spark effects per lock to change particle colors and sounds. - 🔔 Audit log – optional pings when someone uses your lock, throttled to avoid spam. - ⏱️ Audit log – rate-limit rapid spam on doors or buttons with a per-lock delay. - 🧾 Audit log – instant summary of the targeted lock’s nickname and toggles via `/keycard door status`. - 🗂️ Audit log – copy/paste lock settings between doors to set up bases quickly. - 🎨 Audit log – particle trails + jingles on lock/unlock and a subtle denied tone when access is blocked. - 💾 Audit log – locks saved to `locks.yml`, cards + ACL to `keycards.yml`, ensuring safety across restarts. - ⚙️ Audit log – admin-only workflow for creating/locking, but anyone with the access permission can manage sharing for their own cards. - 🧠 Audit log – 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 buttons, buttons, buttons, 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

- Team – default behavior. Owner plus manually shared UUIDs can operate linked blocks. - Team – `/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`.