{"id":26412857,"url":"https://github.com/4k1d3v/nbtkeycard","last_synced_at":"2025-08-12T06:13:35.075Z","repository":{"id":280761802,"uuid":"942778001","full_name":"4K1D3V/NBTKeyCard","owner":"4K1D3V","description":"NBTKeyCard offers a seamless and immersive way to manage access to exclusive mining areas. ","archived":false,"fork":false,"pushed_at":"2025-03-05T06:11:08.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-17T22:11:24.497Z","etag":null,"topics":["minecraft","minecraft-plugin","nms","spigot-api","spigot-plugin"],"latest_commit_sha":null,"homepage":"https://ks.akii.pro","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/4K1D3V.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-04T16:54:53.000Z","updated_at":"2025-03-05T06:35:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"88a114fa-50d5-4c44-ad32-041a5a8602c4","html_url":"https://github.com/4K1D3V/NBTKeyCard","commit_stats":null,"previous_names":["4k1d3v/nbtkeycard"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/4K1D3V/NBTKeyCard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4K1D3V%2FNBTKeyCard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4K1D3V%2FNBTKeyCard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4K1D3V%2FNBTKeyCard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4K1D3V%2FNBTKeyCard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/4K1D3V","download_url":"https://codeload.github.com/4K1D3V/NBTKeyCard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4K1D3V%2FNBTKeyCard/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270011191,"owners_count":24511902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["minecraft","minecraft-plugin","nms","spigot-api","spigot-plugin"],"created_at":"2025-03-17T22:09:39.799Z","updated_at":"2025-08-12T06:13:35.062Z","avatar_url":"https://github.com/4K1D3V.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NBTKeyCard\n\n![Minecraft Version](https://img.shields.io/badge/Minecraft-1.21.4-brightgreen.svg)\n![Spigot API](https://img.shields.io/badge/Spigot_API-1.21-blue.svg)\n![License](https://img.shields.io/badge/License-MIT-yellow.svg)\n![GitHub Issues](https://img.shields.io/github/issues/4K1D3V/NBTKeyCard)\n\nWelcome to **NBTKeyCard**, a cutting-edge Spigot plugin designed to secure your Minecraft mines with NBT-tagged key cards! Crafted with passion by Kite, this plugin offers a seamless and immersive way to manage access to exclusive mining areas. Whether you're running a bustling server or a private world, NBTKeyCard brings advanced features, top-notch performance, and rock-solid stability to your gameplay.\n\n🌐 **Website**: [ks.akii.pro](https://ks.akii.pro)  \n📬 **Issues**: [Report a Bug](https://github.com/4K1D3V/NBTKeyCard/issues)\n\n---\n\n## Features\n\n- **Secure Mine Access**: Restrict entry to mines using custom NBT-tagged key cards.\n- **Multi-World Support**: Define mines across different worlds (e.g., `world`, `world_nether`).\n- **Economy Integration**: Purchase key cards via an in-game shop with Vault support.\n- **Temporary Key Cards**: Create key cards with expiration times or usage limits.\n- **Dynamic Mine Management**: Add new mines in-game with intuitive commands.\n- **Visual Feedback**: See mine boundaries with particle effects and receive denial notifications with sounds and particles.\n- **Performance Optimized**: Built-in caching and event optimizations for lag-free operation.\n- **Customizable**: Configure messages and mine settings to match your server’s style.\n\n---\n\n## Installation\n\n1. **Prerequisites**:\n   - **Minecraft Server**: Spigot 1.21.4\n   - **Dependencies**: [Vault](https://www.spigotmc.org/resources/vault.41918/) and an economy plugin (e.g., [EssentialsX Economy](https://www.spigotmc.org/resources/essentialsx.9089/))\n\n2. **Download**:\n   - Grab the latest `NBTKeyCard.jar` from the [Releases](https://github.com/4K1D3V/NBTKeyCard/releases) page.\n\n3. **Install**:\n   - Drop `NBTKeyCard.jar` into your server’s `plugins/` folder.\n   - Ensure Vault and your economy plugin are also in the `plugins/` folder.\n\n4. **Start Server**:\n   - Launch your server with `java -jar spigot-1.21.4.jar`.\n   - NBTKeyCard will generate a default `config.yml` in `plugins/NBTKeyCard/`.\n\n5. **Configure**:\n   - Edit `config.yml` to define your mines (see [Configuration](#configuration) below).\n\n---\n\n## Configuration\n\nThe `config.yml` file is your key to customizing NBTKeyCard. Below is an example configuration:\n\n```yaml\n# ╔════════════════════════════════════════════════════╗\n# ║          NBTKeyCard Plugin Configuration           ║\n# ╚════════════════════════════════════════════════════╝\n#\n# Welcome to the heart of NBTKeyCard! Configure your mines below with finesse.\n# Should you stumble upon any glitches or quirks while exploring this plugin,\n# we’d love to hear from you! Please raise an issue on our GitHub:\n# ➜ https://github.com/4K1D3V/NBTKeyCard/issues\n#\n# Crafted with passion by Kite\n# Visit us at: https://ks.akii.pro\n# Enjoy a seamless mining adventure!\n\nmines:\n  mine1:\n    world: world\n    min:\n      x: 0\n      y: 0\n      z: 0\n    max:\n      x: 100\n      y: 100\n      z: 100\n    access: open\n  mine2:\n    world: world\n    min:\n      x: 101\n      y: 0\n      z: 0\n    max:\n      x: 200\n      y: 100\n      z: 100\n    access: restricted\n    required_nbt:\n      key: \"access\"\n      value: \"mine2\"\n    code: \"mine2code\"\n    shop_price: 100.0\n  mine3:\n    world: world_nether\n    min:\n      x: 201\n      y: 0\n      z: 0\n    max:\n      x: 300\n      y: 100\n      z: 100\n    access: restricted\n    required_nbt:\n      key: \"access\"\n      value: \"mine3\"\n    code: \"mine3code\"\n    shop_price: 150.0\n\nmessages:\n  denial: \"\u0026cAccess Denied! You need a key card for this mine!\"\n```\n\n### Key Fields\n- **`mines.\u003cname\u003e`**: Define a mine with a unique name.\n  - `world`: The world where the mine exists (e.g., `world`, `world_nether`).\n  - `min/max`: X, Y, Z coordinates for the mine’s boundaries (inclusive).\n  - `access`: `open` (public) or `restricted` (key card required).\n  - `required_nbt`: NBT key-value pair for restricted mines.\n  - `code`: Optional chat code to redeem a key card.\n  - `shop_price`: Cost in the in-game shop (default: 100.0).\n- **`messages.denial`**: Customizable message shown when access is denied.\n\n---\n\n## Commands\n\n| Command                          | Description                              | Permission           |\n|----------------------------------|------------------------------------------|----------------------|\n| `/nbtkeycard give \u003cplayer\u003e \u003cmine\u003e` | Gives a key card to a player            | `nbtkeycard.give`   |\n| `/nbtkeycard gui`                | Opens the key card selection GUI         | `nbtkeycard.gui`    |\n| `/nbtkeycard shop`               | Opens the key card shop                  | `nbtkeycard.shop`   |\n| `/nbtkeycard show \u003cmine\u003e`        | Displays a mine’s boundaries for 10s     | `nbtkeycard.admin`  |\n| `/nbtkeycard mine create \u003cname\u003e \u003cworld\u003e \u003cminX\u003e \u003cminY\u003e \u003cminZ\u003e \u003cmaxX\u003e \u003cmaxY\u003e \u003cmaxZ\u003e \u003caccess\u003e` | Creates a new mine | `nbtkeycard.admin`  |\n\n### Chat Codes\n- Players can type a mine’s `code` (e.g., `mine2code`) in chat to redeem a key card (requires `nbtkeycard.receive`).\n\n---\n\n## Permissions\n\n| Permission             | Description                              | Default  |\n|-----------------------|------------------------------------------|----------|\n| `nbtkeycard.give`     | Allows giving key cards to players       | op       |\n| `nbtkeycard.gui`      | Allows accessing the key card GUI        | true     |\n| `nbtkeycard.shop`     | Allows accessing the key card shop       | true     |\n| `nbtkeycard.receive`  | Allows redeeming key cards via chat      | true     |\n| `nbtkeycard.admin`    | Allows managing mines and visualization  | op       |\n\n---\n\n## Usage\n\n1. **Configure Mines**: Edit `config.yml` to set up your mines.\n2. **Distribute Key Cards**:\n   - Use `/nbtkeycard give \u003cplayer\u003e \u003cmine\u003e` as an admin.\n   - Players can use `/nbtkeycard gui` to pick a free key card or `/nbtkeycard shop` to buy one.\n   - Players can type a mine’s code in chat (e.g., `mine2code`) to redeem a key card.\n3. **Manage Mines**:\n   - Create new mines with `/nbtkeycard mine create`.\n   - Visualize boundaries with `/nbtkeycard show \u003cmine\u003e`.\n\n---\n\n## Performance \u0026 Stability\n\n- **Caching**: Player locations are cached to minimize lookups in `PlayerMoveEvent`.\n- **Optimization**: Early exits in event handlers reduce CPU load.\n- **Stability**: Robust error handling for invalid configs and missing dependencies.\n- **Logging**: Access attempts and redemptions are logged for monitoring.\n\n---\n\n## Contributing\n\nWe welcome contributions! Here’s how to get involved:\n\n1. **Fork the Repository**: Clone it to your local machine.\n2. **Make Changes**: Add features, fix bugs, or improve documentation.\n3. **Submit a Pull Request**: Describe your changes clearly in the PR.\n\nPlease follow the [Code of Conduct](CODE_OF_CONDUCT.md) and report issues at [GitHub Issues](https://github.com/4K1D3V/NBTKeyCard/issues).\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n\n---\n\n## Credits\n\n- **Author**: Kite  \n- **GitHub**: [4K1D3V](https://github.com/4K1D3V)  \n- **Support**: [ks.akii.pro](https://ks.akii.pro)\n\nHappy mining with NBTKeyCard! ⛏️","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4k1d3v%2Fnbtkeycard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F4k1d3v%2Fnbtkeycard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4k1d3v%2Fnbtkeycard/lists"}