---
title: Argument Types
type: docs
weight: 2
---

Hytale provides a comprehensive set of argument types through the `ArgTypes` class. These types handle parsing, validation, and tab completion automatically, ensuring a consistent and user-friendly command experience.

**Package:** `com.hypixel.hytale.server.core.command.system.arguments.types`

{{< cards cols="3" >}}
  {{< card link="#primitive-types" title="Primitives" subtitle="Boolean, Integer, Float, Double, String" icon="hashtag" >}}
  {{< card link="#player-and-entity-types" title="Player & Entity" subtitle="PlayerRef, UUID, EntityId" icon="user" >}}
  {{< card link="#asset-types" title="Assets" subtitle="Items, Blocks, Models, Effects" icon="cube" >}}
  {{< card link="#position-types" title="Positions" subtitle="Absolute and relative coordinates" icon="map" >}}
  {{< card link="#vector-types" title="Vectors" subtitle="2D/3D vectors and rotations" icon="arrows-expand" >}}
  {{< card link="#special-types" title="Special" subtitle="Colors, Patterns, Ranges" icon="sparkles" >}}
{{< /cards >}}

---

## Primitive Types

Basic data types for simple values. These are the foundation of most command arguments.

{{< tabs items="Overview,Examples,Methods" >}}
{{< tab >}}

| Type | Java Type | Description | Input Examples |
|------|-----------|-------------|----------------|
| `ArgTypes.BOOLEAN` | `Boolean` | True or false value | `true`, `false` |
| `ArgTypes.INTEGER` | `Integer` | 32-bit whole numbers | `-1`, `0`, `56346`, `2147483647` |
| `ArgTypes.FLOAT` | `Float` | Single precision decimals | `3.14159`, `-2.5`, `7` |
| `ArgTypes.DOUBLE` | `Double` | Double precision decimals | `-3.14`, `0.0`, `3.141596` |
| `ArgTypes.STRING` | `String` | Single word text | `hello`, `world`, `test123` |

{{< /tab >}}
{{< tab >}}

```java
public class MathCommand extends AbstractCommand {
    private final RequiredArg<Integer> countArg;
    private final RequiredArg<Double> multiplierArg;
    private final RequiredArg<Boolean> verboseArg;
    private final OptionalArg<String> labelArg;

    public MathCommand() {
        super("math", "Perform mathematical operations");
        countArg = withRequiredArg("count", "Number of iterations", ArgTypes.INTEGER);
        multiplierArg = withRequiredArg("multiplier", "Multiplication factor", ArgTypes.DOUBLE);
        verboseArg = withRequiredArg("verbose", "Show detailed output", ArgTypes.BOOLEAN);
        labelArg = withOptionalArg("label", "Optional label", ArgTypes.STRING);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        int count = context.get(countArg);
        double mult = context.get(multiplierArg);
        boolean verbose = context.get(verboseArg);
        String label = context.get(labelArg); // null if not provided

        double result = count * mult;

        if (verbose) {
            String output = (label != null ? label + ": " : "") +
                count + " × " + mult + " = " + result;
            context.sender().sendMessage(Message.raw(output));
        }

        return null;
    }
}
```

**Usage:** `/math 5 2.5 true --label result` → `result: 5 × 2.5 = 12.5`

{{< /tab >}}
{{< tab >}}

**Common methods for primitive arguments:**

| Method | Description |
|--------|-------------|
| `withRequiredArg(name, desc, type)` | Creates a required argument |
| `withOptionalArg(name, desc, type)` | Creates an optional argument |
| `context.get(arg)` | Gets the parsed value |
| `context.provided(arg)` | Checks if optional arg was provided |

{{< /tab >}}
{{< /tabs >}}

---

## Player and Entity Types

Types for referencing players and entities in the game world.

{{< tabs items="Overview,PlayerRef,Entity,UUID" >}}
{{< tab >}}

| Type | Java Type | Description | Input Examples |
|------|-----------|-------------|----------------|
| `ArgTypes.PLAYER_REF` | `PlayerRef` | Online player reference | `john_doe`, `user123` |
| `ArgTypes.PLAYER_UUID` | `UUID` | Player UUID (by name or UUID) | `john_doe`, `550e8400-e29b-...` |
| `ArgTypes.UUID` | `UUID` | Any valid UUID | `550e8400-e29b-41d4-a716-...` |
| `ArgTypes.ENTITY_ID` | `UUID` (wrapped) | Entity by UUID | Entity UUID |

