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:
- Extends
Trigger. - Has a
@TriggerIdentifierannotation with its name. - Has a no-argument constructor. ShowControl uses it for tab completion.
- Has a
String[]constructor. It reads the arguments when a cue is added or loaded. - 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
| Field | Meaning |
|---|---|
value | The trigger name used in /sc add. Must be unique. |
minArgs | The minimum number of arguments. Fewer gives a usage message. |
argDesc | The usage text shown to players, like <location> [effect] |
item | The item that shows this trigger in the cue editor and recording |
Methods you can override
| Method | When 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.
| Method | Reads |
|---|---|
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.
Triggers made for ShowControl 1.x keep working. The old getArgumentTabComplete(Player, int, String) is still supported.