# Existing features:

## commands and arguments
No suprise that everyone uses commands quite often. People use typed arguments and optional arguments very frequently, as expected. Interestingly, people seem to use literal arguments a lot more often than I expected. I'm not sure if this is a question issue, but it's interesting to note.

**usage:**

There's also not much to say about the opinions on these features.

**opinion:**

## special argument features

People don't seem very aware of names or default values for args, with names being rarer. No one seems to dislike them, however, which leads me to believe it's just a case of poor documentation.

**usage:**
**opinion:**

## prefixes

Prefixes seem to be pretty niche. There's a few who use them constantly, yet most hardly use them at all. I think this points to a wider request that users commonly bring up, which is the ability to hide what plugins commands are coming from. It's very common for users to try to block the prefixes for all commands, and I think this is an extension of that. Opinions on the entry aren't strong in either direction, though.

**usage:**
**opinion:**

**specific comments**
> Would love if there was a way to remove the viewing of /skript: commands so like custom command "hi", I want them to only see /hi and not /skript:hi

> prefix should not default to skript. If one is not set, it should not default to skript.

## aliases

Aliases are in pretty common use, with positive opinion. Not much to say here, apart from the request to make aliases overwrite other existing commands.

**usage:**

**opinion:**

**specific comments**
> When using aliases, they don't override commands/aliases from other plugins
Example:
I make a command "/balance" with an alias "/bal"
Having Essentials plugin installed
My custom "/balance" will override essentials, but "/bal" won't.

## executable by

Not used often, which I think is a bit of a shame. Opinion isn't strong here, which likely indicates people either would rather have their own custom error message (and hence handle it themselves) or just find it unnecessary to write out EB for each command.

**usage:**

**opinion:**

**specific comments**
> Executable by ... should have a globally configurable message without lang file changes

> Add "ops/operators" to the executable by

## usage

Very mixed usage, but generally postive sentiment. Based on specific comments and other feedback in the form, my conclusion is that the main complaint here is that it's not dynamic/flexible enough, and that people tend to just write custom error messages anyway.

**usage:**

**opinion:**

**specific comments**
> I dont like the Dark red message that appears above the Usage message if the command is invalid

> Wish there could be sections for usage, so you could highlight the parts that were incorrect/missed. (ex. missing arg-1, highlight arg-1; missing arg-2...)

> Usages should be automatically generated. (AN: they are?)

## description

Basically no one uses or cares about this. No notes.

**usage:**

**opinion:**

**specific comments**
> Description are useful for team work but for someone solo it's pretty useless.

## Permissions

Permissions are very commonly used and generally well regarded. I don't think any improvements need to be made here, expecting with the message.

One comment was made that the permission message only allows static strings, which I also found annoying with usage messages and recently changed in a PR. This could be a pretty simple improvement we can make.

Another mentions that the default error message for permissions and other checks should be configurable.

**usage:**

**opinion:**

**specific comments**
> permission/cooldown messages dont allow for anything other that plain strings with no line breaks (as far as i remember)

> ... permission should have a globally configurable message without lang file changes

## Cooldowns

Cooldowns aren't super commonly used, but it seems to be more of a use case thing than an active dislike. Opinion is generally positive on cooldowns and neutral on some of its more niche functions.

**usage:**

**opinion:**

**specific comments**

> ... cooldown ... should have a globally configurable message without lang file changes

> permission/cooldown messages dont allow for anything other that plain strings with no line breaks (as far as i remember)

> The cooldown features are VERY useful we need more would love to see it on events.

## miscellaneous comments

Note: These comments are prior to seeing any proposed features.

People generally seem to like the features Brigadier supports, like richer tab completion and argument coloring. We should look into either emulating these features or using Brigadier as an implementation.

> Use the Minecraft command syntax that makes the command args colored so we don’t need to use some random addon (sorry Shane)

> Brigadier support!!!!!

> Use brigadier please, it would be a real game changer

They also seem to want a more tree-like command structure for more complex commands

> Skript commands desperately need command overloading with literal arguments.
>
> If I want a complex command like:
> /lp user \<player\> parent add \<text\>
> /lp group \<text\> permission set \<text\> \<boolean = true\>
>
> I have to do this:

