Skip to content

03-command-system.md

Latest commit

 

History

History
232 lines (179 loc) · 7.95 KB

03-command-system.md

File metadata and controls

232 lines (179 loc) · 7.95 KB

Command System

Architecture

CommandManager (server-wide, dispatches commands)
  └── CommandRegistry (per-plugin, auto-cleanup)
        └── AbstractCommand (command tree with subcommands/variants)
              ├── RequiredArg<T> — positional arguments
              ├── OptionalArg<T> — --named arguments
              ├── DefaultArg<T> — --named with default value
              └── FlagArg — --boolean flags

AbstractCommand

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

Constructor

protected AbstractCommand(@Nullable String name, @Nullable String description);
protected AbstractCommand(@Nullable String name, @Nullable String description, boolean requiresConfirmation);
protected AbstractCommand(@Nullable String description); // Variant (no name)

Abstract Method (must implement)

@Nullable
protected abstract CompletableFuture<Void> execute(@Nonnull CommandContext ctx);

Subcommand & Alias Management

public void addSubCommand(@Nonnull AbstractCommand command);
public void addUsageVariant(@Nonnull AbstractCommand command); // Different arg count variants
public void addAliases(String... aliases);

Argument Registration

// Required (positional) arguments
<D> RequiredArg<D> withRequiredArg(String name, String description, ArgumentType<D> argType);
<D> RequiredArg<List<D>> withListRequiredArg(String name, String description, ArgumentType<D> argType);

// Optional (--named) arguments
<D> OptionalArg<D> withOptionalArg(String name, String description, ArgumentType<D> argType);
<D> OptionalArg<List<D>> withListOptionalArg(String name, String description, ArgumentType<D> argType);

// Default (--named with fallback) arguments
<D> DefaultArg<D> withDefaultArg(String name, String description, ArgumentType<D> argType,
                                  @Nullable D defaultValue, String defaultValueDescription);

// Flag (--boolean) arguments
FlagArg withFlagArg(String name, String description);

Permission Control

public void requirePermission(@Nonnull String permission);      // Set explicit permission
@Nullable public String getPermission();                        // Get permission string
public boolean hasPermission(@Nonnull CommandSender sender);    // Check sender permission
protected void setPermissionGroups(String... groups);           // Associate with game mode groups
protected void setPermissionGroup(@Nullable GameMode gameMode); // Associate with game mode

Auto-generated Permissions

If no explicit permission is set, one is generated:

  • Root commands: {plugin.basePermission}.command.{commandName}
  • Subcommands: {parent.permission}.{subcommandName}
  • System commands: hytale.system.command.{commandName}

Other

public void setAllowsExtraArguments(boolean allowsExtraArguments);
protected void setUnavailableInSingleplayer(boolean unavailable);
@Nullable public String getFullyQualifiedName(); // e.g., "hp group set"

CommandContext

public final class CommandContext {
    @Nonnull public CommandSender sender();
    @Nonnull public String getInputString();

    // Get parsed argument values
    <D> D getArg(RequiredArg<D> arg);
    <D> D getArg(OptionalArg<D> arg);      // Returns null if not provided
    <D> D getArg(DefaultArg<D> arg);       // Returns default if not provided
    boolean getArg(FlagArg arg);           // Returns true/false

    // Player-specific
    @Nonnull Player requirePlayer() throws SenderTypeException;
    @Nonnull PlayerRef requirePlayerRef() throws SenderTypeException;
}

CommandSender

public interface CommandSender extends IMessageReceiver, PermissionHolder {
    String getDisplayName();
    UUID getUuid();
}

Extends:

  • IMessageReceiver — void sendMessage(Message message)
  • PermissionHolder — boolean hasPermission(String permission)

CommandRegistry

public class CommandRegistry {
    public void registerCommand(AbstractCommand command);
}

Obtained via getCommandRegistry() on PluginBase.

Argument Types (ArgTypes)

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

Primitive Types

