# Commands

{% hint style="warning" %}
These commands cannot be executed by console, or by command blocks. You need an entity (typically a player) to execute these custom commands.
{% endhint %}

MechanicsEverywhere lets you create custom commands which trigger [Mechanics](https://app.gitbook.com/o/MgHAZkcfIhs3YcmBjk2r/s/hz7yMxlL81NxAT44nraH/ "mention"). This allows you to create instruction commands, visual effects, and other fun admin tools. This can also be used to give donator perks. To add a command, go into this folder:

> <mark style="color:yellow;">your server -> plugins -> MechanicsEverywhere -> commands</mark>

And create a new `.yml` file. Then, you can use these options:

```yaml
<label>:
  Description: <String>
  Permission:
    Name: <String>
    Description: <String>
    Default: <TRUE/FALSE/OP/NOT_OP>
  Aliases:
    - "alias1"
    - "alias2"
    - "etc"
  Mechanics: <Mechanics>
  Allow_Targeter: <NONE/ENTITY/ENTITIES/PLAYER/PLAYERS>  
  Subcommands:
    <label1>: <Command> # This uses all of the options ^
    <label2>: <Command> # ^
    <etc>: <Command>
  Help:
    Color: "<gold>" # Any color code and/or format code
    Accent: "<gray>"
    Symbol: <String>
```

#### \<label>

The label is the unique name for your command, and how you will spell it in Minecraft. So if you use `tpa` for the label, you will use `/tpa` in-game.&#x20;

#### Description

A generalized description of what the command does. This is optional, but you should use it if you want to use the [#help](#help "mention") feature.&#x20;

#### Permission

A custom permission which is required to run the command. If you use a permission that already exists (for example, `essentials.fly` from EssentialsX), make sure you *do not* use the `Description` and `Default` options, since they will override the values.

* `Name` -> The name of the permission, like `mechanicseverywhere.myawesomecommand`
* `Description` -> A short description of what the permission does (For permission managers).
* `Default` -> Who has this permission by default (see below)? Defaults to `OP`.

{% tabs %}
{% tab title="TRUE" %}
All players have permission by default.
{% endtab %}

{% tab title="FALSE" %}
No players have permission by default.
{% endtab %}

{% tab title="OP" %}
Only `/op` players have permission by default.
{% endtab %}

{% tab title="NOT\_OP" %}
Only non-op players have permission by default.
{% endtab %}
{% endtabs %}

#### Aliases

A list of "alternative shorthand names" for your command. For example:

```yaml
teleport:
  #<other options go here>
  Aliases:
    - tp
```

#### Mechanics

The "meat" of the command, or what actually happens. You can use mechanics to:

1. Run other commands
2. Play sounds/spawn particles/play effects
3. Apply potions/damage/movement

Use the [Mechanics](https://app.gitbook.com/o/MgHAZkcfIhs3YcmBjk2r/s/hz7yMxlL81NxAT44nraH/ "mention") wiki, and look at the examples below.

* `@Source{}` -> The entity who executed the command.
* `@Target{}` -> Depends on [#allow\_targeter](#allow_targeter "mention"), but none by default.&#x20;

#### Allow\_Targeter

{% hint style="warning" %}
`Allow_Targeter` may not be used with `Subcommands`
{% endhint %}

Consider the custom command `/murder`, which kills any targeted entity. When you use it in game, you may want to target only zombies, so you run something like:

> `/murder @e[type=minecraft:zombie]`

In this case, you would want to target multiple entities:

```yaml
  Allow_Targeter: ENTITIES
```

{% tabs %}
{% tab title="None" %}
No targeter is allowed.
{% endtab %}

{% tab title="Entity" %}
1 entity may be targeted.
{% endtab %}

{% tab title="Entities" %}
Any number of entities may be targeted.
{% endtab %}

{% tab title="Player" %}
1 player may be targeted.
{% endtab %}

{% tab title="Players" %}
Any number of players may be targeted.
{% endtab %}
{% endtabs %}

#### Subcommands

{% hint style="warning" %}
`Subcommands` may not be used with `Mechanics`, or `Allow_Targerter`.
{% endhint %}

Consider the vanilla command `/effect` (Which gives potion effects). The `/effect` command has 2 subcommands:

1. `give` -> Gives potion effects.
2. `clear` -> Clears potion effects.

Now let's create a command `/nv`, which turns on night vision. We can run `/nv on` to turn it in, or `/nv off` to turn it off. Let's see how we can do that with subcommands:

```yaml
nv:
  permission:
    name: "mechanicseverywhere.commands.nv"
  Subcommands:
    on:
      Mechanics:
        - "Potion{potion=NIGHT_VISION, time=1728000}" # 1 day, in ticks
    off:
      Mechanics:
        - "RemovePotion{potion=NIGHT_VISION}"
```

{% hint style="info" %}
Subcommands have all the same options as normal commands, except you can only use `Help` on the root command. Subcommands cannot use `Help`.&#x20;
{% endhint %}

#### Help

When you use this option, a "help menu" will be automatically generated for your command, which can be accessed by adding `help` or `?` after the command.&#x20;

* `Color` -> The main color, used for "identifying" information.
* `Accent` -> The accent color, used for longer names/descriptions.
* `Symbol` -> The symbol used for lists, defaults to `➢`.

{% hint style="info" %}
WeaponMechanics uses `<gold>` for the main color, and `<gray>` for the accent color. Since we use [MiniMessage](https://docs.advntr.dev/minimessage/format.html) to parse colors, you can use hex and styles:

![](https://3386962828-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDIc8xcPzpPGZNegssoGM%2Fuploads%2FVy89X2V7QKShQXmMTPy4%2Fimage.png?alt=media\&token=db1d61a8-2ac8-4b65-ae76-f6f19c132e42)
{% endhint %}