command lp <text>:
trigger:
set {_args::*} to split arg at " "

if {_args::1} is "user":
set {_player} to player({_args::2})

if {_args::3} is "parent":
# ...
else if {_args::1} is "group":
# ...

> It ends up being really messy! Ideally, I could do this instead:

command lp user <player> parent add <text>:
trigger:
# ...

command lp group <text> permission set <text> <boolean = true>:
trigger:
# ...

> This makes the code much cleaner, and I can use Skript's argument parser instead of manually parsing them myself, which is less performant and messier.

> also arguments should have the option to be positioned in a 'tree' kind of way

> This sounds very like, unhelpful
but I feel like some of the stuff in commands could be structured differently
>
> or basically how you create commands I guess.

# pain points

This question was answered by nearly all respondents. 8 default options were given, with the ability to add a custom response as well. The given options were:
- A lack of flexibility with argument positioning
- A lack of tab completion syntax
- The inability to use two multi-word text arguments back to back.
- Setting command cooldowns
- Setting command permissions
- Checking if the arguments were valid, or what you expected them to be
- Customizing usage messages
- Trigger sections becoming very long when handling lots of argument combinations
- other: custom response

(custom responses will be addressed later)

## non-issues
This indicates that users have little to no issues with the current cooldown/permission system, but do find some irritation with usage messages being so static. This tracks with the findings in the previous section.

One custom response did have an interesting suggestion, though.
> Allow metadata storage for cooldown

## tab completion
This has been highly requested and is a major part of the plan for the command rework. Skript has only some default completion for player arguments and that's it, so the community is reliant on SkBee's text-only tab completion event.

A custom response doubles down on the Brigadier suggestions.
> For the tab completion syntax I really like skBriggy I would love to see something similar to it

## argument flexibility
Interestingly, only about 30% of respondents were irritated by argument flexibility, despite quite a few responses bringing up command tree structures throughout this form. This may indicate that this issue is more of an advanced user problem that the majority of users don't run into.

Alternatively, this options could have been poorly phrased, leading to people not quite understanding what it represented.

> No command overloading with literal arguments !!!

## text arguments
A bit of a dark horse, text argument parsing was a major complaint! two custom responses even followed up with more specific feedback. This should probably be a key point of improvment in the rework, likely with a quoted string argument.

> A two string in a command results in confusion at some time, specially if the first string uses 2 words

> If at all possible, with the multiple words for one text argument, make a new type and the arg has to be incased in like quotes.

## trigger section length
This is the other major pain point with commands. Command length can balloon with more complex arguments, leading to complex and hard to follow code. This is rather unsurprising and something that nearly every proposed feature targets.

## misc
The final custom response mentioned timespan arguments:
> he built-in timespan argument should use the short format, ex. 5d3m for 5 days and 3 minutes

# possible additions

Note: "good idea, poor implementation" responses have been omitted from this recap, as they did not provide any valuable info. Inclusion of this option was a poor decision, as it meant people didn't feel the need to explain *why* the implementation was poor. On the later questions where this option was omitted, more custom feedback was given.

## Choice Arguments

The general consensus here was that this feature is easy to use and intuitive, but that the proposed syntax of `choice` or `choice arg` was poor. Conversation should be had about how to properly access the selected value in code.

Other concerns included the length of the command if many choices were used, and further suggestions of command trees or even other options that will be proposed later in the survey.

In general, this seems like a shoe-in feature.


### comments
> I think: /faction (join, leave, info) \<text\> is better

> You could also explore the concept of command trees (which is how brigadier commands look) but it may not be as skript-user-friendly. It could be interesting to see as its own section kind of like how skbriggy does that.

> Looks amazing, but please support the old command system as well. I have a massive Skript that uses the current command system with arguments like that, and it would probably take me like 20 hours to recode everything if not longer.

> instead of "choice arg-1", i feel like keeping just "arg-1" would be plenty

> How about a section "choices:" then you can do "set choice arg-1 to list" on a different line. For the off chances that commands have like 10 choices, the command line wont go way off to the right

> Does it work with 'subcommand' style arguments?

> Could the word "choice" be left out?

