Command Arguments

Typy argumentů a jejich použití v příkazech.

---

Typy Argumentů

| Metoda | Popis | Příklad |
|--------|-------|---------|
| withRequiredArg() | Povinný argument | /give |
| withOptionalArg() | Volitelný argument | /spawn [index] |
| withDefaultArg() | Argument s výchozí hodnotou | /echo [times=1] |
| withFlagArg() | Boolean flag | /list --online |

---

RequiredArg

Povinný argument - příkaz selže pokud není zadán.

public class GiveCommand extends AbstractPlayerCommand {
    @Nonnull
    private final RequiredArg playerArg =
        this.withRequiredArg("player", "myplugin.commands.give.player", ArgTypes.PLAYER_REF);
    @Nonnull
    private final RequiredArg itemArg =
        this.withRequiredArg("item", "myplugin.commands.give.item", ArgTypes.STRING);
    @Nonnull
    private final RequiredArg amountArg =
        this.withRequiredArg("amount", "myplugin.commands.give.amount", ArgTypes.INTEGER);
    public GiveCommand() {
        super("give", "myplugin.commands.give.desc");
    }
    @Override
    protected void execute(...) {
        PlayerRef target = playerArg.get(context);
        String item = itemArg.get(context);
        int amount = amountArg.get(context);
        // /give   
    }
}

---

OptionalArg

Volitelný argument - může být null.

public class TeleportCommand extends AbstractPlayerCommand {
    @Nonnull
    private final RequiredArg targetArg =
        this.withRequiredArg("target", "myplugin.commands.tp.target", ArgTypes.PLAYER_REF);
    @Nonnull
    private final OptionalArg worldArg =
        this.withOptionalArg("world", "myplugin.commands.tp.world", ArgTypes.WORLD);
    @Override
    protected void execute(...) {
        PlayerRef target = targetArg.get(context);
        // Kontrola zda byl volitelný argument zadán
        if (worldArg.provided(context)) {
            World targetWorld = worldArg.get(context);
            // Teleport do jiného světa
        } else {
            // Teleport ve stejném světě
        }
    }
}

Metody OptionalArg

| Metoda | Popis |
|--------|-------|
| provided(context) | Vrátí true pokud byl argument zadán |
| get(context) | Vrátí hodnotu (může být null) |

---

DefaultArg

Argument s výchozí hodnotou - nikdy není null.

public class EchoCommand extends CommandBase {
    @Nonnull
    private final RequiredArg textArg =
        this.withRequiredArg("text", "myplugin.commands.echo.text", ArgTypes.STRING);
    @Nonnull
    private final DefaultArg timesArg =
        this.withDefaultArg("times", "myplugin.commands.echo.times", ArgTypes.INTEGER, 1, "1");
    public EchoCommand() {
        super("echo", "myplugin.commands.echo.desc");
    }
    @Override
    protected void executeSync(@Nonnull CommandContext context) {
        String text = textArg.get(context);
        int times = timesArg.get(context);  // Nikdy null, výchozí je 1
        for (int i = 0; i < times; i++) {
            context.sendMessage(Message.raw(text));
        }
    }
}

Parametry withDefaultArg()

withDefaultArg(
    "name",           // Název argumentu
    "translation.key", // Klíč pro popis
    ArgTypes.INTEGER,  // Typ
    1,                 // Výchozí hodnota (Java objekt)
    "1"                // Výchozí hodnota (zobrazení v help)
)

---

FlagArg

Boolean flag argument.

public class ListCommand extends CommandBase {
    @Nonnull
    private final FlagArg onlineFlag =
        this.withFlagArg("online", "myplugin.commands.list.online");
    @Nonnull
    private final FlagArg verboseFlag =
        this.withFlagArg("verbose", "myplugin.commands.list.verbose");
    @Override
    protected void executeSync(@Nonnull CommandContext context) {
        boolean onlineOnly = onlineFlag.get(context);
        boolean verbose = verboseFlag.get(context);
        // /list --online --verbose
    }
}

---

ArgTypes

Vestavěné typy argumentů.

Základní Typy

| ArgType | Java typ | Příklad |
|---------|----------|---------|
| ArgTypes.STRING | String | "hello" |
| ArgTypes.INTEGER | Integer | 42 |
| ArgTypes.LONG | Long | 1000000 |
| ArgTypes.FLOAT | Float | 3.14 |
| ArgTypes.DOUBLE | Double | 3.14159 |
| ArgTypes.BOOLEAN | Boolean | true / false |

Herní Typy

| ArgType | Java typ | Popis |
|---------|----------|-------|
| ArgTypes.PLAYER_REF | PlayerRef | Online hráč |
| ArgTypes.WORLD | World | Svět |
| ArgTypes.VECTOR3D | Vector3d | 3D pozice |
| ArgTypes.VECTOR3I | Vector3i | 3D celočíselná pozice |

