Objective arguments

In the CommandAPI, objectives are split into two classes:

  • The ObjectiveArgument class, which represents objectives as a whole
  • The ObjectiveCriteriaArgument class, which represents objective criteria

Objective argument

The objective argument refers to a single scoreboard objective. Unconventionally, the ObjectiveArgument must be cast to String due to implementation limitations.

Developer's Note:

The two classes ObjectiveArgument and TeamArgument must both be cast to String, as opposed to Objective and Team respectively. This is due to the fact that commands are typically registered in the onLoad() method during a plugin's initialization. At this point in the server start-up sequence, the main server scoreboard is not initialized, so it cannot be used.

Example - Move objective to sidebar

As an example, let's create a command to move an objective to a player's sidebar. To do this, we will use the following command syntax:

/sidebar <objective>

Given that an objective has to be casted to a String, we have to find a way to convert it from its name to a Bukkit Objective object. We can do that by using the getObjective(String) method from a Bukkit Scoreboard:

new CommandAPICommand("sidebar")
    .withArguments(new ObjectiveArgument("objective"))
    .executes((sender, args) -> {
        // The ObjectArgument must be casted to a String
        String objectiveName = (String) args[0];
        
        // An objective name can be turned into an Objective using getObjective(String)
        Objective objective = Bukkit.getScoreboardManager().getMainScoreboard().getObjective(objectiveName);
        
        // Set display slot
        objective.setDisplaySlot(DisplaySlot.SIDEBAR);
    })
    .register();

CommandAPICommand("sidebar")
    .withArguments(ObjectiveArgument("objective"))
    .executes(CommandExecutor { _, args ->
        // The ObjectArgument must be casted to a String
        val objectiveName = args[0] as String

        // An objective name can be turned into an Objective using getObjective(String)
        val objective = Bukkit.getScoreboardManager().mainScoreboard.getObjective(objectiveName)

        // Set display slot
        objective?.setDisplaySlot(DisplaySlot.SIDEBAR)
    })
    .register()

Objective criteria argument

The ObjectiveCriteriaArgument is fairly straight forward - it represents the criteria for an objective. Similar to Bukkit, the objective criteria is simply represented as a String, so it must be casted to a String when being used.

Example - Unregister all objectives by criteria

Say we wanted to create a command to unregister all objectives based on a given criteria. Let's create a command with the following form:

/unregisterall <objective critera>

To do this, we're going to take advantage of Bukkit's Scoreboard.getObjectivesByCriteria(String) method

new CommandAPICommand("unregisterall")
    .withArguments(new ObjectiveCriteriaArgument("objective criteria"))
    .executes((sender, args) -> {
        String objectiveCriteria = (String) args[0];
        Set<Objective> objectives = Bukkit.getScoreboardManager().getMainScoreboard().getObjectivesByCriteria(objectiveCriteria);
        
        // Unregister the objectives
        for (Objective objective : objectives) {
            objective.unregister();
        }
    })
    .register();

CommandAPICommand("unregisterall")
    .withArguments(ObjectiveCriteriaArgument("objective criteria"))
    .executes(CommandExecutor { _, args ->
        val objectiveCriteria = args[0] as String
        val objectives = Bukkit.getScoreboardManager().mainScoreboard.getObjectivesByCriteria(objectiveCriteria)

        // Unregister the objectives
        for (objective in objectives) {
            objective.unregister()
        }
    })
    .register()