GlobalFX API

Overview

The IGlobalFXService interface — implemented by GlobalFXBridge — is the public API for controlling Global category layers at runtime. Global layers are always-on effects like hit markers, damage flashes, barrel flashes, and persistent UI widgets that exist outside the main reticle state system (HUD / HipFire / SA / ADS).

Global layers render on a dedicated ReticleRenderer instance, completely isolated from the main reticle pipeline. This isolation guarantees three properties:

• Global animations are never interrupted by category transitions
• Sequence timers never reset when the combat state changes
• Global effects can play continuously while the main reticle animates between states

Accessing the Service

The IGlobalFXService is registered automatically when the GlobalFXBridge component initializes in the scene. Access it through the service locator:

The recommended pattern is to cache the reference once in Start() and null-check before use:

using RCE.Runtime.Bootstrap;
using RCE.Runtime.Rendering;
using RCE.Runtime.Data;

public class HitMarkerController : MonoBehaviour
{
    private IGlobalFXService _globalFX;

    void Start()
    {
        _globalFX = RCEServices.GlobalFX;
    }

    public void OnHit()
    {
        _globalFX?.PlayLayerByName("HitMarker", LayerPlayMode.FireAndForget);
    }
}

API Reference — By Name

These methods use the human-readable layer name you assign in the editor. Layer names are case-sensitive. All action methods return true if the layer was found and the operation succeeded, false if the name was not found in the Global category.

Use GetGlobalLayerNames() to discover available layers at runtime — useful for populating dropdowns or validating names in configuration files:

string[] layerNames = RCEServices.GlobalFX?.GetGlobalLayerNames()
    ?? Array.Empty<string>();

foreach (var name in layerNames)
    Debug.Log($"Global layer: {name}");

API Reference — By ID

These methods use the internal GUID string. They're useful when you've cached the ID from GetLayerIdByName() or received it from an event callback. The signatures mirror the by-name API:

LayerPlayMode

The LayerPlayMode enum controls what happens when a layer's animation sequence completes naturally. Pass it as the second argument to PlayLayerByName() or PlayLayer().

// Transient effect — disappears automatically when the animation ends
_globalFX.PlayLayerByName("HitMarker", LayerPlayMode.FireAndForget);

// Persistent widget — stays visible until you explicitly hide it
_globalFX.PlayLayerByName("Compass", LayerPlayMode.Persistent);

Events & Read-Only State

GlobalFX exposes several events for tracking layer lifecycle and two read-only properties for inspecting current state:

Events

Read-Only Properties

Always unsubscribe in OnDestroy() to avoid memory leaks from stale references:

private IGlobalFXService _globalFX;

void Start()
{
    _globalFX = RCEServices.GlobalFX;
    if (_globalFX != null)
        _globalFX.OnLayerComplete += HandleLayerComplete;
}

void OnDestroy()
{
    if (_globalFX != null)
        _globalFX.OnLayerComplete -= HandleLayerComplete;
}

void HandleLayerComplete(string layerId, bool wasAutoHidden)
{
    if (wasAutoHidden)
        Debug.Log($"Layer {layerId} finished and auto-hid");
    else
        Debug.Log($"Layer {layerId} was manually stopped");
}

Auto-Play System

Layers can be configured to play automatically when the game starts — no code required. This is useful for always-on widgets like a compass overlay or persistent status indicator.

Editor Setup

1. Select a layer in the GBL (Global) category tab
2. In the LAYER section of the properties panel, enable Auto-Play
3. Choose the Play Mode (Persistent or FireAndForget)

Runtime Behavior

Auto-play is evaluated once per edit-to-test or edit-to-runtime transition. The autoPlay and autoPlayMode fields on LayerData control this behavior:

• Auto-played layers start immediately when the game enters play mode
• FireAndForget auto-play layers hide automatically when their sequence completes
• Persistent auto-play layers remain visible until explicitly hidden via the API

Usage Patterns

Hit Marker (FireAndForget)

The most common GlobalFX pattern. Trigger a transient effect on damage — the layer shows, plays its animation sequence, and hides automatically.

public class DamageController : MonoBehaviour
{
    private IGlobalFXService _globalFX;

    void Start() => _globalFX = RCEServices.GlobalFX;

    public void OnDamageDealt(float damage, bool isCritical)
    {
        if (isCritical)
            _globalFX?.PlayLayerByName("CritHitMarker", LayerPlayMode.FireAndForget);
        else
            _globalFX?.PlayLayerByName("HitMarker", LayerPlayMode.FireAndForget);
    }
}

Persistent Widget (Show / Hide / Toggle)

For widgets that stay on-screen until the player dismisses them — like a compass, ammo counter, or status indicator — use Persistent mode and manage visibility manually.