Příklad: Různé Typy

public class ComplexCommand extends AbstractPlayerCommand {
    // Hráč
    private final RequiredArg playerArg =
        this.withRequiredArg("player", "desc", ArgTypes.PLAYER_REF);
    // Svět
    private final OptionalArg worldArg =
        this.withOptionalArg("world", "desc", ArgTypes.WORLD);
    // Pozice
    private final OptionalArg posArg =
        this.withOptionalArg("position", "desc", ArgTypes.VECTOR3D);
    // Číslo
    private final DefaultArg countArg =
        this.withDefaultArg("count", "desc", ArgTypes.INTEGER, 1, "1");
    // Text
    private final RequiredArg messageArg =
        this.withRequiredArg("message", "desc", ArgTypes.STRING);
    @Override
    protected void execute(...) {
        PlayerRef player = playerArg.get(context);
        if (worldArg.provided(context)) {
            World world = worldArg.get(context);
        }
        if (posArg.provided(context)) {
            Vector3d pos = posArg.get(context);
        }
        int count = countArg.get(context);  // Nikdy null
        String message = messageArg.get(context);
    }
}

---

Validace Argumentů

Rozsah Čísel

// Vlastní validace v execute()
@Override
protected void execute(...) {
    int amount = amountArg.get(context);
    if (amount < 1 || amount > 64) {
        context.sendMessage(Message.raw("Množství musí být 1-64"));
        return;
    }
    // Pokračuj...
}

Spawn Index Validace (z SpawnCommand)

private static Transform resolveSpawn(
    CommandContext context,
    World world,
    PlayerRef playerRef,
    OptionalArg spawnIndexArg
) {
    ISpawnProvider spawnProvider = world.getWorldConfig().getSpawnProvider();
    if (spawnIndexArg.provided(context)) {
        int spawnIndex = spawnIndexArg.get(context);
        Transform[] spawnPoints = spawnProvider.getSpawnPoints();
        if (spawnIndex >= 0 && spawnIndex < spawnPoints.length) {
            return spawnPoints[spawnIndex];
        } else {
            int maxIndex = spawnPoints.length - 1;
            context.sendMessage(
                Message.translation("server.commands.spawn.indexNotFound")
                    .param("maxIndex", maxIndex)
            );
            throw new GeneralCommandException(
                Message.translation("server.commands.errors.spawnIndexOutOfRange")
                    .param("index", spawnIndex)
                    .param("maxIndex", maxIndex)
            );
        }
    } else {
        return spawnProvider.getSpawnPoint(world, playerRef.getUuid());
    }
}

---

Sender Handling

Kontrola typu odesílatele příkazu.

@Override
protected void executeSync(@Nonnull CommandContext context) {
    // Kontrola zda je odesílatel hráč
    if (!context.isPlayer()) {
        context.sendMessage(Message.raw("Tento příkaz je pouze pro hráče!"));
        return;
    }
    // Získání hráče
    Player player = context.senderAs(Player.class);
    PlayerRef playerRef = context.senderAsPlayerRef();
    // Další zpracování...
}

Metody CommandContext

| Metoda | Popis |
|--------|-------|
| isPlayer() | Je odesílatel hráč? |
| senderAs(Class) | Získej odesílatele jako typ |
| senderAsPlayerRef() | Získej PlayerRef |
| senderUUID() | UUID odesílatele |
| sendMessage(Message) | Pošli zprávu odesílateli |

---

Chybové Zprávy

Message.translation()

context.sendMessage(
    Message.translation("server.commands.errors.playerNotFound")
        .param("username", targetName)
);

Message.raw()

context.sendMessage(Message.raw("Jednoduchá zpráva"));

S barvou

context.sendMessage(
    Message.translation("server.commands.success")
        .color("#00FF00")
);

---

Permissions

public class AdminCommand extends CommandBase {
    public AdminCommand() {
        super("admin", "myplugin.commands.admin.desc");
        // Vyžaduj oprávnění
        this.requirePermission(HytalePermissions.fromCommand("admin"));
    }
}

HytalePermissions

// Z příkazu
HytalePermissions.fromCommand("spawn.self")
HytalePermissions.fromCommand("spawn.other")
HytalePermissions.fromCommand("warp.set")
// Vlastní
HytalePermissions.of("myplugin.admin")

---

Shrnutí

| Typ Argumentu | Povinný | Výchozí hodnota | Může být null |
|---------------|---------|-----------------|---------------|
| RequiredArg | Ano | - | Ne |
| OptionalArg | Ne | - | Ano |
| DefaultArg | Ne | Ano | Ne |
| FlagArg | Ne | false | Ne (boolean) |