|
| 1 | +--- |
| 2 | +order: 2 |
| 3 | +authors: |
| 4 | + - JorelAli |
| 5 | + - misode |
| 6 | + - DerEchtePilz |
| 7 | +--- |
| 8 | + |
| 9 | +# Spigot chat arguments |
| 10 | + |
| 11 | +## Chat color argument |
| 12 | + |
| 13 | + |
| 14 | + |
| 15 | +The `ChatColorArgument` class is used to represent a given chat color (e.g., red or green). This argument returns the `ChatColor` object. |
| 16 | + |
| 17 | +::::tip Example – Username color changing plugin |
| 18 | + |
| 19 | +Say we want to create a plugin to change the color of a player's username. We want to create a command of the following form: |
| 20 | + |
| 21 | +```mccmd |
| 22 | +/namecolor <chatcolor> |
| 23 | +``` |
| 24 | + |
| 25 | +We then use the `ChatColorArgument` to change the player's name color: |
| 26 | + |
| 27 | +:::tabs |
| 28 | +===Java |
| 29 | +<<< @/../reference-code/src/main/java/createcommands/arguments/types/chat/SpigotChatArguments.java#chatColorArgumentExample |
| 30 | +===Kotlin |
| 31 | +<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/chat/SpigotChatArguments.kt#chatColorArgumentExample |
| 32 | +===Kotlin DSL |
| 33 | +<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/chat/SpigotChatArguments.kt#chatColorArgumentExampleDSL |
| 34 | +::: |
| 35 | + |
| 36 | +:::: |
| 37 | + |
| 38 | +:::info |
| 39 | + |
| 40 | +The two following classes, `ChatComponentArgument` and `ChatArgument` depend on a [Spigot](https://www.spigotmc.org/) based server. This means that these arguments will not work on a non-Spigot based server, such as CraftBukkit. If you use this class on a non-Spigot based server, it will throw a `SpigotNotFoundException` |
| 41 | + |
| 42 | +::: |
| 43 | + |
| 44 | +## Chat component argument |
| 45 | + |
| 46 | +The `ChatComponentArgument` class accepts raw chat-based JSON as valid input. Despite being regular JSON, it _must_ conform to the standard declared [here](https://minecraft.wiki/w/Raw_JSON_text_format), which consists of JSON that has a limited subset of specific keys (In other words, you can have a JSON object that has the key `text`, but not one that has the key `blah`). |
| 47 | + |
| 48 | +This is converted into Spigot's `BaseComponent[]`, which can be used for the following: |
| 49 | + |
| 50 | +- Broadcasting messages to all players on the server using: |
| 51 | + |
| 52 | + ````java |
| 53 | + Bukkit.getServer().spigot().broadcast(BaseComponent[]); |
| 54 | + ```` |
| 55 | + |
| 56 | +- Adding and setting pages to books using `BookMeta`: |
| 57 | + |
| 58 | + ```java |
| 59 | + BookMeta meta = // ... |
| 60 | + meta.spigot().setPages(BaseComponent[]); |
| 61 | + ``` |
| 62 | + |
| 63 | +- Sending messages to `Player` objects: |
| 64 | + |
| 65 | + ```java |
| 66 | + Player player = // ... |
| 67 | + player.spigot().sendMessage(BaseComponent[]); |
| 68 | + ``` |
| 69 | + |
| 70 | +- Sending messages to `CommandSender` objects: |
| 71 | + |
| 72 | + ```java |
| 73 | + CommandSender sender = // ... |
| 74 | + sender.spigot().sendMessage(BaseComponent[]); |
| 75 | + ``` |
| 76 | + |
| 77 | +::::tip Example - Book made from raw JSON |
| 78 | + |
| 79 | +Say we want to generate a book using raw JSON. For this example, we'll use the following JSON (generated from [minecraftjson.com](https://minecraftjson.com/)) to generate our book: |
| 80 | + |
| 81 | +```json |
| 82 | +["", { |
| 83 | + "text": "Once upon a time, there was a guy call " |
| 84 | +}, { |
| 85 | + "text": "Skepter", |
| 86 | + "color": "light_purple", |
| 87 | + "hoverEvent": { |
| 88 | + "action": "show_entity", |
| 89 | + "value": "Skepter" |
| 90 | + } |
| 91 | +}, { |
| 92 | + "text": " and he created the " |
| 93 | +}, { |
| 94 | + "text": "CommandAPI", |
| 95 | + "underlined": true, |
| 96 | + "clickEvent": { |
| 97 | + "action": "open_url", |
| 98 | + "value": "https://github.com/JorelAli/CommandAPI" |
| 99 | + } |
| 100 | +}] |
| 101 | +``` |
| 102 | + |
| 103 | +Since we're writing a book, we must ensure that all quotes have been escaped. This can also be performed on the [minecraftjson.com](https://minecraftjson.com/) website by selecting "book": |
| 104 | + |
| 105 | +```json |
| 106 | +["[\"\",{\"text\":\"Once upon a time, there was a guy call \"},{\"text\":\"Skepter\",\"color\":\"light_purple\",\"hoverEvent\":{\"action\":\"show_entity\",\"value\":\"Skepter\"}},{\"text\":\" and he created the \"},{\"text\":\"CommandAPI\",\"underlined\":true,\"clickEvent\":{\"action\":\"open_url\",\"value\":\"https://github.com/JorelAli/CommandAPI\"}}]"] |
| 107 | +``` |
| 108 | + |
| 109 | +Now let's define our command. Since a book text is typically huge - too large to be entered into a chat, we'll make a command block compatible command by providing a player parameter: |
| 110 | + |
| 111 | +```mccmd |
| 112 | +/makebook <player> <contents> |
| 113 | +``` |
| 114 | + |
| 115 | +Now we can create our book command. We use the player as the main target by using their name for the author field, as well as their inventory to place the book. We finally construct our book using the `.setPages(BaseComponent[])` method: |
| 116 | + |
| 117 | +:::tabs |
| 118 | +===Java |
| 119 | + |
| 120 | +===Kotlin |
| 121 | + |
| 122 | +===Kotlin DSL |
| 123 | + |
| 124 | +::: |
| 125 | + |
| 126 | +:::: |
| 127 | + |
| 128 | +## Chat argument |
| 129 | + |
| 130 | +:::info |
| 131 | + |
| 132 | +The `ChatArgument` class is an argument similar to the [`GreedyStringArgument`](../string-arguments#greedy-string-argument), in the sense that it has no terminator and must be defined at the end of your `List` of arguments. For more information on this, please read the section on [Greedy arguments](../string-arguments#greedy-string-argument). |
| 133 | + |
| 134 | +::: |
| 135 | + |
| 136 | +The `ChatArgument` is identical to the `GreedyStringArgument`, with the added functionality of enabling _entity selectors_, such as `@e`, `@p` and so on. The `ChatArgument` also returns a `BaseComponent[]`, similar to the `ChatComponentArgument`. |
| 137 | + |
| 138 | +::::tip Example – Sending personalized messages to players |
| 139 | + |
| 140 | +Say we wanted to broadcast a "personalized" message to players on the server. By "personalized", we mean a command which changes its output depending on whom we are sending the output to. Simply put, we want a command of the following syntax: |
| 141 | + |
| 142 | +```mccmd |
| 143 | +/pbroadcast <message> |
| 144 | +``` |
| 145 | + |
| 146 | +Say we're on a server with two players: _Bob_ and _Michael_. If I were to use the following command: |
| 147 | + |
| 148 | +```mccmd |
| 149 | +/pbroadcast Hello @p |
| 150 | +``` |
| 151 | + |
| 152 | +_Bob_ would receive the message "Hello Bob", whereas _Michael_ would receive the message "Hello Michael". We can use the `ChatArgument` to create this "personalized" broadcast: |
| 153 | + |
| 154 | +:::tabs |
| 155 | +===Java |
| 156 | + |
| 157 | +===Kotlin |
| 158 | + |
| 159 | +===kotlin,Kotlin DSL |
| 160 | + |
| 161 | +::: |
| 162 | + |
| 163 | +:::: |
0 commit comments