Field Type Examples
ArgTypes.BOOLEAN Boolean true, false
ArgTypes.INTEGER Integer -1, 0, 56346
ArgTypes.FLOAT Float 3.14, -2.5
ArgTypes.DOUBLE Double -3.14, 0.0
ArgTypes.STRING String "quoted text"
ArgTypes.UUID UUID UUID strings

Player/Entity Types

Field Type Description
ArgTypes.PLAYER_UUID UUID Player UUID or username lookup
ArgTypes.PLAYER_REF PlayerRef Online player reference
ArgTypes.GAME_PROFILE_LOOKUP PublicGameProfile Profile lookup (sync)
ArgTypes.GAME_PROFILE_LOOKUP_ASYNC CompletableFuture<PublicGameProfile> Profile lookup (async)
ArgTypes.ENTITY_ID ArgWrapper<EntityWrappedArg, UUID> Entity UUID wrapper

Position Types

Field Type Description
ArgTypes.RELATIVE_DOUBLE_COORD Coord Single relative double (e.g., ~5.0)
ArgTypes.RELATIVE_INT_COORD IntCoord Single relative int (e.g., ~-2)
ArgTypes.RELATIVE_BLOCK_POSITION RelativeIntPosition 3D block pos (e.g., ~5 ~ ~-3)
ArgTypes.RELATIVE_POSITION RelativeDoublePosition 3D double pos
ArgTypes.RELATIVE_CHUNK_POSITION RelativeChunkPosition 2D chunk pos
ArgTypes.VECTOR3I Vector3i 3D integer vector
ArgTypes.VECTOR2I Vector2i 2D integer vector
ArgTypes.RELATIVE_VECTOR3I RelativeVector3i 3D relative vector

World/Asset Types

Field Type Description
ArgTypes.WORLD World World by name
ArgTypes.MODEL_ASSET ModelAsset Model asset reference
ArgTypes.WEATHER_ASSET Weather Weather asset
ArgTypes.ITEM_ASSET Item Item asset
ArgTypes.BLOCK_TYPE_ASSET BlockType Block type asset
ArgTypes.EFFECT_ASSET EntityEffect Entity effect asset
ArgTypes.SOUND_EVENT_ASSET SoundEvent Sound event asset
ArgTypes.PARTICLE_SYSTEM ParticleSystem Particle system asset
ArgTypes.INTERACTION_ASSET Interaction Interaction asset

Math Types

Field Type Description
ArgTypes.RELATIVE_INTEGER RelativeInteger Optionally relative int
ArgTypes.RELATIVE_FLOAT RelativeFloat Optionally relative float
ArgTypes.INT_RANGE Pair<Integer, Integer> Min/max range
ArgTypes.RELATIVE_INT_RANGE RelativeIntegerRange Relative range
ArgTypes.INTEGER_COMPARISON_OPERATOR IntegerComparisonOperator >, <, >=, <=, =, !=
ArgTypes.INTEGER_OPERATION IntegerOperation +, -, *, /, %, =

Enum Types

// Create custom enum argument type:
ArgTypes.forEnum(String name, Class<E> enumClass);
// Example: ArgTypes.SOUND_CATEGORY (SoundCategory enum)

GameMode Argument Type

ArgTypes.GameModeArgumentType // Parses "Adventure" or "Creative"

HyperPerms Usage Example

public class HyperPermsCommand extends AbstractCommand {
    public HyperPermsCommand(HyperPerms hyperPerms) {
        super("hp", "HyperPerms management command");

        addSubCommand(new HelpSubCommand());
        addSubCommand(new GroupSubCommand(hyperPerms));
        addAliases("hyperperms", "perms");
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext ctx) {
        ctx.sender().sendMessage(buildHelpMessage());
        return CompletableFuture.completedFuture(null);
    }
}

Command Parsing Flow

  1. Input tokenized by Tokenizer
  2. Subcommands matched by name/alias
  3. Required args parsed positionally
  4. Optional args parsed by --name value syntax
  5. Permissions checked at each level
  6. execute(CommandContext) called with parsed values