> You still get a complex trigger, it should be split up into multiple by default. So you define the command itself with all properties, then all subcommands with a trigger.

> I feel like, if tab completion was also a feature, this wouldn't be nessescary. I still like it though

> it will get long if you have many

> Consistent: Falls in line with "Skript syntax."

> some text inputs its hard to write | so maybe an alternative %something% method would be great

> Very understandable for everyone, and easy to check

## Tab Completion

Tab completion had three proposed ways to tackle it. In-command and per-argument were both popular options, though in-command seems slightly more popular.

In general, users disliked in-argument completions but were enthusiastic for anything else. The main sentiment was that users are used to SkBee tab completions and would prefer something with, at minimum, the same amount of control and flexibility. In addition, the less work the user has to do to add tab completions, the better, it seems.

As already addressed in conversations, a similar tab complete event will need to be added no matter what we add to the command structure, so the main conversation should be about the addition features we can add in the command structure itself.

### In-command


The main feedback here was around the `disable tab completions` syntax included in the example. This is mainly separate from the proposed feature as a whole, but something to consider going forward.

Other concerns included the thought that users may not realise this is an event that runs each tab complete, or that it may get kind of complex when tab completions are added to an already complicated command structure.

One user even suggested the custom argument type idea that will be discussed later in this writeup, which is rather humerous. Great minds think alike, though I suppose fools rarely differ.

**specific comments**
> Unsure if this is just a flaw of the code example; why disable the tab completions when you can just not show them in the first place?

> It looks quite great. Definitely allows for some advanced display. Does this also allow the usage of tooltips (when you hover over the suggestion)?

> whatever's going on in the 'disable tab completions ...' bit looks horrible, should be a deleteable object

> I see the use case, but theres already addons like skbee that have tab competition that I feel work nicely, and I feel that it honestly creates more organization, when im creating commands I would not want to have to worry about tab complete in the same section

> An alternative is to allow advanced users define their own types for commands and then provide tab completion for it. So here instead of text it would be home and there would be a structure entry with "type home: text" and another tab complete structure entry where the parameters come in with their type so you can provide completions. SHOULD USE BRIGADIER INTERNALLY!!!

### Per-argument


People seemed mostly in favour, but slightly more skeptical than with the in-command version. I would attribute this to the slightly more rigid structure of this version, which makes it a bit harder/more confusing to do the more complex, argument-dependent completions. Overall, I think this is a valid approach but slightly less valuable than in-command.

**specific comments**
> This one looks like it has more control than the one above, so it is nice. It might be nice if you can still also do "set the tab completions of %arg% to blah" but I'm no skript expert, so I have no idea if that's even possible

> it seems a little messier this way to me but honestly either way works great

> it's ok

> This is obviously the most like SkBee, so I reckon most users would like something like this. That being said, compared to other options, this is less useful. Like, compare this to any of the validation entry ones and the latter is leagues better.

### In-argument

This was not a popular option. People were very confused by how it works, were confused about how it would interact with default values, and very concerned about it causing lines to be very long. I don't think we should consider moving forwards with this option.

**specific comments**
> Make it like SkBee

> Can imagine this getting out of hand for longer commands or stuff with a bunch of different options, such as /setkit \<player\> \<kitname\> & having like 30 different kits

> good idea for static completions, but could be messy when combined with the other tab completion implementations

> This is going to get way too messy just to get a good-looking command.

> if somebody were to look at this code and they didn't have an explanation, they would probably be really confused what this does. a default value with a "tab completions" expression i've never seen before? what value is the string given when i don't provide the arg? the syntax would need to be changed to be more clear and not clash with default values

> its cool but having those %% in there looks annoying, it looks like a nooby one liner

> Would run the command line far to the side. Seems would be a hassle to set arg-2 completions based on arg-1

> Becomes confusing with longer lines, in my opinion keep tab complete 100% separate from the command, it is not part of the command it is an event. and if the command isnt created in skript then they will have to use the event, which will create a split

> I dont want lines which are 200 characters, this is just bad design

> Makes for congested and unreadable code

> It's kinda hard to read especially when you would probably have a few of them and gets long

> Best one

## Multi-structure Commands