{{< callout type="warning" >}}
**PLAYER_REF** only matches currently online players and returns a `PlayerRef`. **PLAYER_UUID** can match by name or UUID and returns a `UUID` directly.
{{< /callout >}}

{{< /tab >}}
{{< tab >}}

{{< callout type="info" >}}
`PlayerRef` provides player identity (`getUsername()`, `getUuid()`) and ECS access via `getReference()`. To check if a player is online, verify `getReference()` returns a valid reference.
{{< /callout >}}

```java
public class TeleportCommand extends AbstractCommand {
    private final RequiredArg<PlayerRef> targetArg;
    private final OptionalArg<PlayerRef> destinationArg;

    public TeleportCommand() {
        super("tp", "Teleport players");
        targetArg = withRequiredArg("target", "Player to teleport", ArgTypes.PLAYER_REF);
        destinationArg = withOptionalArg("destination", "Destination player", ArgTypes.PLAYER_REF);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        PlayerRef targetRef = context.get(targetArg);

        // Check if player is online via ECS reference
        Ref<EntityStore> targetEntity = targetRef.getReference();
        if (targetEntity == null || !targetEntity.isValid()) {
            context.sendMessage(Message.raw("Player is no longer online!"));
            return null;
        }

        if (context.provided(destinationArg)) {
            PlayerRef destRef = context.get(destinationArg);
            Ref<EntityStore> destEntity = destRef.getReference();
            if (destEntity != null && destEntity.isValid()) {
                // Teleport target to destination player using ECS
                // Access TransformComponent from both entities for teleportation
            }
        }

        return null;
    }
}
```

**Usage:** `/tp john_doe --destination steve` → Teleports john_doe to steve

{{< /tab >}}
{{< tab >}}

```java
public class EntityInfoCommand extends AbstractCommand {
    private final RequiredArg<UUID> entityArg;

    public EntityInfoCommand() {
        super("entityinfo", "Get entity information");
        entityArg = withRequiredArg("entity", "Entity UUID", ArgTypes.UUID);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        UUID entityId = context.get(entityArg);

        // Find entity in worlds
        for (World world : Universe.get().getWorlds().values()) {
            // Search for entity by UUID
            // Entity lookup depends on world API
        }

        context.sender().sendMessage(Message.raw("Entity lookup complete"));
        return null;
    }
}
```

{{< /tab >}}
{{< tab >}}

```java
public class UuidCommand extends AbstractCommand {
    private final RequiredArg<UUID> uuidArg;

    public UuidCommand() {
        super("uuid", "Parse and display UUID");
        uuidArg = withRequiredArg("uuid", "UUID to parse", ArgTypes.UUID);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        UUID uuid = context.get(uuidArg);
        context.sender().sendMessage(Message.raw(
            "UUID: " + uuid.toString() + "\nVersion: " + uuid.version()
        ));
        return null;
    }
}
```

**Valid UUID formats:**
- Full: `550e8400-e29b-41d4-a716-446655440000`

{{< /tab >}}
{{< /tabs >}}

---

## World Types

Types for referencing game worlds.

{{< tabs items="Overview,Example" >}}
{{< tab >}}

| Type | Java Type | Description | Input Examples |
|------|-----------|-------------|----------------|
| `ArgTypes.WORLD` | `World` | World by name | `default`, `creative`, `pvp_arena` |

{{< callout type="info" >}}
World names are case-insensitive and support tab completion for all loaded worlds.
{{< /callout >}}

{{< /tab >}}
{{< tab >}}

```java
public class WorldTeleportCommand extends AbstractCommand {
    private final RequiredArg<World> worldArg;
    private final OptionalArg<RelativeDoublePosition> positionArg;

    public WorldTeleportCommand() {
        super("wtp", "Teleport to another world");
        worldArg = withRequiredArg("world", "Destination world", ArgTypes.WORLD);
        positionArg = withOptionalArg("position", "Spawn position", ArgTypes.RELATIVE_POSITION);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        if (!(context.sender() instanceof Player player)) {
            context.sender().sendMessage(Message.raw("Only players can use this command!"));
            return null;
        }

        World targetWorld = context.get(worldArg);

        Vector3d spawnPos;
        if (context.provided(positionArg)) {
            spawnPos = context.get(positionArg).resolve(player.getPosition());
        } else {
            spawnPos = targetWorld.getSpawnPosition();
        }

        player.teleport(targetWorld, spawnPos);
        player.sendMessage(Message.raw("Teleported to " + targetWorld.getName()));

        return null;
    }
}
```

