# command annotation

```csharp
@Katton.command(name = "name", permission = "admin" | "creative" | "all")
function handler(sender, args) {
    ...
}
```

### requirements

* the function must take **exactly** two parameters: `sender` and `args` (you can name them whatever you like, but there must be exactly two)
* `name` must be lowercase letters, numbers, underscores, and hyphens only
* `permission` must be exactly `"admin"`, `"creative"`, or `"all"`

### `name` uniqueness

```csharp
@Katton.command(name = "heal", permission = "admin")
function heal1(sender, args) { ... }

@Katton.command(name = "heal", permission = "all") // will error due to having a duplicate within this script
function heal2(sender, args) { ... }
```

### permission levels

| value | who can run it |
|---|---|
| `"admin"` | only the current admin |
| `"creative"` | only the current admin, **and** people who are in creative mode |
| `"all"` | only the current admin, **and** people who are in creative, spectator, survival, or adventure mode |

### `args`

everything typed after the command name in `/katton run <name> [arguments...]` comes through as a list of strings:

```csharp
@Katton.command(name = "give", permission = "admin")
function giveByName(sender, args) {
    if (args.size() == 0) {
        sender.sendMessage("&cusage: /katton run give <material>")
        return
    }

    val material = args[0]
    sender.give(Katton.item(material))
}
```

```
/katton run give diamond_sword
```

here, `args` is `["diamond_sword"]`, so `args[0]` is `"diamond_sword"`.
