Command Syntax

When a player types a command, the input goes through a pipeline before reaching your command’s execute() method:

Tokenization

The raw input string is split into tokens. By default, tokens are separated by spaces:

/give diamond_sword 5
-> ["give", "diamond_sword", "5"]

Quoted strings

Wrap text in double or single quotes to keep spaces in a single token:

/say "hello world"
-> ["say", "hello world"]

/say 'hello world'
-> ["say", "hello world"]

Unbalanced quotes produce a parse error.

Escape characters

Use backslash to escape special characters inside arguments. Only these six characters can be escaped:

Escape	Character
\"	Double quote
\'	Single quote
\\	Backslash
\,	Comma
\[	Open bracket
\]	Close bracket

Any other escape sequence is an error.

List syntax

Lists use brackets with comma-separated values:

/fill [Rock_Stone, Rock_Shale, Grass_Full]
-> ["fill", "[", "Rock_Stone", ",", "Rock_Shale", ",", "Grass_Full", "]"]

Brackets, commas, and values each become separate tokens internally. The parser context reassembles them into list arguments. Nested brackets are not allowed.

There is also an implicit list syntax — a comma after a positional value enters list mode:

/fill Rock_Stone, Rock_Shale

Lists are capped at 10 items. For multi-token types (like positions), each list item must have the same number of tokens.

Positional arguments

Positional arguments are consumed left-to-right in the order they were registered on the command. They appear before any --named arguments:

/greet Alice          -> name="Alice"
/tp 10 64 200         -> x=10, y=64, z=200

Some argument types consume multiple tokens. Positions consume 3 (<x> <y> <z>), ranges consume 2 (<min> <max>):

/tp Alice 10 64 200
    ───── ────────
    1 token   3 tokens (one position arg)

Named arguments

Named arguments use --name value or --name=value syntax. They can appear in any order after the positional arguments:

/give diamond_sword --quantity=5
/give diamond_sword --quantity 5
/npc spawn Wolf --count=3 --radius=10

Flags

Flags are named arguments with no value — their presence means true, absence means false:

/entity dump --json
/npc freeze --all

Abbreviation

Named arguments can be abbreviated to any unambiguous prefix. If a command has --radius and --rotation, then:

• --radiu, --radi, --rad all resolve to --radius
• --rot, --rota all resolve to --rotation
• --r and --ro are ambiguous and produce an error

Special flags

Two flags are handled by the command system itself:

• --help or --? — shows the command’s usage information
• --confirm — satisfies the confirmation requirement for commands that use requiresConfirmation = true

Relative coordinates

Position arguments support prefix modifiers for relative and special coordinate modes:

Prefix	Meaning	Example
~	Relative to player position	~5 = player pos + 5, ~ = player pos + 0
_	Surface height at that XZ	_ = top of terrain + 1
c	Chunk scale (value × 32)	c2 = block position 64

Prefixes combine left-to-right: ~c2 means relative + chunk scale.

/tp ~ ~5 ~             # 5 blocks above current position
/tp ~10 _ ~-10          # 10 blocks east, surface height, 10 blocks south
/tp c2 64 c3            # block position (64, 64, 96)

These prefixes work with RELATIVE_BLOCK_POSITION, RELATIVE_POSITION, RELATIVE_INT_COORD, RELATIVE_FLOAT, and RELATIVE_INTEGER argument types.

Dispatch order

After tokenization and argument classification, the command system determines which command to execute:

1. First positional argument matches a subcommand name or alias -> execute that subcommand
2. No subcommand match, but a usage variant matches the positional parameter count -> execute that variant
3. No match -> parent command executes (typically shows usage for command collections)

See Usage Variants for details on how variants work.

Code location

Package: com.hypixel.hytale.server.core.command.system

• Tokenizer — raw input to token list
• ParserContext — token classification (positional vs named)
• AbstractCommand.acceptCall0 — dispatch and argument processing
• CommandManager — entry point, orchestrates the pipeline