**Usage:** `/wtp creative` or `/wtp creative 100 64 200`

{{< /tab >}}
{{< /tabs >}}

---

## Asset Types

Types for referencing game assets loaded from data packs.

{{< tabs items="Overview,Items,Blocks,Effects,Other" >}}
{{< tab >}}

| Type | Java Type | Description |
|------|-----------|-------------|
| `ArgTypes.ITEM_ASSET` | `Item` | Item definition |
| `ArgTypes.BLOCK_TYPE_ASSET` | `BlockType` | Block type definition |
| `ArgTypes.MODEL_ASSET` | `Model` | 3D model asset |
| `ArgTypes.WEATHER_ASSET` | `Weather` | Weather configuration |
| `ArgTypes.EFFECT_ASSET` | `EntityEffect` | Entity effect (buffs/debuffs) |
| `ArgTypes.ENVIRONMENT_ASSET` | `Environment` | Environment settings |
| `ArgTypes.PARTICLE_SYSTEM` | `ParticleSystem` | Particle system definition |
| `ArgTypes.SOUND_EVENT_ASSET` | `SoundEvent` | Sound event |
| `ArgTypes.AMBIENCE_FX_ASSET` | `AmbienceFX` | Ambient sound/effect |
| `ArgTypes.INTERACTION_ASSET` | `Interaction` | Interaction definition |

{{< callout type="info" >}}
Asset identifiers use the format `namespace:path` (e.g., `hytale:sword_iron`). Tab completion lists all available assets.
{{< /callout >}}

{{< /tab >}}
{{< tab >}}

```java
public class GiveCommand extends AbstractCommand {
    private final RequiredArg<Item> itemArg;
    private final OptionalArg<Integer> amountArg;
    private final OptionalArg<PlayerRef> targetArg;

    public GiveCommand() {
        super("give", "Give items to players");
        itemArg = withRequiredArg("item", "Item to give", ArgTypes.ITEM_ASSET);
        amountArg = withOptionalArg("amount", "Stack size", ArgTypes.INTEGER);
        targetArg = withOptionalArg("player", "Target player", ArgTypes.PLAYER_REF);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        Item item = context.get(itemArg);
        int amount = context.provided(amountArg) ? context.get(amountArg) : 1;

        // Get target player - use PlayerRef for identity, sender for direct access
        String targetName;
        if (context.provided(targetArg)) {
            PlayerRef ref = context.get(targetArg);
            targetName = ref.getUsername();
            // Use ref.getReference() for ECS operations
        } else if (context.sender() instanceof Player p) {
            targetName = p.getDisplayName();
            // p.getInventory() for inventory operations
        } else {
            context.sendMessage(Message.raw("Specify a player!"));
            return null;
        }

        // Create ItemStack and add to inventory
        ItemStack stack = new ItemStack(item.getId(), amount);
        // Add to player inventory via ECS...

        context.sendMessage(Message.raw(
            "Gave " + amount + "x " + item.getId() + " to " + targetName
        ));

        return null;
    }
}
```

**Usage:** `/give hytale:sword_iron 1 john_doe`

{{< /tab >}}
{{< tab >}}

```java
public class SetBlockCommand extends AbstractCommand {
    private final RequiredArg<BlockType> blockArg;
    private final RequiredArg<RelativeBlockPosition> positionArg;

    public SetBlockCommand() {
        super("setblock", "Set a block at position");
        blockArg = withRequiredArg("block", "Block type", ArgTypes.BLOCK_TYPE_ASSET);
        positionArg = withRequiredArg("position", "Target position", ArgTypes.RELATIVE_BLOCK_POSITION);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        if (!(context.sender() instanceof Player player)) {
            return null;
        }

        BlockType blockType = context.get(blockArg);
        Vector3i pos = context.get(positionArg).resolve(player.getBlockPosition());

        player.getWorld().setBlock(pos, blockType);

        context.sender().sendMessage(
            Message.raw("Set block to " + blockType.getIdentifier() + " at " + pos)
        );

        return null;
    }
}
```

**Usage:** `/setblock hytale:rock_stone ~ ~-1 ~`

{{< /tab >}}
{{< tab >}}