Multi-structure commands were proposed to address two main issues. First, of argument order being very inflexible. Having a more tree-like structure allows more complex options, including changing the argument type/order based on inputs to earlier arguments. Second, to combat the issue of extremely long trigger sections, easily hitting 300+ lines on larger commands.

A few variations on this theme were proposed, from truly different structures to subcommands within the same structure. Opinion on all the variations was mostly similar, with multi-structure commands being the easiest and most intuitive, while subcommands was considered the most useful. We should consider all these options carefully when designing the final solution.

### Multistructure Commands


Most people were in support of this option, but had some concerns about implementation details. Having to type out "/command xyz" for every structure was one concern, followed by worries about how the properties of the command structures would interact.

**specific comments**
> would probably be confusing at first, but i like this idea.

> dont do this

> I think this really makes a lot of sense given skript's idiomacy. Being able to insert normal text as if you were writing the command's usage is convenient and powerful.

> YES

> having to specify 'command /faction' for all 3 subcommands looks like a real pain in my opinion, i'd prefer a more 'tree' kind of structure, kinda like the 'if:... then:...' which goes 1 indentation deeper and then goes back 1

> thee part that would be confusing to me is using arg-1 instead of arg-2. while it is referring to the first input argument, i still feel like it is the second argument.

> aliases integration to directly access sub commands would be nice

> should not be added as it would confuse beginners as we tell them constantly that's not how commands work

> Exploring command trees is probably the most powerful (and potentially hardest) thing you can change with the command system. At the same time, being able to write a command in the style of its "usage form" is intuitive and idiomatic for basic use cases, so it should definitely stay. It looks great so far!

### Multipattern Commands


People had very similar responses to this option as they did multi-structure commands, which makes sense. The two options are very similar. Concerns were more about the differences to the multi-structure option than in general. Namely, that keeping it all in one structure meant you have to put everything into one file, when you may want to spread it out. Or that the multiple triggers don't allow you to assign separate permissions or other properties to the subcommands.

Overall, sentiment seems to indicate that this is just a slightly worse version of multi-structure commands.

**specific comments**
> Kinda weird, but this is very useful!

> Little confusing on the "trigger \<argument\>" part; not the most intuitive on that end. Aside from that, could be very cool

> I'm starting to see the formation of command trees :D

> this looks really clean but with a system like this, you aren't able to provide specific permissions/permission messages/cooldown per subcommand. the other method is more featureful and less structured. this is more structured and imo cleaner, but less useful

> i love it, but how would it work in case you wanted to do this but for the second argument?

> This one is better

> This is my new least favourite actually. Having multiple triggers seems odd to me, and less preferable than declaring them in the one line and using something like a validation section instead.

> This does require you to put it all in the same script file which is not always prefered

> I BEG YOU

> Will the old command syntax still work?

## Subcommands


This option seems like the option most people thought was useful. It allows the same flexibility of properties as the multi-structure commands, while keeping things contained into a single structure for clarity. People did find it slightly more confusing than multi-structure commands, but thought it was similarly easy to use. I think that's a good tradeoff overall.

**specific comments**
> I love.

> Other implementation is better

> you solved all the problems i pointed out in the previous post. i view this as the best way to handle it

> i think 'subcommand' should be dropped and be replaced with 'branch', yk, like a tree, the command is branching off into the 'join' string for arg 1, easy to understand and much easier than 'subcommand'

> 10/10

> It is indeed useful, just confused on how to use it ingame, is it still like faction <join|invite|leave>? if yes then this is way better

> For sure more useful than the multi-pattern commands, and the added advantage of having the entries for each subcommand is actually pretty good.

> Good for advanced users, but not intuitive how properties inherit from their parents

> I BEG YOU

> this is the same with different words?

> Will the old command syntax still work?

## Argument Validation

Argument validation is mainly aimed at cleaning up trigger sections and preventing the user from being overwhelmed by if-else trees. It tries to move the logic of validating the arguments outside of the trigger section to their own locations, or even saving the user from writing them in general. In some sense, choice arguments are even a type of argument validation.

A few different options were proposed, varying from a section that runs prior to trigger, to a tree of entries that defines the valid options, or completely custom arugment types that have their own validation systems.

