{"id":16329256,"url":"https://github.com/josantonius/minecraft-messaging","last_synced_at":"2026-04-29T00:31:15.317Z","repository":{"id":153240412,"uuid":"628588861","full_name":"josantonius/minecraft-messaging","owner":"josantonius","description":"Easily send messages to players on a Minecraft server running PaperMC, Bukkit, or Spigot","archived":false,"fork":false,"pushed_at":"2023-05-01T18:34:53.000Z","size":69,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-15T08:45:19.392Z","etag":null,"topics":["bukkit","kotlin","library","minecraft","paper","papermc"],"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-04-16T12:30:37.000Z","updated_at":"2024-12-13T09:02:37.000Z","dependencies_parsed_at":"2024-11-06T20:41:13.260Z","dependency_job_id":null,"html_url":"https://github.com/josantonius/minecraft-messaging","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/josantonius/minecraft-messaging","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-messaging","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-messaging/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-messaging/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-messaging/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/josantonius","download_url":"https://codeload.github.com/josantonius/minecraft-messaging/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-messaging/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32405901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"ssl_error","status_checked_at":"2026-04-28T19:37:55.688Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["bukkit","kotlin","library","minecraft","paper","papermc"],"created_at":"2024-10-10T23:14:56.473Z","updated_at":"2026-04-29T00:31:15.302Z","avatar_url":"https://github.com/josantonius.png","language":"Kotlin","funding_links":["https://github.com/sponsors/Josantonius"],"categories":[],"sub_categories":[],"readme":"# Minecraft Messaging Library\n\n[![Release](https://jitpack.io/v/dev.josantonius/minecraft-messaging.svg)](https://jitpack.io/#dev.josantonius/minecraft-messaging)\n[![License](https://img.shields.io/github/license/josantonius/minecraft-messaging)](LICENSE)\n\nEasily send messages to players on a Minecraft server running PurPur, Paper, Bukkit, or Spigot.\n\nIt supports sending messages and titles to individual players, all players and console.\n\nThe messages are stored in a YAML file and can be easily formatted with placeholders.\n\n---\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Available Classes](#available-classes)\n  - [Message Class](#message-class)\n  - [Title Class](#title-class)\n- [Usage](#usage)\n- [Using Clickable Tags](#using-clickable-tags)\n- [Using Color Codes](#using-color-codes)\n- [TODO](#todo)\n- [Changelog](#changelog)\n- [Contribution](#contribution)\n- [Sponsor](#sponsor)\n- [License](#license)\n\n---\n\n## Requirements\n\n- Java 17\n- Purpur server 1.19.3 or Paper/Bukkit/Spigot server compatible with the Purpur API version used.\n\n## Installation\n\nFirst, add the repository containing the minecraft-messaging library to your project's build.gradle file:\n\n```groovy\nrepositories {\n    maven { url 'https://jitpack.io' }\n}\n```\n\nThen, add the minecraft-messaging library as a dependency to your project's build.gradle file:\n\n```groovy\ndependencies {\n    implementation 'dev.josantonius:minecraft-messaging:v1.0.9'\n}\n```\n\n## Available Classes\n\n### Message Class\n\n`dev.josantonius.minecraft.messaging.Message`\n\nSet the prefix for console messages:\n\n```kotlin\n/**\n * @param prefix The prefix to use for console messages.\n */\nfun setConsolePrefix(prefix: String)\n```\n\nSet the prefix for chat messages:\n\n```kotlin\n/**\n * @param prefix The prefix to use for chat messages.\n */\nfun setChatPrefix(prefix: String)\n```\n\nSends a message with the given key and optional parameters to all online players on the server:\n\n```kotlin\n/**\n * @param key    The key associated with the message in the message file.\n * @param params Optional parameters to replace placeholders in the message.\n */\nfun sendToPlayers(key: String, vararg params: String)\n```\n\nSends a message with the given key and optional parameters to a specific player:\n\n```kotlin\n/**\n * @param player The Player object to send the message to.\n * @param key    The key associated with the message in the message file.\n * @param params Optional parameters to replace placeholders in the message.\n */\nfun sendToPlayer(player: Player, key: String, vararg params: String)\n```\n\nSends a message with the given key and optional parameters to all online players on the server:\n\n```kotlin\n/**\n * @param key    The key associated with the message in the message file.\n * @param params Optional parameters to replace placeholders in the message.\n */\nfun sendToPlayers(key: String, vararg params: String)\n```\n\nSends a system message to the console:\n\n```kotlin\n/**\n * @param key    The key associated with the message in the message file.\n * @param params Optional parameters to replace placeholders in the message.\n */\nfun sendToConsole(key: String, vararg params: String)\n```\n\nSends a message with the given key and optional parameters to online players and the console:\n\n```kotlin\n/**\n * @param key The key associated with the message in the message file.\n * @param params Optional parameters to replace placeholders in the message.\n */\nfun broadcast(key: String, vararg params: String)\n```\n\nRetrieves associated with the given key, replaces placeholders and returns a string:\n\n```kotlin\n/**\n * @param key    The key associated with the message in the message file.\n * @param params Optional parameters to replace placeholders in the message.\n */\nfun getString(key: String, vararg params: String): String\n```\n\nRetrieves associated with the given key, replaces placeholders and returns a Component:\n\n```kotlin\n/**\n * @param key    The key associated with the message in the message file.\n * @param params Optional parameters to replace placeholders in the message.\n */\nfun getComponent(key: String, vararg params: String): Component\n```\n\n### Title Class\n\n`dev.josantonius.minecraft.messaging.Title`\n\nCreates a new Title object with the given message file and optional Title.Times:\n\n```kotlin\n/**\n * Represents a title message with optional custom times.\n *\n * @property file  The file from which the message is read.\n * @property times The Title.Times object containing fadeIn, stay, and fadeOut durations.\n *\n * @throws IllegalArgumentException if there is an error loading the file.\n */\nclass Title(private val file: File, private val times: AdventureTitle.Times? = null)\n```\n\nShows a title and subtitle with the given keys and optional parameters to all online players:\n\n```kotlin\n/**\n * @param titleKey    The key associated with the title message in the message file.\n * @param subtitleKey The key associated with the subtitle message in the message file.\n * @param params      Optional parameters to replace placeholders in the messages.\n */\nfun showToPlayers(titleKey: String, subtitleKey: String, vararg params: String)\n```\n\nShows a title and subtitle with the given keys and optional parameters to a specific player:\n\n```kotlin\n/**\n * @param player      The Player object to show the title to.\n * @param titleKey    The key associated with the title message in the message file.\n * @param subtitleKey The key associated with the subtitle message in the message file.\n * @param params      Optional parameters to replace placeholders in the messages.\n */\nfun showToPlayer(player: Player, titleKey: String, subtitleKey: String, vararg params: String)\n```\n\n## Using Clickable Tags\n\nWith [MiniMessage](https://docs.advntr.dev/minimessage/format.html#click), you can create interactive messages by\nadding clickable tags such as hover and click events. Here are some examples of using clickable tags\nin your messages:\n\n**Example usage in YAML files**:\n\n```yml\nwelcome_message: \"\u003cclick:open_url:https://example.com\u003eVisit our website\u003c/click\u003e\"\ninfo_message: \"\u003cclick:run_command:/rules\u003eClick here to view rules\u003c/click\u003e\"\nwarning_message: \"\u003cclick:suggest_command:/report \u003eReport a user\u003c/click\u003e\"\n```\n\n## Using Color Codes\n\nThis library utilizes [MiniMessage](https://docs.advntr.dev/minimessage/format.html#color) to parse and handle color\ncodes and text formatting in messages. You can use MiniMessage's syntax in your message strings to\napply colors, formatting, and other features. Here are some examples of MiniMessage syntax:\n\n**Example usage in YAML files**:\n\n```yml\nwelcome_message: \"\u003cgreen\u003eWelcome to our server!\u003c/green\u003e\"\ninfo_message: \"\u003cblue\u003e\u003cbold\u003eInfo:\u003c/bold\u003e\u003c/blue\u003e Remember to follow the server rules!\"\nwarning_message: \"\u003cred\u003e\u003cbold\u003eWarning:\u003c/bold\u003e\u003c/red\u003e Fly is not allowed \"\n```\n\n## Usage\n\n### Creating new instance of Message\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport org.bukkit.plugin.java.JavaPlugin\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"), JavaPlugin())\n```\n\n### Creating new instance of Title\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Title\n\nTitle(File(\"path/to/titles.yml\"))\n```\n\n### Creating new instance of Title with custom times\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport java.time.Duration\nimport dev.josantonius.minecraft.messaging.Title\n\nval stay    = Duration.ofSeconds(5)\nval fadeIn  = Duration.ofSeconds(1)\nval fadeOut = Duration.ofMillis(1000)\n\nval times = Title.Times.of(fadeIn, stay, fadeOut)\n\nTitle(File(\"path/to/titles.yml\"), times)\n```\n\n### Set console prefix for messages\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\n\nmessage.setConsolePrefix(\"[MyPlugin]\")\n```\n\n### Set chat prefix for messages\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\n\nmessage.setChatPrefix(\"\u003cred\u003e[MyPlugin]\u003cwhite\u003e\")\n```\n\n### Send message to all online players on the server\n\n**`messages.yml`**\n\n```yml\nwelcome:\n  message: \"Welcome to this server!\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\n\nmessage.sendToPlayers(\"welcome.message\")\n```\n\n### Send message to all online players on the server with parameters\n\n**`messages.yml`**\n\n```yml\ngame:\n  start: \"Game '{1}' started. Good luck, {2}!\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\n\nmessage.sendToPlayers(\n    key = \"game.start\",\n    params = arrayOf(\"CaptureTheFlag\", \"everyone\")\n)\n```\n\n### Send message to a specific player\n\n**`messages.yml`**\n\n```yml\nplayer:\n  teleport: \"You have been teleported to The End.\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport org.bukkit.entity.Player\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\nval targetPlayer: Player = //...\n\nmessage.sendToPlayer(\n    player = targetPlayer, \n    key = \"player.teleport\"\n)\n```\n\n### Send message to a specific player with parameters\n\n**`messages.yml`**\n\n```yml\nplayer:\n  points: \"You have earned {1} points, {2}!\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport org.bukkit.entity.Player\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\nval targetPlayer: Player = //...\n\nmessage.sendToPlayer(\n    player = targetPlayer,\n    key = \"player.points\",\n    params = arrayOf(\"100\", targetPlayer.name)\n)\n```\n\n### Sends a system message to the console\n\n**`messages.yml`**\n\n```yml\nwarnings:\n  wrong_input: \"Warning: it is not a valid input.\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\n\nmessage.sendToConsole(\n    key = \"warnings.wrong_input\"\n)\n```\n\n### Sends a system message to the console with parameters\n\n**`messages.yml`**\n\n```yml\ninfo:\n  wrong_input: \"Info: {} is not a valid input.\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\n\n\nmessage.sendToConsole(\n    key = \"info.wrong_input\",\n    params = arrayOf(\"command\")\n)\n```\n\n### Sends a message to all online players and the console\n\n**`messages.yml`**\n\n```yml\nwarning:\n  restart: \"Warning: The server will restart.\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\n\nmessage.broadcast(\n    key = \"warning.restart\"\n)\n```\n\n### Sends a message to all online players and the console with parameters\n\n**`messages.yml`**\n\n```yml\nwarning:\n  restart: \"Warning: The server will in {1} minutes.\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\n\n\nmessage.broadcast(\n    key = \"warning.restart\"\n    params = arrayOf(\"10\")\n)\n```\n\n### Retrieves the message associated with the given key\n\n**`messages.yml`**\n\n```yml\nplayer:\n  win: \"Congratulations, you won the game!\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\n\nmessage.getString(\n    key = \"player.win\"\n)\n```\n\n### Retrieves the message associated with the given key with parameters\n\n**`messages.yml`**\n\n```yml\ncommand:\n  cancel: \"Run \u003ccommand\u003e/cancel\u003c/command\u003e to cancel the challenge.\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\n\nmessage.getString(\n    key = \"command.cancel\",\n    params = arrayOf(\"first\")\n)\n```\n\n### Retrieves the component associated with the given key\n\n**`messages.yml`**\n\n```yml\nsee:\n  rules: \"See our \u003clink\u003ehttps://mc.com\u003c/link\u003e before accepting challenges.\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\n\nmessage.getComponent(\n    key = \"see.rules\"\n)\n```\n\n### Retrieves the component associated with the given key with parameters\n\n**`messages.yml`**\n\n```yml\nplayer:\n  win: \"Congratulations, you won the {1} game!\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Message\n\nval message = Message(File(\"path/to/messages.yml\"))\n\nmessage.getComponent(\n    key = \"player.win\",\n    params = arrayOf(\"first\")\n)\n```\n\n### Show title and subtitle to a specific player\n\n**`titles.yml`**\n\n```yml\ntitle:\n  welcome: \"Welcome!\"\n  subtitle: \"Enjoy your time on our server!\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport org.bukkit.entity.Player\nimport dev.josantonius.minecraft.messaging.Title\n\nval title = Title(File(\"path/to/titles.yml\"))\nval targetPlayer: Player = //...\n\ntitle.showToPlayer(\n    player = targetPlayer,\n    titleKey = \"title.welcome\",\n    subtitleKey = \"title.subtitle\"\n)\n```\n\n### Show title without subtitle to a specific player\n\n**`titles.yml`**\n\n```yml\ntitle:\n  warning: \"Warning!\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport org.bukkit.entity.Player\nimport dev.josantonius.minecraft.messaging.Title\n\nval title = Title(File(\"path/to/titles.yml\"))\nval targetPlayer: Player = //...\n\ntitle.showToPlayer(\n    player = targetPlayer,\n    titleKey = \"title.warning\",\n    subtitleKey = \"\"\n)\n```\n\n### Show title without subtitle and with parameters to a specific player\n\n**`titles.yml`**\n\n```yml\ntitle:\n  congrats: \"Congratulations, {1}!\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport org.bukkit.entity.Player\nimport dev.josantonius.minecraft.messaging.Title\n\nval title = Title(File(\"path/to/titles.yml\"))\nval targetPlayer: Player = //...\n\ntitle.showToPlayer(\n    player = targetPlayer,\n    titleKey = \"title.congrats\",\n    subtitleKey = \"\",\n    params = arrayOf(targetPlayer.name)\n)\n```\n\n### Show title and subtitle to all online players on the server\n\n**`titles.yml`**\n\n```yml\nwelcome:\n  title: \"Welcome to our Server!\"\n  subtitle: \"Enjoy your stay.\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Title\n\nval title = Title(File(\"path/to/titles.yml\"))\n\ntitle.showToPlayers(\"welcome.title\", \"welcome.subtitle\")\n```\n\n### Show title without subtitle to all online players on the server\n\n**`titles.yml`**\n\n```yml\nevent:\n  title: \"Special Event Starting Soon!\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Title\n\nval title = Title(File(\"path/to/titles.yml\"))\n\ntitle.showToPlayers(\"event.title\", \"\")\n```\n\n### Show title without subtitle and with parameters to all online players on the server\n\n**`titles.yml`**\n\n```yml\ngame:\n  title: \"Game '{1}' Starting in {2} minutes!\"\n```\n\n**`Main.kt`**\n\n```kotlin\nimport java.io.File\nimport dev.josantonius.minecraft.messaging.Title\n\nval title = Title(File(\"path/to/titles.yml\"))\n\ntitle.showToPlayers(\n    titleKey = \"game.title\",\n    subtitleKey = \"\",\n    params = arrayOf(\"CaptureTheFlag\", \"5\")\n)\n```\n\n## TODO\n\n- [ ] Add new feature\n- [ ] Add 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-messaging/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-messaging/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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosantonius%2Fminecraft-messaging","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosantonius%2Fminecraft-messaging","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosantonius%2Fminecraft-messaging/lists"}