Using particle systems from C#

<cat>Particle.Intro</cat>
<title>Using particle systems from C#</title>

Once you have [created a particle system](Creating_your_first_particle_effect) in the particle editor there are many ways to create and interact with it in game from the C# API.

```csharp
// Most basic way to create a particle system
Particles MyParticle = Particles.Create( "particles/my_particle.vpcf" );

// Set control point 0 to a random world position, your particle system should use this control point to set it's position.
MyParticle.SetPosition( 0, new Vector3( 100, 200, 100 ) );
```

It is important to understand [how control points work](Understanding_Emmiters_Initializers_&_Operators) before creating particle systems in code, when you call Particles.SetPosition you are not directly setting the position of the system itself but rather the position of a control point that can then be used within the particle system itself.

#### Networking

Particle systems can be created both on the server and client - when created on the server they are automatically networked to all clients along with any of their control point values. When they are created on the client they are visible for that client only.
## Setting Named Values

```csharp
// Use .Set for Named Values with the name you set inside the particle and assign a Float.
MyParticles.Set( "Radius", 10.0f );

// This works the same as Float, but requires a Vector instead.
MyParticles.Set( "MoveDirection", new Vector3( 0, 0, 100 ) );
```

Inside the particle you can use "Named Float or Named Vector" instead of using Control Points, these act the same as Control Points but use a name instead of a number.

## Attaching a particle to an entity

When creating particles they can be attached to an entity.

```csharp
Particles.Create("particles/my_particle.vpcf", MyEntity, "" );
```

When you do this two things happen:

* The lifetime of this particle system is determined by the entity, when the entity is destroyed so is the particle system.
* Control point 0 is set to the entity (or its attachment) position, and will follow it.

<note>Particle systems can be attached to an entity without an attachment by providing an empty string, this does return a warning though. https://github.com/Facepunch/sbox-issues/issues/894</note>

## Destroying particle systems

Particle systems can be destroyed at any point in your code via a reference to the particle system.

```csharp
var MyParticle = Particles.Create( "particles/my_particle.vpcf" );

// Destroys a particle system
MyParticle.Destroy()

// Destroys a particle system immediately
MyParticle.Destroy( true );
```

When you destroy a particle system non immediately, the following happens:

* The emitters within the system stop emitting.
* Particles within the system that have emitted began their lifespan decay.
* The end cap is played.

When destroyed immediately none of that happens, all particles within the system are immediately deleted.

<validate>Does it wait for lifespan decay, need to validate</validate>

# Prediction and particles

Particles can be predicted, this means when you're creating particles in a [predicted method](Prediction) such as Simulate it is expected to be called from both the server and client - **if you fail to predict it properly it may not show up for your simulated client**.

```csharp
public override Simulate( IClient cl )
{
    // When the client presses their secondary attack binding, create our particle
    if ( Input.Pressed( InputButton.SecondaryAttack ) )
    {
        // This will be predicted properly
        Particles.Create( "particles/test.vpcf", this, "" );

        // This particle will not appear on the simulated Client, but will show for others.
        if ( Game.IsServer )
        {
            Particles.Create( "particles/test.vpcf", this, "" );
        }

        // This particle will appear on the client, but is not predicted.
        if ( Game.IsServer )
        {
            using ( Prediction.Off() )
            {
                Particles.Create( "particles/test.vpcf", this, "" );
            }
        }
    }
}
```

Using particle systems from C#

Account Management

Special Pages

Wiki List

S&box Wiki