This feature is probably the one that needs the most work, as people found the idea very useful but were generally confused or concerned about implementation details.

### Validation Section


This is the most generic and straightforward option, where a section runs that sets the valid options and error messages for each argument. It, however, was pretty confusing to users, who didn't really get when it would be run, what restrictions there were, etc. The main takeaway is we need to figure out the details on how something like this would work.

**specific comments**
> I'm assuming that "set valid options" and "ensure %arg% matches" are mutually exclusive?

> setting 'valid options of ...' without setting tab completions should be an option. 'usage message' could also be 'error message''

> what am i looking at 💀

> Good idea to have argument validation, but theres got to be a better way then that.

> tab completes but better!

> Confusing in general

> looks ok, but i think having actual code (as in effects) before the trigger can be confusing, especially for old timers

### Validation Entries


These were slightly better received, as people understood them more easily. However, concerns were raised that this option was much more rigid and difficult to do anything complex with.

**specific comments**
> I think this is an improvement over the corresponding feature idea, but it lacks advanced control (at first glance). For example, you (presumably) cannot base arg 2's validation on what arg 1 was.

> it seems more flexible to validate arguments with code (or aforementioned types, i love that!) than entries.

> i like this but please, please please please, do not make this a replacement for any of the other ideas, make this some sort of easier way to do it in case you dont need a lot of customization

> I feel as if this might be confusing to newer skripters. And its not too useful, since its basically just an if statment done for you. also I feel like it would be better for new people just to learn it with loops/conditionals

> Not flexible enough

> I know this is less Skripty than the others, but easily the most preferable and intuitive (especially for new users) in my opinion.

> Would prefer the type solution

> I think it improves readability of commands, but at the same time this could be done fairly easily in a trigger

### Custom Arguments


Custom arguments were a bit divisive. Some found them absolutely wonderful and a must have, while others were completely confused on how to use them. My theory is that those who have used reflect and its custom syntaxes before understood what they were meant to do, while newer users were much more confused.

This may be a feature we want to gate behind some experiments, or add to a addon like reflect.

**specific comments**
> Oop!

> This is great, but it doesn't really feel like something I'd expect from skript. This would definitely be something that's an advanced feature, though this would really tie well into the backend of command trees (at least I assume it would)

> this is an awesome idea, please do this!

> very reflect-like suggestion, i like it but it definitely needs some adjustments, like in the 'pattern' option: 'text' is the type and 'name' is the local variable name and i think it should be implied/said that it is that way to cut off any doubts from first impressions. it should also be specified that stopping in the check section makes the argument fail (+ again 'usage message' should also be able to be 'error message' imo)

> this feels like it would be a very good addition to skript-reflect, but not normal skript.

> Not confusing for me personally, but I can see the average Skript user not quite following the pattern and check parts of this.

> YES YES YES

> It seems like a good idea and makes sense. But it's hard to see how much of a purpose it'd really have.

> I think it would be nice to have completion/validation on either command or a argument type

# Conclusion

Our initial theories for the pain points (tab completes, long trigger sections, and inflexibility in arguments) seem to be echoed pretty closely by the community, with the addition of wanting quoted text arguments.

We definitely need a tab completion solution, and it seems like a separate event in combination with a in-structure section is the best way to go about it.

Choice arguments seem like a simple and easy solution to some bloat in the trigger section and should cut down on some if/elses.

Multi-structure commands, or command trees, are definitely something we should focus on supporting. We should not, under any circumstances, completely break the original method of making commands, though. Keeping a command within one structure is likely the best way to go about it for readabillity purposes, but having separate structures could be valueable for more freedom of organization.

Validation seems like a popular feature, but we need to narrow down how exactly we want to do it. The current ideas are a bit too nebulous right now. Custom arguments are promising, but perhaps a bit out of Skript scope.

In the end, the most positive feedback was clustered on options with the fewest restrictions on what the user could do (providing sections seems better than providing entries), but also on those that were the easiest to understand. This shouldn't really be a surprise, but it does mean that we should be quite wary of jumping the shark with new additions.

In a related note, users seem to be very attracted to the features offered by Brigadier (colour tab completion, grouped arguments, etc) and we should look into a Brigadier implementation of Skript commands.