```java
public class EffectCommand extends AbstractCommand {
    private final RequiredArg<EntityEffect> effectArg;
    private final OptionalArg<Integer> durationArg;
    private final OptionalArg<Integer> amplifierArg;

    public EffectCommand() {
        super("effect", "Apply effect to player");
        effectArg = withRequiredArg("effect", "Effect to apply", ArgTypes.EFFECT_ASSET);
        durationArg = withOptionalArg("duration", "Duration in ticks", ArgTypes.INTEGER);
        amplifierArg = withOptionalArg("amplifier", "Effect level", ArgTypes.INTEGER);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        if (!(context.sender() instanceof Player player)) {
            return null;
        }

        EntityEffect effect = context.get(effectArg);
        int duration = context.provided(durationArg) ? context.get(durationArg) : 600; // 30 seconds
        int amplifier = context.provided(amplifierArg) ? context.get(amplifierArg) : 0;

        player.addEffect(effect, duration, amplifier);

        return null;
    }
}
```

{{< /tab >}}
{{< tab >}}

```java
public class ParticleCommand extends AbstractCommand {
    private final RequiredArg<ParticleSystem> particleArg;
    private final OptionalArg<RelativeDoublePosition> positionArg;

    public ParticleCommand() {
        super("particle", "Spawn particle effect");
        particleArg = withRequiredArg("particle", "Particle system", ArgTypes.PARTICLE_SYSTEM);
        positionArg = withOptionalArg("position", "Spawn position", ArgTypes.RELATIVE_POSITION);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        if (!(context.sender() instanceof Player player)) {
            return null;
        }

        ParticleSystem particle = context.get(particleArg);
        Vector3d pos = context.provided(positionArg)
            ? context.get(positionArg).resolve(player.getPosition())
            : player.getPosition();

        player.getWorld().spawnParticle(particle, pos);

        return null;
    }
}
```

**Usage:** `/particle hytale:explosion ~ ~2 ~`

{{< /tab >}}
{{< /tabs >}}

---

## Position Types

Types for specifying locations in the game world. Supports both absolute and relative coordinates.

### Relative Notation

Positions support relative coordinates using the `~` prefix:

| Syntax | Meaning | Example |
|--------|---------|---------|
| `100` | Absolute value 100 | Exact coordinate |
| `~` | Current position | Same as `~0` |
| `~5` | Current + 5 | 5 blocks in positive direction |
| `~-5` | Current - 5 | 5 blocks in negative direction |

{{< tabs items="3D Positions,Block Positions,Single Coords" >}}
{{< tab >}}

| Type | Java Type | Precision | Input Examples |
|------|-----------|-----------|----------------|
| `ArgTypes.RELATIVE_POSITION` | `RelativeDoublePosition` | Double (sub-block) | `100.5 64.0 -200.5`, `~ ~ ~`, `~5 ~10 ~-5` |
| `ArgTypes.RELATIVE_BLOCK_POSITION` | `RelativeIntPosition` | Integer (block) | `100 64 -200`, `~ ~ ~`, `~5 ~10 ~-5` |
| `ArgTypes.RELATIVE_CHUNK_POSITION` | `RelativeChunkPosition` | Chunk (X, Z) | `5 10`, `~2 ~-3` |

```java
public class TeleportPosCommand extends AbstractCommand {
    private final RequiredArg<RelativeDoublePosition> posArg;

    public TeleportPosCommand() {
        super("tppos", "Teleport to coordinates");
        posArg = withRequiredArg("position", "Target position", ArgTypes.RELATIVE_POSITION);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        if (!(context.sender() instanceof Player player)) {
            return null;
        }

        RelativeDoublePosition relPos = context.get(posArg);

        // Resolve relative coordinates based on player's current position
        Vector3d absolutePos = relPos.resolve(player.getPosition());

        player.teleport(absolutePos);
        player.sendMessage(Message.raw("Teleported to " + absolutePos));

        return null;
    }
}
```

**Usage Examples:**
- `/tppos 100 64 200` → Teleport to exact coordinates
- `/tppos ~ ~10 ~` → Teleport 10 blocks up
- `/tppos ~5 ~ ~-5` → Teleport 5 blocks east and 5 blocks north

{{< /tab >}}
{{< tab >}}

