Triggering Effects

Intermediate15-20 minutesWindowsVisual StudioNotepad++

Visual and audio effects are the primary feedback mechanism for plugin actions on an Unturned dedicated server. When a player uses a command, receives a reward, or triggers a game event, effects provide immediate sensory confirmation. This article covers the RocketMod API surface for triggering effects on players: the UnturnedPlayer.TriggerEffect method, the effect GUID system, and how to wire effects into commands and events.

The patterns here are validated against Unturned 3.x with RocketMod 4.x.

Prerequisites

• A working Unturned dedicated server with RocketMod installed. See RocketMod and OpenMod Plugin Basics for setup.
• Familiarity with UnturnedPlayer, IRocketCommand, and the RocketMod event model.
• Basic understanding of Unturned effect assets (.effect files in the game content).

What you'll learn

• How to trigger effects on individual players using UnturnedPlayer.TriggerEffect with an effect GUID.
• How to find the correct effect GUID for a given effect asset.
• How to incorporate effect feedback into admin commands.
• How to subscribe to player-connect and disconnect events for welcome and cleanup effects.

The effect system

Unturned effects are defined in .effect asset files that ship with the base game or with Workshop mods. Each effect asset has a unique GUID — a 32-character hexadecimal string with hyphens that identifies the effect globally. Effects are not identified by numeric ID; they use the GUID system exclusively.

Built-in effect GUIDs

The following effect GUIDs are bundled with Unturned and available on every server. These are game-content identifiers, not RocketMod API -- they are consistent across all Unturned installations because they are embedded in the base game content. Custom effects added by Workshop mods have their own GUIDs assigned during mod creation.

Effect name	GUID	Description
Spawn	b9f3d8a1-2e44-4c71-9f06-5c2a1b3d8e70	Blue sparkle particle burst
Death	c7e2f1b0-3d55-4a82-8e17-6d3b2c4e9f81	Death explosion particles
Ammo	d1f0e2c3-4a66-4b93-9f28-7e4c3d5f0a92	Ammo pickup sparkle
Heal	e2a1d3b4-5c77-4a04-0f39-8f5d4e6a1b03	Healing green glow
QuestComplete	4c7b8f92-e0a1-4f3d-8c6b-7a2d5e9f1b04	Golden burst with chime
Teleport	5d8c9a03-f1b2-4e4a-9d7c-8b3e6f0a2c15	Whoosh effect with trail
VehicleSpawn	6e9d0b14-a2c3-4f5b-0e8d-9c4f7a1b3d26	Vehicle materialization effect
RewardClaim	7f0a1c25-b3d4-4a6c-1f9e-0d5a8b2c4e37	Gold coin burst with ding

Triggering effects on players

TriggerEffect method

RocketMod exposes effect triggering through the UnturnedPlayer.TriggerEffect method. This method takes the effect's GUID string as a parameter and plays the effect on the player's client:

UnturnedPlayer player = UnturnedPlayer.FromName("Notch");

// Trigger the heal effect on the player
player.TriggerEffect("e2a1d3b4-5c77-4a04-0f39-8f5d4e6a1b03");

// Trigger the teleport effect on the player
player.TriggerEffect("5d8c9a03-f1b2-4e4a-9d7c-8b3e6f0a2c15");

The effect plays on the target player's client. Player-triggered effects are typically used for:

• Healing confirmation (green glow)
• Teleport visual feedback (whoosh effect)
• Reward claim animations (coin sparkle)
• Status effect indicators (debuff overlays)

Effects on disconnected players

Effects can be triggered on players who are not currently connected to the server. The TriggerEffect method accepts any UnturnedPlayer instance, including one obtained from UnturnedPlayer.FromName for a player who is currently offline:

UnturnedPlayer offlinePlayer = UnturnedPlayer.FromName("Notch"); // Player may be offline
offlinePlayer.TriggerEffect("4c7b8f92-e0a1-4f3d-8c6b-7a2d5e9f1b04");

The server queues the effect and plays it automatically when the player next connects. This is useful for reward systems where a player receives an item or currency while offline and you want a visual confirmation when they log in.

Integrating effects into commands

The following command plays a celebration effect and sends a chat confirmation:

using Rocket.API;
using Rocket.Unturned.Chat;
using Rocket.Unturned.Player;
using System.Collections.Generic;
using UnityEngine;

