BlueBeard.Effects 0.1.0-ci.24

BlueBeard.Effects

A managed effect emitter system for Unturned. Spawn visual effects at world positions using spatial patterns and audience targeting, with automatic lifecycle management.

Installation

Add a project reference:

<ProjectReference Include="..\BlueBeard.Effects\BlueBeard.Effects.csproj" />

Setup

using BlueBeard.Effects;

// In your plugin:
var effectManager = new EffectEmitterManager();
effectManager.Load();

// On unload:
effectManager.Unload(); // stops and destroys all active emitters

Spawning Effects

One-Shot Effect

Spawn an effect once at a position:

using BlueBeard.Effects;
using BlueBeard.Effects.Patterns;
using BlueBeard.Effects.Audiences;

var definition = new EffectDefinition
{
    EffectId = 1234,
    Pattern = new SinglePointPattern(),
    Origin = position,
    OneShot = true,
    SnapToSurface = true
};

effectManager.Start(definition, new AllPlayersAudience());

Repeating Effect

Spawn effects on a loop (e.g., zone border particles):

var definition = new EffectDefinition
{
    EffectId = 5678,
    Pattern = new CirclePattern(radius: 15f, pointCount: 20),
    Origin = zoneCenter,
    OneShot = false,
    Interval = 2f, // seconds between each cycle
    SnapToSurface = true
};

var emitter = effectManager.Start(definition, new AllPlayersAudience());

// Stop it later:
effectManager.Stop(emitter);

Patterns

Patterns define where effects are spawned (as offsets from Origin).

Custom Patterns

Implement IEffectPattern:

using BlueBeard.Effects.Patterns;

public class CrossPattern : IEffectPattern
{
    private readonly float _size;
    public CrossPattern(float size) { _size = size; }

    public IEnumerable<Vector3> GetPoints()
    {
        yield return new Vector3(-_size, 0, 0);
        yield return new Vector3(_size, 0, 0);
        yield return new Vector3(0, 0, -_size);
        yield return new Vector3(0, 0, _size);
        yield return Vector3.zero;
    }
}

Audiences

Audiences define who sees the effects.

Custom Audiences

Implement IEffectAudience:

using BlueBeard.Effects.Audiences;

public class NearbyPlayersAudience : IEffectAudience
{
    private readonly Vector3 _center;
    private readonly float _range;

    public NearbyPlayersAudience(Vector3 center, float range)
    {
        _center = center;
        _range = range;
    }

    public IEnumerable<ITransportConnection> GetRecipients()
    {
        foreach (var client in Provider.clients)
        {
            if (Vector3.Distance(client.player.transform.position, _center) <= _range)
                yield return client.transportConnection;
        }
    }
}

EffectDefinition

Events

// EffectEmitter fires Completed when a one-shot finishes:
emitter.Completed += e => Logger.Log("Effect finished");