---
description: This is a guide to learn how to start with SmartCommands.
---

# Get started

### Initialize SmartCommands API

To use the API, you must first initialize it by using the `ApiBuilder` class. If you don't know how to use it, you can read the guide below.

{% content-ref url="tools/apibuilder" %}
[apibuilder](tools/apibuilder)
{% endcontent-ref %}

### Create a command

#### Using JSON

To create a command, you must first register it in a `json` file. In your project, create a file called `commands.json`. If you're using IntelliJ, you can use a resources folder to store your command files.

{% hint style="warning" %}
Using this API requires knowledge of the JSON format. You can read about it on the official [website](https://www.json.org/json-en.html).
{% endhint %}

Now, let's register our command. Open your `commands.json` file, open embraces, write the name of your command and reopen embraces.

```javascript
{
  "item": {}
}
```

{% hint style="info" %}
Here we will create a `/item` command so our command name is `item`.
{% endhint %}

Let's add different properties to our commands. The available properties are:

| Property       | Type               | Description                                                                              |
| -------------- | ------------------ | ---------------------------------------------------------------------------------------- |
| `description`  | `String`           | The description of the command                                                           |
| `usage`        | `String`           | The usage of the command                                                                 |
| `resource`     | `String`           | The path to the resource file of the command                                             |
| `resourceOnly` | `boolean`          | Set `false` if you don't want the command resource file to be created or else set `true` |
| `aliases`      | `List<String>`     | The aliases of the command                                                               |
| `issuers`      | `List<IssuerType>` | The type of issuer which can use the command (`PLAYER` and/or `CONSOLE`)                 |
| `tabComplete`  | `boolean`          | Set `true` if you want an automatic tab completer or else set `false`                    |

{% hint style="warning" %}
Properties `tabComplete` and `resourceOnly` are available only if you're using a command resource file.&#x20;
{% endhint %}

#### Example

```javascript
{
  "item": {
    "description": "A command to customize your items.",
    "usage": "/item",
    "resource": "commands/command_item.json",
    "resourceOnly": false,
    "aliases": ["it"],
    "issuers": ["PLAYER"],
    "tabComplete": true
  }
}
```

To get more information about command resource files,  you can read the guide below.

{% content-ref url="contents/command-contents" %}
[command-contents](contents/command-contents)
{% endcontent-ref %}

### Register your command

#### Prerequisite

To register our command in our plugin, we will need the `CommandManager` class. You don't have to create a new instance of this class because it automatically while initializing the API.&#x20;

First, let's get this class:

```java
CommandManager manager = api.getCommandManager();
```

#### Registration

Now, let's use the `registerCommand()` method from the `CommandManager` class. This method has two parameters:

| Parameter  | Type              | Description                                          |
| ---------- | ----------------- | ---------------------------------------------------- |
| `name`     | `String`          | The name of the command you want to register.        |
| `executor` | `CommandExecutor` | The class in which you want to register the command. |

```java
manager.registerCommand("item", new CommandItem());
```

If your command class does not exist, create it and import the methods of `CommandExecutor` interface.&#x20;

#### Example

```java
public class CommandItem implements CommandExecutor {
    
    @Override
    public boolean onCommand(SmartCommand command, CommandIssuer issuer, String label, String[] args) {
        return false;
    }

    @Override
    public List<String> onTabComplete(SmartCommand command, CommandSender sender, String label, String[] args, List<String> completions) {
        return null;
    }
}
```

Great, your command is registered. Now you can modify its behavior by adding code into the `onCommand()` method or add tab completions into the `onTabComplete()` method.

### Check if a command is registered

You can check if a command is registered by using the `isRegistered()` method from the CommandManager class.

| Parameter | Type     | Description                               |
| --------- | -------- | ----------------------------------------- |
| `name`    | `String` | The name of the command you want to check |

#### Example

```java
manager.isRegistered("item");
```

This method will return `true` if the command is registered or else it will return `false`.

### Check if a command is registered by a plugin

You can also check if a command is already registered by a plugin by using the `isRegistered()` method from the `CommandManager` class.

| Parameter | Type     | Description                                                                 |
| --------- | -------- | --------------------------------------------------------------------------- |
| `plugin`  | `String` | The name of the plugin you want to check that it has registered the command |
| `name`    | `String` | The name of the command you want to check                                   |

This method will return `true` if the command is registered by the plugin or else it will return `false`.

#### Example

```java
manager.isRegistered("MyPlugin", "item");
```

### Unregister commands

You can unregister a command by using the `unregisterCommand()` method from the CommandManager class.

| Parameter | Type     | Description                                                              |
| --------- | -------- | ------------------------------------------------------------------------ |
| `plugin`  | `String` | The name of the plugin that has registered the command to want to remove |
| `name`    | `String` | The name of the command you want to remove                               |

{% hint style="success" %}
This method will remove the command and all its aliases.
{% endhint %}

{% hint style="warning" %}
&#x20;Be sure the command is registered before using this method or you will have a `NullPointerException`.
{% endhint %}

#### Example

```java
if(manager.isRegistered("MyPlugin", "item")) 
    manager.unregisterCommand("MyPlugin", "item");
```