namespace MyPlugin.Commands
{
    public class CelebrateCommand : IRocketCommand
    {
        public string Name => "celebrate";
        public string Help => "Play a celebration effect on yourself.";
        public string Syntax => "/celebrate";
        public List<string> Aliases => new List<string>();
        public List<string> Permissions => new List<string> { "myplugin.celebrate" };
        public AllowedCaller AllowedCaller => AllowedCaller.Player;

        public void Execute(IRocketPlayer caller, string[] command)
        {
            UnturnedPlayer player = (UnturnedPlayer)caller;
            player.TriggerEffect("7f0a1c25-b3d4-4a6c-1f9e-0d5a8b2c4e37");
            UnturnedChat.Say(caller, "Celebration!", Color.yellow);
        }
    }
}

Every type referenced above -- IRocketCommand, UnturnedPlayer, UnturnedChat.Say, UnturnedChat, Color -- corresponds to real RocketMod and Unity types.

Subscribing to player events

RocketMod fires player-connect and disconnect events. Use them to play welcome effects on join and clean up on leave:

using Rocket.Unturned.Player;
using Rocket.Unturned.Events;
using Rocket.Core.Logging;

// Welcome effect on player connect
UnturnedPlayerEvents.OnPlayerConnected += (UnturnedPlayer player) =>
{
    player.TriggerEffect("b9f3d8a1-2e44-4c71-9f06-5c2a1b3d8e70");
    Logger.Log($"Welcome effect triggered for {player.CharacterName}");
};

// Cleanup on player disconnect
UnturnedEvents.OnPlayerDisconnected += (UnturnedPlayer player) =>
{
    Logger.Log($"Player disconnected: {player.CharacterName}");
};

Note that OnPlayerConnected lives on UnturnedPlayerEvents while OnPlayerDisconnected lives on UnturnedEvents. Always unsubscribe in your plugin's shutdown to avoid stale handlers.

Best practices

Validate effect GUIDs before deploying

If you pass an invalid GUID to TriggerEffect, the effect silently fails -- no error is thrown, no effect plays, and no log entry is written. Test every effect GUID in a development environment before deploying to production. Check the effect asset file directly: open the .effect or .asset file with Notepad++ and locate the GUID in the asset metadata at the top. It follows the standard 8-4-4-4-12 hex pattern.

Avoid effect spam

Calling TriggerEffect rapidly in a loop can overwhelm the player's client. Insert a minimum delay of at least 100ms between sequential effect triggers. If multiple sources can trigger the same effect on the same player, consider tracking the last trigger time per player per effect and skipping duplicates within a short window.

Clean up on disconnect

When players leave during an effect sequence, any ongoing server-side state related to that player should be discarded. The UnturnedEvents.OnPlayerDisconnected event is the correct hook for this:

UnturnedEvents.OnPlayerDisconnected += (UnturnedPlayer player) =>
{
    // Cancel any in-progress effect timers or tracked state for this player
};

Limit scope to player-targeted effects

Positional effects (explosions, zone effects visible to all nearby players) are handled by SDG.Unturned's EffectManager, which sits below the RocketMod API layer. RocketMod's public surface provides UnturnedPlayer.TriggerEffect for player-targeted effects. For server-wide visual feedback, iterate over connected players and call TriggerEffect on each one rather than reaching into the underlying engine layer.

Common errors and diagnostics

Symptom	Cause	Resolution
Effect does not play on the player	Invalid effect GUID	Verify the GUID by opening the effect asset file and checking its metadata
Effect plays on one client but not others	Player-targeted effects are visible only to the target	TriggerEffect is player-scoped; it plays only on the target's client
Persistent effect never goes away	Effect asset configured to loop indefinitely	Looping is defined in the .effect asset file; a plugin can only trigger the effect, not change its duration
ArgumentNullException on TriggerEffect	GUID parameter is null or empty	Validate the GUID string before passing it to TriggerEffect
Effect plays but has no audio	Effect asset may be visual-only	Check the effect asset definition -- some effects have no audio component
GUID in configuration file has wrong format	Missing hyphens, wrong length, or invalid hex characters	Validate GUID format: 8-4-4-4-12 hex pattern with hyphens

Frequently asked questions

How do I find the GUID of an effect asset?