```java
public class FillCommand extends AbstractCommand {
    private final RequiredArg<RelativeIntPosition> pos1Arg;
    private final RequiredArg<RelativeIntPosition> pos2Arg;
    private final RequiredArg<BlockType> blockArg;

    public FillCommand() {
        super("fill", "Fill region with blocks");
        pos1Arg = withRequiredArg("from", "First corner", ArgTypes.RELATIVE_BLOCK_POSITION);
        pos2Arg = withRequiredArg("to", "Second corner", ArgTypes.RELATIVE_BLOCK_POSITION);
        blockArg = withRequiredArg("block", "Block type", ArgTypes.BLOCK_TYPE_ASSET);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        if (!(context.sender() instanceof Player player)) {
            return null;
        }

        Vector3i playerPos = player.getBlockPosition();
        Vector3i from = context.get(pos1Arg).resolve(playerPos);
        Vector3i to = context.get(pos2Arg).resolve(playerPos);
        BlockType block = context.get(blockArg);

        int count = 0;
        World world = player.getWorld();

        int minX = Math.min(from.x(), to.x());
        int maxX = Math.max(from.x(), to.x());
        int minY = Math.min(from.y(), to.y());
        int maxY = Math.max(from.y(), to.y());
        int minZ = Math.min(from.z(), to.z());
        int maxZ = Math.max(from.z(), to.z());

        for (int x = minX; x <= maxX; x++) {
            for (int y = minY; y <= maxY; y++) {
                for (int z = minZ; z <= maxZ; z++) {
                    world.setBlock(new Vector3i(x, y, z), block);
                    count++;
                }
            }
        }

        player.sendMessage(Message.raw("Filled " + count + " blocks"));
        return null;
    }
}
```

**Usage:** `/fill ~-5 ~ ~-5 ~5 ~10 ~5 hytale:rock_stone` → Create a 11x11x11 cube around player

{{< /tab >}}
{{< tab >}}

| Type | Java Type | Description | Input Examples |
|------|-----------|-------------|----------------|
| `ArgTypes.RELATIVE_DOUBLE_COORD` | `Coord` | Single coordinate (double) | `5.0`, `~-2.3`, `~` |
| `ArgTypes.RELATIVE_INT_COORD` | `IntCoord` | Single coordinate (integer) | `5`, `~-2`, `~` |
| `ArgTypes.RELATIVE_INTEGER` | `RelativeInteger` | Relative integer value | `5`, `~-2` |
| `ArgTypes.RELATIVE_FLOAT` | `RelativeFloat` | Relative float value | `90.0`, `~-45.5`, `~` |

```java
public class SetYCommand extends AbstractCommand {
    private final RequiredArg<Coord> yArg;

    public SetYCommand() {
        super("sety", "Teleport to Y level");
        yArg = withRequiredArg("y", "Y coordinate", ArgTypes.RELATIVE_DOUBLE_COORD);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        if (!(context.sender() instanceof Player player)) {
            return null;
        }

        Coord relY = context.get(yArg);
        // Coord.resolveXZ() or Coord.resolveYAtWorldCoords() for resolution
        double newY = relY.resolveXZ(player.getPosition().y);

        player.teleport(new Vector3d(
            player.getPosition().x(),
            newY,
            player.getPosition().z()
        ));

        return null;
    }
}
```

**Usage:** `/sety 64` or `/sety ~10`

{{< /tab >}}
{{< /tabs >}}

---

## Vector Types

Types for directional and rotational data.

{{< tabs items="Overview,Examples" >}}
{{< tab >}}

| Type | Java Type | Components | Input Examples |
|------|-----------|------------|----------------|
| `ArgTypes.VECTOR2I` | `Vector2i` | X, Z (2D integer) | `124 232`, `5 -3` |
| `ArgTypes.VECTOR3I` | `Vector3i` | X, Y, Z (3D integer) | `124 232 234` |
| `ArgTypes.RELATIVE_VECTOR3I` | `RelativeVector3i` | X, Y, Z (relative 3D) | `124 ~232 234`, `~5 0 ~-3` |
| `ArgTypes.ROTATION` | `Vector3f` | Pitch, Yaw, Roll | `45.0 90.0 0.0` |

{{< /tab >}}
{{< tab >}}

```java
public class LookCommand extends AbstractCommand {
    private final RequiredArg<Vector3f> rotationArg;

    public LookCommand() {
        super("look", "Set player rotation");
        rotationArg = withRequiredArg("rotation", "Pitch Yaw Roll", ArgTypes.ROTATION);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        if (!(context.sender() instanceof Player player)) {
            return null;
        }

        Vector3f rotation = context.get(rotationArg);
        // rotation.x = pitch, rotation.y = yaw, rotation.z = roll

        player.setRotation(rotation);
        player.sendMessage(Message.raw(
            "Rotation set to Pitch: " + rotation.x +
            ", Yaw: " + rotation.y +
            ", Roll: " + rotation.z
        ));

        return null;
    }
}
```

**Rotation values:**
- **Pitch:** -90 (up) to 90 (down)
- **Yaw:** 0-360 degrees (north = 0, east = 90, south = 180, west = 270)
- **Roll:** Usually 0 for players

