effects-api-ADR-007: Command Effect and Death Stage in the Effects Engine¶
Status¶
Accepted
Context¶
Prior to this decision, server and player commands triggered around teleports were hardcoded in config.yml under consoleCommands and playerCommands and executed strictly at postteleport inside BukkitEffectsHandler. This created several limitations:
1. Commands could not be executed at other stages of the teleport lifecycle (such as preteleport, cancel, firstjoin, join, or upon death).
2. Commands could not be configured per permission node or per effect group in effects/*.yml.
3. Commands were not platform-neutral, relying on Bukkit-specific dispatch in rtp-plugin.
4. Players dying while teleporting or at any point did not have a dedicated lifecycle stage in the effects engine. While OnEventTeleports listened to PlayerDeathEvent for respawn calculation, the effects engine lacked a death stage for operators to trigger effects (e.g. particles, sounds, titles, commands) on death.
Decision¶
1. CommandEffect in effects-api¶
We introduce CommandEffect to effects-api under io.github.dailystruggle.effectsapi.common.effects.CommandEffect, registered in EffectFactory under the identifier COMMAND.
Parsing and Configuration Syntax¶
CommandEffect supports two execution modes:
- CONSOLE: Commands executed with console privileges.
- PLAYER: Commands executed as the target player.
In effects/*.yml, commands can be written cleanly and human-readably with support for quotes and backslash escapes:
effects:
- COMMAND CONSOLE say Player [player] teleported to [world]!
- COMMAND PLAYER spawn
- COMMAND CONSOLE "give [player] diamond 1"
- COMMAND CONSOLE msg [player] Welcome\ to\ [world]
In permission nodes, tokens can use quotes or backslash escapes for whitespace and special characters:
- rtp.effect.postteleport.command.console.say\ [player]\ has\ landed
- rtp.effect.death.command.console.broadcast\ [player]\ died
Placeholder Substitution¶
The command string supports the following dynamic placeholders:
- [player] or {player}: The target player's name.
- [uuid] or {uuid}: The target player's UUID.
- [world] or {world}: Target location world name (if available).
- [x], [y], [z] or {x}, {y}, {z}: Target coordinate integers (if available).
2. Platform Command Dispatch via HandleRegistry¶
Command dispatching is abstracted via HandleRegistry and HandleProvider:
- PlayerHandle: Adds void performCommand(String command).
- HandleProvider: Adds void dispatchConsoleCommand(String command) and void dispatchPlayerCommand(PlayerHandle player, String command).
- HandleRegistry: Exposes static entry points dispatchConsoleCommand and dispatchPlayerCommand.
Concurrency and Folia Invariants¶
- On Bukkit / Spigot / Paper:
- Console commands run on the main server thread.
- On Folia, console commands are scheduled via
Bukkit.getGlobalRegionScheduler().run(...). - Player commands run on the player's entity thread (
player.getScheduler().run(...)on Folia) or main server thread. - On Fabric:
- Console commands execute on the server thread via
MinecraftServer.getCommands().performPrefixedCommand(...). - Player commands execute via
ServerPlayer.getCommandSource(). - On NeoForge:
- Console commands execute on the server thread via
MinecraftServer.execute(...)withserver.getCommands().performPrefixedCommand(server.createCommandSourceStack(), command). - Player commands execute via
server.execute(...)withserver.getCommands().performPrefixedCommand(player.createCommandSourceStack(), command).
3. death Stage in the Effects Engine¶
We add death to the standard lifecycle stage vocabulary established in effects-api-ADR-005:
- Stage identifier: death.
- Permission node prefix: rtp.effect.death.<effect>....
- Configuration trigger: when: death in effects/*.yml.
- Dispatch hook: Dispatched whenever a player death event occurs on the server (PlayerDeathEvent on Bukkit, ServerPlayer death callback on Fabric, LivingDeathEvent on NeoForge).
Consequences¶
Positive¶
- Commands can be triggered on any lifecycle stage, including
death,preteleport,postteleport,cancel,join, etc. - Commands can be granted via permissions or organized in declarative groups in
effects/*.yml. - Death is a first-class effect stage, enabling rich custom animations, sounds, messages, or custom command triggers when players die.
- Full Folia thread-safety for command dispatch.
Negative / Trade-offs¶
- Commands run with console authority require careful operator configuration. Permission-driven console commands must be granted only to trusted permission tracks.