public class CompassController : MonoBehaviour
{
    private IGlobalFXService _globalFX;

    void Start() => _globalFX = RCEServices.GlobalFX;

    public void ShowCompass()
    {
        _globalFX?.PlayLayerByName("Compass", LayerPlayMode.Persistent);
    }

    public void HideCompass()
    {
        _globalFX?.HideLayerByName("Compass");
    }

    public void ToggleCompass()
    {
        if (_globalFX != null && _globalFX.IsLayerVisibleByName("Compass"))
            _globalFX.HideLayerByName("Compass");
        else
            _globalFX?.PlayLayerByName("Compass", LayerPlayMode.Persistent);
    }
}

Damage Flash with Pause

Persistent effects can be paused and resumed — useful for freeze-frame moments, pause menus, or slow-motion sequences.

public class HealthUI : MonoBehaviour
{
    private IGlobalFXService _globalFX;

    void Start() => _globalFX = RCEServices.GlobalFX;

    public void OnLowHealth()
    {
        // Start pulsing damage indicator
        _globalFX?.PlayLayerByName("LowHealthPulse", LayerPlayMode.Persistent);
    }

    public void OnPauseMenu()
    {
        // Freeze animation while game is paused
        _globalFX?.PauseLayerByName("LowHealthPulse");
    }

    public void OnResumeGame()
    {
        // Resume from where it left off
        _globalFX?.PlayLayerByName("LowHealthPulse", LayerPlayMode.Persistent);
    }

    public void OnHealthRestored()
    {
        // Stop and hide the indicator
        _globalFX?.StopLayerByName("LowHealthPulse", hide: true);
    }
}

Trigger-Based Reactive Effects

The most efficient pattern for rapid-fire reactive effects. Design a Global layer with a persistent base animation and awaitTrigger Override entries. The trigger fires a brief reactive animation that overrides the base, then smoothly releases back.

public class WeaponFireController : MonoBehaviour
{
    private IGlobalFXService _globalFX;

    void Start() => _globalFX = RCEServices.GlobalFX;

    public void OnWeaponFired()
    {
        // Fires all awaitTrigger entries on the layer.
        // Auto-starts the layer if it has autoPlay enabled.
        _globalFX?.TriggerLayerByName("WeaponRecoil");
    }
}

Chaining Effects via OnLayerComplete

Use the OnLayerComplete event to trigger follow-up effects when a FireAndForget layer finishes — creating sequenced multi-stage visual feedback without coroutines.

public class EffectChainer : MonoBehaviour
{
    private IGlobalFXService _globalFX;

    void Start()
    {
        _globalFX = RCEServices.GlobalFX;
        if (_globalFX != null)
            _globalFX.OnLayerComplete += OnEffectComplete;
    }

    void OnDestroy()
    {
        if (_globalFX != null)
            _globalFX.OnLayerComplete -= OnEffectComplete;
    }

    public void TriggerExplosion()
    {
        _globalFX?.PlayLayerByName("ExplosionFlash", LayerPlayMode.FireAndForget);
    }

    void OnEffectComplete(string layerId, bool wasAutoHidden)
    {
        // Chain: flash → smoke → debris
        string flashId = _globalFX.GetLayerIdByName("ExplosionFlash");
        string smokeId = _globalFX.GetLayerIdByName("ExplosionSmoke");

        if (layerId == flashId)
            _globalFX.PlayLayerByName("ExplosionSmoke", LayerPlayMode.FireAndForget);
        else if (layerId == smokeId)
            _globalFX.PlayLayerByName("ExplosionDebris", LayerPlayMode.FireAndForget);
    }
}

Architecture

Understanding how GlobalFX fits into the rendering pipeline helps you reason about timing, ordering, and performance.

Rendering Pipeline

LoadoutManager.EmitGlobalShapes()
       ↓
GlobalFXBridge // filters to visible layers only
       ↓
ShapePropertyAnimator // applies per-layer animations
       ↓
ReticleRenderer #2 // dedicated Global renderer instance

The main reticle pipeline (HUD / HF / SA / ADS) uses a separate ReticleRenderer instance, ensuring Global effects never interfere with combat state rendering. Each pipeline gets its own StructuredBuffer, its own draw call, and its own animation state.

Visibility Management

GlobalFXBridge never modifies LayerData.visible — the editor's saved visibility state stays intact. Runtime visibility is controlled entirely through internal HashSet collections:

• Showing or hiding at runtime doesn't affect the saved loadout
• Reloading the loadout restores the editor-configured visibility
• Auto-play respects the layer's editor visibility for its initial state

Key Files

What's Next

• Integration Guide — Wire RCE into your game's input, damage, and UI systems
• Animations — Learn about the 7 animation modes that power GlobalFX layer sequences
• Architecture — Deep dive into assembly structure, data flow, and service registration