{{< /tab >}}
{{< /tabs >}}

---

## Range Types

Types for specifying value ranges.

{{< tabs items="Overview,Example" >}}
{{< tab >}}

| Type | Java Type | Description | Input Examples |
|------|-----------|-------------|----------------|
| `ArgTypes.INT_RANGE` | `Pair<Integer, Integer>` | Integer range (min, max) | `-2 8`, `5 5`, `1 100` |
| `ArgTypes.RELATIVE_INT_RANGE` | `Pair<RelativeInt, RelativeInt>` | Relative integer range | `~-2 ~8`, `~5 ~5` |

{{< /tab >}}
{{< tab >}}

```java
public class RandomCommand extends AbstractCommand {
    private final RequiredArg<Pair<Integer, Integer>> rangeArg;

    public RandomCommand() {
        super("random", "Generate random number in range");
        rangeArg = withRequiredArg("range", "Min and max values", ArgTypes.INT_RANGE);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        Pair<Integer, Integer> range = context.get(rangeArg);
        int min = range.left();
        int max = range.right();

        if (min > max) {
            context.sender().sendMessage(Message.raw("Min must be less than max!"));
            return null;
        }

        int result = min + (int)(Math.random() * (max - min + 1));

        context.sender().sendMessage(
            Message.raw("Random number between " + min + " and " + max + ": " + result)
        );

        return null;
    }
}
```

**Usage:** `/random 1 100` → Random number between 1 and 100

{{< /tab >}}
{{< /tabs >}}

---

## Special Types

Specialized types for specific game mechanics.

{{< tabs items="Color,Game Mode,Tick Rate,Block Patterns" >}}
{{< tab >}}

| Type | Java Type | Description | Input Examples |
|------|-----------|-------------|----------------|
| `ArgTypes.COLOR` | `Integer` | ARGB color value | `#FF0000`, `#80FF0000`, `16711680`, `0xFF0000` |

**Supported formats:**
- Hex RGB: `#FF0000` (red)
- Hex ARGB: `#80FF0000` (50% transparent red)
- Decimal: `16711680` (red)
- Hex literal: `0xFF0000` (red)

```java
public class ColorCommand extends AbstractCommand {
    private final RequiredArg<Integer> colorArg;

    public ColorCommand() {
        super("color", "Set display color");
        colorArg = withRequiredArg("color", "Color value", ArgTypes.COLOR);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        int color = context.get(colorArg);

        int alpha = (color >> 24) & 0xFF;
        int red = (color >> 16) & 0xFF;
        int green = (color >> 8) & 0xFF;
        int blue = color & 0xFF;

        context.sender().sendMessage(
            Message.raw("Color: ARGB(" + alpha + ", " + red + ", " + green + ", " + blue + ")")
        );

        return null;
    }
}
```

{{< /tab >}}
{{< tab >}}

| Type | Java Type | Description | Input Examples |
|------|-----------|-------------|----------------|
| `ArgTypes.GAME_MODE` | `GameMode` | Player game mode | `Adventure`, `Creative` |

{{< callout type="info" >}}
Hytale currently supports two game modes: **Adventure** and **Creative**.
{{< /callout >}}

```java
public class GameModeCommand extends AbstractCommand {
    private final RequiredArg<GameMode> modeArg;
    private final OptionalArg<PlayerRef> playerArg;

    public GameModeCommand() {
        super("gamemode", "Change game mode");
        modeArg = withRequiredArg("mode", "Game mode", ArgTypes.GAME_MODE);
        playerArg = withOptionalArg("player", "Target player", ArgTypes.PLAYER_REF);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        GameMode mode = context.get(modeArg);

        // Get target player name
        String targetName;
        if (context.provided(playerArg)) {
            PlayerRef ref = context.get(playerArg);
            targetName = ref.getUsername();
            // Use ref.getReference() for ECS game mode operations
        } else if (context.sender() instanceof Player p) {
            targetName = p.getDisplayName();
            // Use Player.setGameMode() static method for game mode changes
        } else {
            context.sendMessage(Message.raw("Specify a player!"));
            return null;
        }

        // Set game mode using Player.setGameMode() static method with ECS ref
        context.sendMessage(Message.raw("Game mode changed to " + mode.name() + " for " + targetName));

        return null;
    }
}
```

**Usage:** `/gamemode Creative` or `/gamemode Adventure --player john_doe`

{{< /tab >}}
{{< tab >}}

