{"id":16329249,"url":"https://github.com/josantonius/minecraft-command","last_synced_at":"2025-05-15T08:33:54.154Z","repository":{"id":164406089,"uuid":"639852034","full_name":"josantonius/minecraft-command","owner":"josantonius","description":"Create custom commands with specific actions and cooldowns","archived":false,"fork":false,"pushed_at":"2023-05-15T22:49:31.000Z","size":70007,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-17T10:13:13.944Z","etag":null,"topics":["kotlin","minecraft","minecraft-plugin","plugin","purpur"],"latest_commit_sha":null,"homepage":"https://josantonius.dev","language":"Kotlin","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/josantonius.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","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},"funding":{"github":["Josantonius"]}},"created_at":"2023-05-12T11:23:17.000Z","updated_at":"2024-06-18T15:17:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"468da3f2-6b84-4380-9f9c-96ee3313bece","html_url":"https://github.com/josantonius/minecraft-command","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-command","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-command/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-command/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-command/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/josantonius","download_url":"https://codeload.github.com/josantonius/minecraft-command/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254304747,"owners_count":22048457,"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","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":["kotlin","minecraft","minecraft-plugin","plugin","purpur"],"created_at":"2024-10-10T23:14:55.449Z","updated_at":"2025-05-15T08:33:54.125Z","avatar_url":"https://github.com/josantonius.png","language":"Kotlin","readme":"# Minecraft Command Plugin\n\n[![License](https://img.shields.io/github/license/josantonius/minecraft-command)](LICENSE)\n\nThis plugin allows server administrators to create custom commands with specific actions and cooldowns.\n\nCustom commands can be cancelled by other plugins in the `PlayerCommandPreprocessEvent` event.\n\n## [Watch demo on YouTube](https://www.youtube.com/watch?v=whHH9OC_1qI)\n\n## Requirements\n\n- Java 17 or higher.\n- Purpur server 1.19.3 or Bukkit/Spigot/Paper server compatible with the Purpur API version used.\n\n## Installation\n\n1. Download the JAR file: [command-1.0.0-purpur-1.19.3.jar](/build/libs/command-1.0.0-purpur-1.19.3.jar).\n\n1. Place the JAR file in the plugins folder of your Minecraft server.\n\n1. Restart the server to load the plugin.\n\n## Building\n\nTo build the plugin yourself, follow these steps:\n\n1. Make sure you have `Java 17` or higher and `Gradle` installed on your system.\n\n1. Clone the plugin repository on your local machine:\n\n    ```bash\n    git clone https://github.com/josantonius/minecraft-command.git\n    ```\n\n1. Navigate to the directory of the cloned repository:\n\n    ```bash\n    cd minecraft-command\n    ```\n\n1. Use Gradle to compile the plugin:\n\n    ```bash\n    gradle build\n    ```\n\n## Commands\n\n- `/command reload` - Reload the plugin\n\nRequires the `command.admin` permission to be used.\n\n## Configuration\n\nThe `config.yml` file located in the `plugins/Command` folder contains the plugin configuration.\nTo define custom commands and their actions, you can modify the commands section in the file.\n\n### Add new custom command to the server\n\nTo add a new custom command to the server, you must add a new entry in the `commands` section of the\n`plugins/Command/config.yml` file.\n\n```yaml\ncommands:\n  warpshop:\n    cooldown: 5\n    actions:\n      - 'command_player: shop %player%'\n      - 'message: Welcome to the shop, %player%!'\n```\n\n## Action Types\n\nThe config.yml file located in the `plugins/Command` folder contains the plugin configuration.\nTo define custom commands and their actions, you can modify the commands section in the file.\n\n1. `Command Player`: Executes a command as the player. Use the prefix `command_player:` followed by\nthe command to execute. You can use `%player%` as a placeholder for the player's name.\n\n    - `command_player: tp %player% 100 64 200`\n\n1. `Command Console`: Executes a command as the console. Use the prefix `command_console`: followed\nby the command to execute. You can use `%player%` as a placeholder for the player's name.\n\n    - `command_console: op %player%`\n\n1. `Message`: Sends a message to the player. Use the prefix message: followed by the text to send.\nYou can use `%player%` as a placeholder for the player's name.\n\n    - `message: Welcome to the shop, %player%!`\n\n      You can use the `messages.yml` file located in the `plugins/Command` folder to define custom\n      messages for your commands. This allows you to easily manage and change command messages in a\n      centralized location.\n\n      To add a new message to the messages.yml file, simply create a new entry using a key and a\n      value. The key will be used to reference the message in the custom command configuration, and\n      the value will be the message content.\n\n      Here's an example of how to add a login message to the `messages.yml` file:\n\n      ```yaml\n      user:\n        login: \"Login successful!\"\n      ```\n\n      To use a message from the `messages.yml` file in a custom command, reference the message key\n      in the message: action using the format key.subkey.\n\n      For example, to use the login message in a custom command, you would do the following:\n\n      ```yaml\n      commands:\n        login:\n          actions:\n            - 'message: user.login'\n      ```\n\n      When the login_command is executed, the player will receive the message \"Login successful!\" as\n      defined in the `messages.yml` file. This allows you to easily update messages without having\n      to modify the custom command configurations directly.\n\n## Cooldowns\n\nCooldowns allow you to limit the frequency at which players can execute custom commands. To add a\ncooldown to a custom command, you need to add a cooldown field in the command configuration in the\n`config.yml` file located in the `plugins/Command` folder.\n\n### Setting up a cooldown for a custom command\n\nTo set up a cooldown for a custom command, simply add the cooldown property to the command in the\n`config.yml` file and specify the time in seconds.\n\nHere's an example of how to set up a 60-second cooldown for the warpshop command:\n\n```yaml\ncommands:\n  warpshop:\n    cooldown: 60\n    actions:\n      - 'command_player: tp %player% 100 64 200'\n      - 'message: Welcome to the shop, %player%!'\n```\n\n### Cancellation of commands on cooldown\n\nIf a player moves while waiting for a command's cooldown to expire, the command will automatically\nbe cancelled, and the player will be notified that the command has been cancelled due to their movement.\n\n## Command Arguments\n\nYou can also include command arguments in the actions. To do this, use placeholders in the format\n`{1}`, `{2}`, `{3}`, and so on. These placeholders will be replaced by the corresponding arguments\npassed by the player when executing the custom command.\n\nExample of a custom command with arguments:\n\n```yaml\ncommands:\n  setwarp:\n    actions:\n      - 'command_console: setworldspawn %player% {1} {2} {3}'\n      - 'message: Warp set at coordinates {1}, {2}, {3}'\n```\n\nWhen a player types `/setwarp 100 64 200`, the command action will be executed as `setworldspawn\nplayername 100 64 200`, and the message will be \"Warp set at coordinates 100, 64, 200\".\n\n## Executing Command Exactly as Player Input\n\nTo execute the command exactly as the player input, you can use the `*` symbol. This takes the command\nand arguments that the player entered, and executes them as they were entered.\n\n```yaml\ncommands:\n  'ps home':\n    actions:\n      - 'command_player: *'\n    cooldown: 5\n```\n\nIn this example, when a player enters the command ps home `ps-158-1555`, it will be executed exactly\nas entered, with ps-158 being treated as an argument to the ps home command. The `*` acts as a\nplaceholder for any arguments passed by the player.\n\n## Compatibility with Other Plugins\n\nThis plugin uses the PlayerCommandPreprocessEvent to handle custom commands. If you want to cancel\na custom command from another plugin, you can do so by calling `event.isCancelled` on the `PlayerCommandPreprocessEvent`.\n\n## TODO\n\n- [ ] Add new feature\n- [ ] Create tests\n- [ ] Improve documentation\n\n## Changelog\n\nDetailed changes for each release are documented in the\n[release notes](https://github.com/josantonius/minecraft-command/releases).\n\n## Contribution\n\nPlease make sure to read the [Contributing Guide](.github/CONTRIBUTING.md), before making a pull\nrequest, start a discussion or report a issue.\n\nThanks to all [contributors](https://github.com/josantonius/minecraft-command/graphs/contributors)! :heart:\n\n## Sponsor\n\nIf this project helps you to reduce your development time,\n[you can sponsor me](https://github.com/josantonius#sponsor) to support my open source work :blush:\n\n## License\n\nThis repository is licensed under the [MIT License](LICENSE).\n\nCopyright © 2023-present, [Josantonius](https://github.com/josantonius#contact)\n","funding_links":["https://github.com/sponsors/Josantonius"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosantonius%2Fminecraft-command","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosantonius%2Fminecraft-command","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosantonius%2Fminecraft-command/lists"}