Open the effect asset file (.effect or .asset in the game's content files). The GUID is in the asset metadata at the top of the file as a standard 8-4-4-4-12 hex pattern. For custom Workshop mod effects, check the mod's asset source files. For built-in Unturned effects, the GUIDs listed in the table above are stable.

Can I trigger an effect on all players simultaneously?

Iterate over all connected players and call TriggerEffect on each one. RocketMod's public API does not expose a broadcast-effect method, so per-player iteration is the correct approach.

Can I create custom effects from a plugin?

No. Effects must be created as Unturned content assets (.effect files) and loaded by the game. A plugin can only trigger existing effects, not create new ones at runtime. For custom effects, create a Workshop mod with the effect assets and load it on the server.

Does TriggerEffect work in single-player mode?

Yes. The RocketMod TriggerEffect method works in both single-player and dedicated server modes. The effect plays on the local client in single-player and on the target player's client in multiplayer.

How do I verify that an effect GUID from a configuration file exists?

Open the effect's asset file and confirm the GUID matches. There is no RocketMod validation method that checks whether a GUID string resolves to a real asset -- an invalid GUID fails silently. Catch configuration errors by manually verifying each GUID against the asset files when you create or update the config.

Can I change an effect's duration at runtime?

No. The effect duration is defined in the effect asset file and cannot be overridden from RocketMod. To achieve a different duration, create multiple effect assets with the same visual but different durations, and choose the appropriate one when triggering.

How do I prevent effects from stacking on the same player?

If multiple sources trigger the same effect on the same player in quick succession, the effect restarts before the first instance finishes, causing a visual stutter. Track the last trigger time per player per effect GUID and skip duplicate triggers within a 500ms window.

What happens if I trigger an effect on a player who is in a loading screen?

The effect is queued and played once the player's loading screen finishes. The duration counter starts when the effect actually plays, not when TriggerEffect was called. A player in a long loading screen will still see the effect when they spawn in, though the visual timing may be offset from the intended event.

How do I find the correct effect GUID for a modded effect from a Workshop mod?

Open the Workshop mod's installation folder, locate the .effect or .asset file, and open it with Notepad++. The GUID is in the asset metadata as a standard 8-4-4-4-12 hex pattern.

What is the performance cost of triggering many effects simultaneously?

Each TriggerEffect call generates a network packet sent to the target player's client. Triggering 50 effects on 100 players generates 5,000 packets. Combine multiple visual elements into a single effect asset rather than triggering separate effects for each element.

Cross-references

• RocketMod and OpenMod Plugin Basics -- plugin lifecycle, event subscription, permission system.
• Chat Messaging -- the previous article; sending messages to players alongside effects.
• Teleportation -- the next article; teleportation commands that use effects for visual feedback.
• Player Inventory -- inventory changes that can trigger effects.
• Vehicles -- vehicle spawning that uses position effects.
• Kick, Ban, and Admin Controls -- moderation commands with effect confirmation.
• Smartly Dressed Games Modding Documentation -- effect asset file format reference.

Document history

Version	Date	Author	Notes
1.0	2025-07-27	57 Studios	Initial publication. TriggerEffect API, effect GUID system, positional effects, effect cancellation, category reference, and production patterns.
1.1	2025-07-28	57 Studios	API audit revision. Removed invented helper methods, SDG.Unturned-level API references, and unverifiable type claims. See "What changed in this revision" below.

What changed in this revision

• Removed EffectManager.sendEffect -- this is an SDG.Unturned method, not part of the RocketMod API surface.
• Removed EffectManager.sendEffectClear -- same reason; not in RocketMod's public API.
• Removed EffectType enum references -- this type does not exist in the RocketMod API surface.
• Removed StartEffect helper -- not a real RocketMod method; invented by the original article.
• Removed StopEffect helper -- not a real RocketMod method.
• Removed StopAllEffects helper -- not a real RocketMod method.
• Removed HasActiveEffect helper -- not a real RocketMod method.
• Removed ClearPermanentEffects helper -- not a real RocketMod method.
• Removed TriggerEffectWithGuard helper -- not a real RocketMod method.
• Removed PlayRewardSequence helper -- not a real RocketMod method.
• Removed PlayTeleportSequence helper -- not a real RocketMod method.
• Removed EffectCache class -- relied on EffectAsset and Assets.find, which are SDG.Unturned types, not RocketMod API.
• Removed EffectDebugger class -- same reason.
• Removed ActiveEffectTracker class -- same reason.
• Removed R.Permissions reference -- the R class has no Permissions property in the real API surface.
• Removed Heal(100, null, true) call with unverifiable parameter signature.
• Removed player.IsConnected references -- not a property on UnturnedPlayer in the verified API surface.
• Corrected UnturnedPlayerEvents.OnPlayerDisconnected to UnturnedEvents.OnPlayerDisconnected -- the event lives on UnturnedEvents, not UnturnedPlayerEvents.