| Type | Java Type | Description | Input Examples |
|------|-----------|-------------|----------------|
| `ArgTypes.TICK_RATE` | `Integer` | Tick rate in TPS | `30tps`, `33ms`, `60` |

**Supported formats:**
- TPS (ticks per second): `30tps`, `60tps`
- Milliseconds per tick: `33ms`, `16ms` (converted to TPS)
- Numeric TPS: `30`, `60`

{{< callout type="info" >}}
`TICK_RATE` returns an `Integer` representing the ticks per second (TPS). Millisecond input is automatically converted to TPS.
{{< /callout >}}

```java
public class TickRateCommand extends AbstractCommand {
    private final RequiredArg<Integer> rateArg;

    public TickRateCommand() {
        super("tickrate", "Set world tick rate");
        rateArg = withRequiredArg("rate", "Tick rate", ArgTypes.TICK_RATE);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        if (!(context.sender() instanceof Player player)) {
            return null;
        }

        int tps = context.get(rateArg);  // Returns Integer (TPS)
        // Set tick rate on world...

        player.sendMessage(Message.raw("Tick rate set to " + tps + " TPS"));

        return null;
    }
}
```

{{< /tab >}}
{{< tab >}}

| Type | Java Type | Description | Input Examples |
|------|-----------|-------------|----------------|
| `ArgTypes.BLOCK_PATTERN` | `BlockPattern` | Weighted block selection | `[Rock_Stone]`, `[20%Rock_Stone, 80%Rock_Shale]` |
| `ArgTypes.BLOCK_MASK` | `BlockMask` | Block filter | `[!Fluid_Water, !^Fluid_Lava]` |

**Block Pattern Syntax:**
- Single block: `[Rock_Stone]`
- Weighted: `[20%Rock_Stone, 80%Rock_Shale]`
- Equal weights: `[Rock_Stone, Rock_Shale]` (50% each)

**Block Mask Syntax:**
- Include: `[Rock_Stone]`
- Exclude: `[!Rock_Stone]`
- Exclude tag: `[!^Fluid]` (excludes all blocks with "Fluid" tag)

```java
public class FillPatternCommand extends AbstractCommand {
    private final RequiredArg<RelativeIntPosition> pos1Arg;
    private final RequiredArg<RelativeIntPosition> pos2Arg;
    private final RequiredArg<BlockPattern> patternArg;
    private final OptionalArg<BlockMask> maskArg;

    public FillPatternCommand() {
        super("fillpattern", "Fill with pattern");
        pos1Arg = withRequiredArg("from", "First corner", ArgTypes.RELATIVE_BLOCK_POSITION);
        pos2Arg = withRequiredArg("to", "Second corner", ArgTypes.RELATIVE_BLOCK_POSITION);
        patternArg = withRequiredArg("pattern", "Block pattern", ArgTypes.BLOCK_PATTERN);
        maskArg = withOptionalArg("mask", "Replace mask", ArgTypes.BLOCK_MASK);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        // Implementation using weighted random selection from pattern
        // Only replace blocks matching mask if provided
        return null;
    }
}
```

**Usage:** `/fillpattern ~-5 ~ ~-5 ~5 ~5 ~5 [30%Rock_Stone, 70%Rock_Shale]`

{{< /tab >}}
{{< /tabs >}}

---

## Custom Argument Types

### Creating Enum Arguments

Use `ArgTypes.forEnum()` to create arguments for custom enums with automatic tab completion:

```java
public enum Difficulty {
    EASY, NORMAL, HARD, EXTREME
}

public class DifficultyCommand extends AbstractCommand {
    private final RequiredArg<Difficulty> difficultyArg;

    public DifficultyCommand() {
        super("difficulty", "Set server difficulty");
        difficultyArg = withRequiredArg(
            "level",
            "Difficulty level",
            ArgTypes.forEnum("Difficulty", Difficulty.class)
        );
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        Difficulty level = context.get(difficultyArg);
        // Apply difficulty setting
        context.sender().sendMessage(
            Message.raw("Difficulty set to " + level.name())
        );
        return null;
    }
}
```

### List Arguments

Create list arguments for any type:

