data-driven event system
constellation.zenfyr.dev
1# Commands
2
3Commands in Commander are the main actors in your subscription.
4
5In JSON, a command is an object. The required `type` field selects the command that will be executed when the event is invoked.
6
7All command types accept a special `condition` field, that can operate on the current event context. The field uses the vanilla predicate system, so [misode.github.io](https://misode.github.io/predicate/) can be used to quickly create predicates.
8
9Various command types can take additional parameters.
10
11You can also use Commander commands in advancement rewards:
12
13```json
14{
15 "rewards": {
16 "commander:commands": [
17 {
18 "type": "commander:print",
19 "text": "42"
20 }
21 ]
22 }
23}
24```
25
26And other projects might integrate commands to other contexts!
27
28[[toc]]
29
30## Selectors
31
32Some commands require you to specify a "selector". A selector is a simple identifier that allows you to select a position and (optionally) an entity that will be used to perform an action. Selectors, with some exceptions, mimic vanilla loot contexts, built-in selectors can be found here: [BuiltInSelectors](https://github.com/constellation-mc/commander/blob/main/src/main/java/me/melontini/commander/impl/builtin/BuiltInSelectors.java)
33
34## Built-in commands
35The mod comes with a minimal set of commands, this is by design, as game interactions should be handled by brigadier `/` commands, or functions.
36
37### `commander:commands`
38This is the main type of command you will use when writing subscriptions.
39
40This command type expects a selector and either a list of commands or a function identifier. It's recommended that you provide a function identifier, as these are verified by the function loader on reload.
41
42::: details Example
43```json
44{
45 "type": "commander:commands",
46 "selector": "commander:random_player",
47 "commands": [
48 "/cmd:explode ~ ~1 ~ 2"
49 ]
50}
51```
52:::
53
54#### Command Macros
55
56If you opt into specifying commands using the array, you are a given an option of using command macros.
57
58A macro is a simple `${{}}` block, which allows you to dynamically insert info using expressions. For example:
59```
60"/say hi, my name is ${{level.dimension.location}}!"
61```
62will say `hi, my name is minecraft:overworld` in the overworld.
63
64You can learn more about expressions on this page: [Expressions](Expressions).
65
66By default macros return a string, but you can cast (convert) a macro into some other types like so:
67
68```
69$(long){{random(0, 34)}} 34.52946 -> 34
70$(double){{true}} true -> 1.0
71$(bool){{0}} 0 -> false
72```
73
74### `commander:cancel`
75This is a special command type that can only be used with supported event types.
76
77The only field required by this command is `value` with an appropriate return value.
78
79::: details Example
80```json
81{
82 "type": "commander:cancel",
83 "value": false
84}
85```
86
87```json
88{
89 "type": "commander:cancel",
90 "value": "fail"
91}
92```
93:::
94
95### `commander:all_of`, `commander:any_of`, `commander:defaulted`
96All three of these commands have a similar function. They accept a list of commands and if the condition is true, they execute the command specified in the optional `then` block.
97
98`all_of` requires all commands to execute successfully, `any_of` requires one command to execute successfully, and `defaulted` requires one command to fail.
99
100Note: even if the condition is true early, the command will still execute all commands! To chanage this, you can set `short_circuit` to true, in which case commands will be aborted immediately if the condition fails.
101
102::: details Example
103```json
104{
105 "event": "commander:player_use/item",
106 "commands": [
107 {
108 "type": "commander:all_of",
109 "condition": {
110 "condition": "minecraft:match_tool",
111 "predicate": {
112 "items": [
113 "minecraft:diamond"
114 ]
115 }
116 },
117 "commands": [
118 {
119 "type": "commander:commands",
120 "selector": "this_entity",
121 "commands": [
122 "/say mmm... diamond..."
123 ]
124 },
125 {
126 "type": "commander:cancel",
127 "value": "success"
128 }
129 ]
130 }
131 ]
132}
133```
134:::
135
136### `commander:random`
137This command type takes a weighted list of other commands and randomly executes some of them. By default, it rolls only once, but the number of rolls can be adjusted using the optional `rolls` field (Supports [Expressions](Expressions)).
138
139::: details Example
140```json
141{
142 "type": "commander:random",
143 "rolls": 2,
144 "commands": [
145 {
146 "weight": 2,
147 "data": {
148 "type": "commander:commands",
149 "selector": "this_entity",
150 "commands": [
151 "/say weight 2"
152 ]
153 }
154 },
155 {
156 "weight": 6,
157 "data": {
158 "type": "commander:commands",
159 "selector": "this_entity",
160 "commands": [
161 "/say weight 6"
162 ]
163 }
164 }
165 ]
166}
167```
168:::