Arguments Usage

🔩 CommandsAPI – Arguments & Completion Guide (v4)

This guide covers how to add and customize arguments for your commands using CommandsAPI v4’s modular system.

---

➕ Adding Arguments

You can add arguments to a command using:

• addArgs(...) for required arguments
• addOptionalArgs(...) for optional arguments

Preferred Usage

The recommended and modern approach is to pass argument types directly using Java classes:

addArgs("name", String.class);
addOptionalArgs("amount", Integer.class);

This method provides better type safety, supports IDE autocompletion, and avoids parsing ambiguity.

Deprecated Syntax: name:type

While still supported for backward compatibility and for certain features (like infinite), the "name:type" syntax is now deprecated.

Use it only when dealing with infinite arguments:

addArgs("message:infinite"); // still valid and required for infinite support

Example

public class GreetCommand extends Command<MyPlugin> {

    public GreetCommand(MyPlugin plugin) {
        super(plugin, "greet");
        setDescription("A greeting command");
        setUsage("/greet <name>");

        // Preferred
        addArgs("name", String.class);

        // Deprecated (only for infinite)
        // addArgs("name:string");
    }

    @Override
    public void execute(CommandSender sender, Arguments args) {
        String name = args.get("name");
        sender.sendMessage("Hello, " + name + "!");
    }
}

---

🌍 Built-in Argument Types

Java Type	Identifier	Description
String	string	Accepts a basic string.
Integer	integer	Parses as integer.
Double	double	Parses as double.
Long	long	Parses as long.
Player	player	Online player (Spigot only).
OfflinePlayer	offlineplayer	Offline or online player.
String	infinite	Accepts infinite trailing arguments. Must be defined as "name:infinite"

⚠️ infinite only works using the deprecated syntax "name:infinite".

---

🛠️ Custom Argument Types

Create your own argument types by implementing the ArgumentConverter<T> interface:

public class CustomConverter implements ArgumentConverter<CustomType> {
    @Override
    public CustomType apply(String input) {
        return new CustomType(input);
    }
}

❌ Deprecated: Registration with Identifier

This form is deprecated and only necessary if using legacy "name:type" syntax (e.g., for infinite):

commandManager.registerConverter(CustomType.class, "customtype", new CustomConverter());

✅ Recommended Usage

Use this form instead:

commandManager.registerConverter(CustomType.class, new CustomConverter());

This works with:

addArgs("name", CustomType.class);

---

✨ Auto-Completion

Support tab-completion by implementing the TabCompleter interface:

public class CustomConverter implements ArgumentConverter<CustomType>, TabCompleter {

    @Override
    public CustomType apply(String input) {
        return new CustomType(input);
    }

    @Override
    public List<String> onCompletion(CommandSender sender) {
        return Arrays.asList("Alice", "Bob", "Charlie");
    }
}

Inline Completion:

addArgs("name", CustomType.class);
addArgs("number", Integer.class, (sender, args) -> Arrays.asList("1", "2", "3"));

---

🔐 Completion & Permissions

• Tab completions respect command permissions.
• If a sender lacks permission, they won't see suggestions.

---

🧐 Notes

• Prefer using addArgs("name", Type.class) instead of "name:type"
• Use "name:infinite" only for infinite string collection
• Retrieve infinite args using String infinireStr = args.get("name")
• Completions are platform-aware and permission-sensitive

---

Happy command building with CommandsAPI!