```java
public class MultiTeleportCommand extends AbstractCommand {
    private final RequiredArg<List<PlayerRef>> playersArg;
    private final RequiredArg<RelativeDoublePosition> positionArg;

    public MultiTeleportCommand() {
        super("multitp", "Teleport multiple players");
        playersArg = withListRequiredArg("players", "Target players", ArgTypes.PLAYER_REF);
        positionArg = withRequiredArg("position", "Destination", ArgTypes.RELATIVE_POSITION);
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        List<PlayerRef> playerRefs = context.get(playersArg);
        RelativeDoublePosition relPos = context.get(positionArg);

        for (PlayerRef ref : playerRefs) {
            // Use getReference() to access ECS entity
            Ref<EntityStore> entityRef = ref.getReference();
            if (entityRef != null && entityRef.isValid()) {
                // Access TransformComponent for position/teleportation
                // Vector3d pos = relPos.resolve(currentPosition);
                // Set new position via ECS
            }
        }

        context.sendMessage(
            Message.raw("Teleported " + playerRefs.size() + " players")
        );

        return null;
    }
}
```

**Usage:** `/multitp [player1, player2, player3] 100 64 200`

{{< callout type="info" >}}
List arguments use square bracket syntax: `[item1, item2, item3]`. Each item is parsed according to the base argument type.
{{< /callout >}}

---

## Argument Validation

Arguments are automatically validated during parsing. For custom validation, use the `validate()` method:

```java
public class AgeCommand extends AbstractCommand {
    private final RequiredArg<Integer> ageArg;

    public AgeCommand() {
        super("setage", "Set player age");
        ageArg = withRequiredArg("age", "Age value (1-120)", ArgTypes.INTEGER)
            .validate(age -> {
                if (age < 1 || age > 120) {
                    throw new CommandException("Age must be between 1 and 120");
                }
            });
    }
}
```

---

## Summary Reference

{{< details title="Complete ArgTypes Reference" >}}

| Category | Type | Java Type |
|----------|------|-----------|
| **Primitive** | `BOOLEAN` | `Boolean` |
| | `INTEGER` | `Integer` |
| | `FLOAT` | `Float` |
| | `DOUBLE` | `Double` |
| | `STRING` | `String` |
| **Player/Entity** | `PLAYER_REF` | `PlayerRef` |
| | `PLAYER_UUID` | `UUID` |
| | `UUID` | `UUID` |
| | `ENTITY_ID` | `UUID` (wrapped) |
| **World** | `WORLD` | `World` |
| **Assets** | `ITEM_ASSET` | `Item` |
| | `BLOCK_TYPE_ASSET` | `BlockType` |
| | `MODEL_ASSET` | `ModelAsset` |
| | `WEATHER_ASSET` | `Weather` |
| | `EFFECT_ASSET` | `EntityEffect` |
| | `ENVIRONMENT_ASSET` | `Environment` |
| | `PARTICLE_SYSTEM` | `ParticleSystem` |
| | `SOUND_EVENT_ASSET` | `SoundEvent` |
| | `AMBIENCE_FX_ASSET` | `AmbienceFX` |
| | `INTERACTION_ASSET` | `Interaction` |
| | `ROOT_INTERACTION_ASSET` | `RootInteraction` |
| **Position** | `RELATIVE_POSITION` | `RelativeDoublePosition` |
| | `RELATIVE_BLOCK_POSITION` | `RelativeIntPosition` |
| | `RELATIVE_CHUNK_POSITION` | `RelativeChunkPosition` |
| | `RELATIVE_DOUBLE_COORD` | `Coord` |
| | `RELATIVE_INT_COORD` | `IntCoord` |
| | `RELATIVE_INTEGER` | `RelativeInteger` |
| | `RELATIVE_FLOAT` | `RelativeFloat` |
| **Vector** | `VECTOR2I` | `Vector2i` |
| | `VECTOR3I` | `Vector3i` |
| | `RELATIVE_VECTOR3I` | `RelativeVector3i` |
| | `ROTATION` | `Vector3f` |
| **Range** | `INT_RANGE` | `Pair<Integer, Integer>` |
| | `RELATIVE_INT_RANGE` | `RelativeIntegerRange` |
| **Special** | `COLOR` | `Integer` |
| | `GAME_MODE` | `GameMode` (Adventure, Creative) |
| | `SOUND_CATEGORY` | `SoundCategory` |
| | `TICK_RATE` | `Integer` (TPS) |
| | `BLOCK_PATTERN` | `BlockPattern` |
| | `BLOCK_MASK` | `BlockMask` |
| **Advanced** | `HITBOX_COLLISION_CONFIG` | `HitboxCollisionConfig` |
| | `REPULSION_CONFIG` | `RepulsionConfig` |
| | `INTEGER_COMPARISON_OPERATOR` | `IntegerComparisonOperator` |
| | `INTEGER_OPERATION` | `IntegerOperation` |

{{< /details >}}
