Skip to main content

Custom triggers

You can add your own triggers. They work exactly like the built-in ones: in /sc add, in the cue editor, in live recording and with tab completion.

How a trigger works​

A trigger is a class that:

  1. Extends Trigger.
  2. Has a @TriggerIdentifier annotation with its name.
  3. Has a no-argument constructor. ShowControl uses it for tab completion.
  4. Has a String[] constructor. It reads the arguments when a cue is added or loaded.
  5. Implements trigger(), which runs when the show reaches the cue.

Read and check all arguments in the constructor. Throw an InvalidArgumentException with a clear message when something is wrong. The player sees that message, and the cue is not added.

Example: lightning​

This trigger strikes lightning at a location:

/sc add finale 10s lightning @stage
/sc add finale 11s lightning @stage effect
import org.bukkit.Location;
import org.bukkit.Material;
import org.bukkit.entity.Player;
import tech.sbdevelopment.showcontrol.api.args.ArgReader;
import tech.sbdevelopment.showcontrol.api.args.ArgSpec;
import tech.sbdevelopment.showcontrol.api.args.ShowLocation;
import tech.sbdevelopment.showcontrol.api.exceptions.InvalidArgumentException;
import tech.sbdevelopment.showcontrol.api.triggers.Trigger;
import tech.sbdevelopment.showcontrol.api.triggers.TriggerIdentifier;

import java.util.List;

@TriggerIdentifier(value = "lightning", minArgs = 1, argDesc = "<location> [effect]", item = Material.LIGHTNING_ROD)
public class LightningTrigger extends Trigger {
private final ShowLocation location;
private final boolean effectOnly;

// Used for tab completion
public LightningTrigger() {
super();
this.location = null;
this.effectOnly = false;
}

// Used when a cue is added or loaded
public LightningTrigger(String[] data) throws InvalidArgumentException {
super(data);
ArgReader reader = new ArgReader(data, "<location> [effect]");
this.location = reader.nextLocation();
this.effectOnly = "effect".equalsIgnoreCase(reader.peek());
}

@Override
public void trigger() {
Location loc = location.resolve(); // null if the world isn't loaded or the point was deleted
if (loc == null) return;

if (effectOnly) loc.getWorld().strikeLightningEffect(loc);
else loc.getWorld().strikeLightning(loc);
}

@Override
public List<String> getArgumentTabComplete(Player player, String[] args) {
return ArgSpec.complete(player, List.of(ArgSpec.loc(), ArgSpec.value("effect")), args);
}

@Override
public List<Location> getPreviewLocations() {
Location loc = location == null ? null : location.resolve();
return loc == null ? List.of() : List.of(loc);
}
}

Register your triggers​

Register your triggers in onEnable:

@Override
public void onEnable() {
// One by one
SCAPI.register(LightningTrigger.class);

// Or every trigger in a package (and its sub-packages) of your plugin
SCAPI.index(MyPlugin.class, "com.example.myplugin.triggers");
}

The annotation​

FieldMeaning
valueThe trigger name used in /sc add. Must be unique.
minArgsThe minimum number of arguments. Fewer gives a usage message.
argDescThe usage text shown to players, like <location> [effect]
itemThe item that shows this trigger in the cue editor and recording

Methods you can override​

MethodWhen it is called
trigger()Required. When the show reaches the cue.
getArgumentTabComplete(player, args)While a player types the arguments
getPreviewLocations()By /sc preview, to show where the cue happens
remove()When the cue is deleted or the plugin shuts down. Clean up here.

Helpers​

ArgReader reads arguments one by one and throws clear errors when something is missing.

MethodReads
next(name)One word
nextInt(name), nextDouble(name), nextBool(name)A number or on/off
nextEnum(type, name)A value of an enum, like a Particle
nextLocation()A location: @point or <world> <x> <y> <z>
optDouble(name, default)An optional number
options()All remaining key:value options, as a map
rest()All remaining words as one text
peek(), hasNext()Look ahead without reading

ShowLocation is a location that may be a named point. Call resolve() when the cue fires, not in the constructor. That way the cue follows the point when it moves.

Targets reads a target like all or near:stage:20. Use Targets.parse(text) in the constructor and resolve() in trigger() to get the players.

ArgSpec describes your arguments for tab completion. Combine ArgSpec.loc(), ArgSpec.value(...), ArgSpec.options(...) and ArgSpec.text(...), then call ArgSpec.complete(player, specs, args).

Look at the built-in triggers in the package tech.sbdevelopment.showcontrol.api.triggers.impl for more examples.

note

Triggers made for ShowControl 1.x keep working. The old getArgumentTabComplete(Player, int, String) is still supported.