> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: Particles
icon: sparkle
---

# <ApiPageIcon icon="sparkle" />Particles

<ApiExposes data="[{&#x22;k&#x22;:&#x22;OBJECT&#x22;,&#x22;c&#x22;:&#x22;method&#x22;,&#x22;s&#x22;:&#x22;particles.Create.Options&#x22;,&#x22;h&#x22;:&#x22;#particlescreateoptions&#x22;},{&#x22;k&#x22;:&#x22;OBJECT&#x22;,&#x22;c&#x22;:&#x22;method&#x22;,&#x22;s&#x22;:&#x22;particles.Particle&#x22;,&#x22;h&#x22;:&#x22;#particlesparticle&#x22;},{&#x22;k&#x22;:&#x22;NAMESPACE&#x22;,&#x22;c&#x22;:&#x22;fn&#x22;,&#x22;s&#x22;:&#x22;particles&#x22;,&#x22;h&#x22;:&#x22;#particles-1&#x22;}]" />

## particles.Create.Options<ApiTag label="object type" />

Options for `particles.Create`. If a field has a value that is not in its enum, an error is
thrown.

<ApiMembers>
  <ApiMember kind="prop" name="particles.Create.Options.attachment" summary="How control point 0 is placed. Defaults to `WORLDORIGIN`. The values `POINT`, `POINT_FOLLOW`, `CUSTOMORIGIN` and `CUSTOMORIGIN_FOLLOW` throw an error here. To use them, create the effect with another value, and then bind the point with `SetEntity`." ret="[[{&#x22;s&#x22;:&#x22;particles.Attachment&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/particles#particles-Attachment&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" />

  <ApiMember kind="prop" name="particles.Create.Options.check_fow" summary="Whether the effect is hidden in fog of war, in the same way as the effects of the game. Defaults to `true`." ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" />

  <ApiMember kind="prop" name="particles.Create.Options.create_pvs" summary="Whether the scene objects of the effect take part in visibility culling. Defaults to `true`." ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" />

  <ApiMember kind="prop" name="particles.Create.Options.entity" summary="The entity that the effect is attached to. It is required for every `attachment` value except `WORLDORIGIN`. An invalid entity throws an error." ret="[[{&#x22;s&#x22;:&#x22;Entity&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/engine/entity#entity-1&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" />

  <ApiMember kind="prop" name="particles.Create.Options.lifespan" summary="The number of seconds until the effect is destroyed. The end cap of the effect is played when it is destroyed. The default is `0`, which means that the effect never expires. A negative value throws an error." ret="[[{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" />
</ApiMembers>

## particles.Particle<ApiTag label="object type" />

A particle effect that was created by this script.

The effect is not destroyed when the last reference to this object is gone. The effect runs
until you call `Destroy`, until its `lifespan` ends, until the script unloads, or until the map
ends. After that, every method returns `false` or `nil`.

<ApiMembers>
  <ApiMember kind="method" name="particles.Particle:IsValid" summary="Returns whether the effect is still alive and owned by this object." args="" sig="[{&#x22;s&#x22;:&#x22;particles.Particle:IsValid&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]]" nodiscard />

  <ApiMember kind="method" name="particles.Particle:GetName" summary="Returns the path of the resource that the effect was created from. Returns `nil` after the effect is gone." args="" sig="[{&#x22;s&#x22;:&#x22;particles.Particle:GetName&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" nodiscard />

  <ApiMember kind="method" name="particles.Particle:SetControlPoint" summary="Moves a control point. The orientation of the point is reset to the identity rotation." args="point, position" sig="[{&#x22;s&#x22;:&#x22;particles.Particle:SetControlPoint&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;point&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;position&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;point&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;}],&#x22;d&#x22;:&#x22;The control point, from `0` to `63`. Any other value throws an error.&#x22;},{&#x22;n&#x22;:&#x22;position&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;}],&#x22;d&#x22;:&#x22;The position in world space.&#x22;}]" returns="[{&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}],&#x22;d&#x22;:&#x22;`false` if the effect is gone.&#x22;}]" />

  <ApiMember kind="method" name="particles.Particle:SetTransform" summary="Sets the position and the orientation of a control point." args="point, transform, interpolation?" sig="[{&#x22;s&#x22;:&#x22;particles.Particle:SetTransform&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;point&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;transform&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;CTransform&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/transform#ctransform&#x22;},{&#x22;s&#x22;:&#x22;[, &#x22;},{&#x22;s&#x22;:&#x22;interpolation&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;point&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;}],&#x22;d&#x22;:&#x22;The control point, from `0` to `63`. Any other value throws an error.&#x22;},{&#x22;n&#x22;:&#x22;transform&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;CTransform&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/transform#ctransform&#x22;}],&#x22;d&#x22;:&#x22;The transform in world space.&#x22;},{&#x22;n&#x22;:&#x22;interpolation&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;}],&#x22;d&#x22;:&#x22;The number of seconds to blend from the current value to the new value. Defaults to `0`. A negative value throws an error.&#x22;,&#x22;o&#x22;:true}]" returns="[{&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}],&#x22;d&#x22;:&#x22;`false` if the effect is gone.&#x22;}]" />

  <ApiMember kind="method" name="particles.Particle:SetEntity" summary="Binds a control point to an entity. An invalid entity throws an error." args="point, entity, attachment?, attachment_name?" sig="[{&#x22;s&#x22;:&#x22;particles.Particle:SetEntity&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;point&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;entity&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;Entity&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/engine/entity#entity-1&#x22;},{&#x22;s&#x22;:&#x22;[, &#x22;},{&#x22;s&#x22;:&#x22;attachment&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;particles.Attachment&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/particles#particles-Attachment&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;attachment_name&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;point&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;}],&#x22;d&#x22;:&#x22;The control point, from `0` to `63`. Any other value throws an error.&#x22;},{&#x22;n&#x22;:&#x22;entity&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;Entity&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/engine/entity#entity-1&#x22;}],&#x22;d&#x22;:&#x22;The entity to follow.&#x22;},{&#x22;n&#x22;:&#x22;attachment&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;particles.Attachment&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/particles#particles-Attachment&#x22;}],&#x22;d&#x22;:&#x22;How the point follows the entity. Defaults to `ABSORIGIN_FOLLOW`.&#x22;,&#x22;o&#x22;:true},{&#x22;n&#x22;:&#x22;attachment_name&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}],&#x22;d&#x22;:&#x22;The name of the attachment on the model. It is required for `POINT` and `POINT_FOLLOW`, and a missing or empty name throws an error for them. It is ignored for the other values.&#x22;,&#x22;o&#x22;:true}]" returns="[{&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}],&#x22;d&#x22;:&#x22;`false` if the effect is gone.&#x22;}]" />

  <ApiMember kind="method" name="particles.Particle:SetPath" summary="Sets the shape of a rope or trail effect from a list of points. This works for effects that read a particle snapshot from a control point. For example, the effect `&#x22;particles/entity/spectator_utility_trail.vpcf&#x22;` reads it from control point `0`." args="point, points" sig="[{&#x22;s&#x22;:&#x22;particles.Particle:SetPath&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;point&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;points&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;[&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;point&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;}],&#x22;d&#x22;:&#x22;The control point for the snapshot, from `0` to `63`. Any other value throws an error.&#x22;},{&#x22;n&#x22;:&#x22;points&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;[&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;}],&#x22;d&#x22;:&#x22;The points in world space, in order. At least 2 points are required, and fewer points throw an error. Points after the maximum particle count of the effect spawn nothing.&#x22;}]" returns="[{&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}],&#x22;d&#x22;:&#x22;`false` if the effect is gone.&#x22;}]">
    <ApiNotes>
      Each call replaces the points of the previous call. The effect decides when it reads the
      points. Most effects, including the spectator trail, copy the points only when particles
      spawn. A later call does not move particles that are already alive. Point `i` gets a creation
      time of `(i - 1) / (#points - 1)`.

      The effect gets one particle for each point. The spectator trail scales the width of each
      particle by its index along the path. Because of this, a path with only two points draws
      nothing that you can see. Split a straight line into 16 to 24 points.

      The spectator trail draws a beam once. Control point `3` holds the particle life in seconds,
      the width and the alpha. Control point `16` holds the colour. The alpha of a particle grows
      with its age. Its width grows during the first half of its life and shrinks to zero during the
      second half. Give the effect a `lifespan` that is a little longer than the particle life.
    </ApiNotes>

    <ApiExample title="Red beam between two points">
      ```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/rendering/particles:0:bdd7e82b4f31"
      local from, to = Vector(0, 0, 64), Vector(256, 0, 64)
      local points = {}
      for i = 0, 23 do
          local t = i / 23
          points[#points + 1] = from + (to - from) * t
      end
      local beam = particles.Create("particles/entity/spectator_utility_trail.vpcf", { lifespan = 2.3 })
      if beam then
          beam:SetPath(0, points)
          beam:SetControlPoint(16, Vector(255, 0, 0)) -- color
          beam:SetControlPoint(3, Vector(2, 0.4, 1))  -- particle life, width, alpha
      end
      ```
    </ApiExample>
  </ApiMember>

  <ApiMember kind="method" name="particles.Particle:Destroy" summary="Destroys the effect." args="play_endcap?" sig="[{&#x22;s&#x22;:&#x22;particles.Particle:Destroy&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;[&#x22;},{&#x22;s&#x22;:&#x22;play_endcap&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;play_endcap&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}],&#x22;d&#x22;:&#x22;Whether the effect plays its end sequence first. Defaults to `true`.&#x22;,&#x22;o&#x22;:true}]" returns="[{&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}],&#x22;d&#x22;:&#x22;`false` if the effect was already gone.&#x22;}]" />
</ApiMembers>

<Heading level={2} id="particles-1">
  particles

  <ApiTag label="global table" />
</Heading>

Creates and controls particle effects. The game simulates and renders the effects.

A script can have at most 256 effects alive at the same time. Creating one more throws an
error.

<ApiMembers>
  <ApiMember kind="fn" name="particles.Create" summary="Creates a particle effect from a compiled `.vpcf` resource." args="path, options?" sig="[{&#x22;s&#x22;:&#x22;particles.Create&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;path&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;[, &#x22;},{&#x22;s&#x22;:&#x22;options&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;particles.Create.Options&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/particles#particlescreateoptions&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;particles.Particle&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/particles#particlesparticle&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;particles.Particle&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/particles#particlesparticle&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;path&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}],&#x22;d&#x22;:&#x22;The path of the resource, for example `\&#x22;particles/entity/spectator_utility_trail.vpcf\&#x22;`.&#x22;},{&#x22;n&#x22;:&#x22;options&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;particles.Create.Options&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/particles#particlescreateoptions&#x22;}],&#x22;d&#x22;:&#x22;The options for the attachment and the lifetime of the effect.&#x22;,&#x22;o&#x22;:true}]">
    <ApiNotes>
      Returns `nil` when the client is not in a game or when the resource cannot be found. Throws an
      error if another script registered the name with `particles.Register`.
    </ApiNotes>

    <ApiExample title="Create a trail">
      ```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/rendering/particles:1:0ee9dbd59084"
      local fx = particles.Create("particles/entity/spectator_utility_trail.vpcf", { lifespan = 3 })
      if fx then fx:SetControlPoint(0, Vector(0, 0, 64)) end
      ```
    </ApiExample>
  </ApiMember>

  <ApiMember kind="fn" name="particles.Register" summary="Loads a compiled particle system from memory, so that `particles.Create(name)` can use it. Use this function to add an effect that the game does not have, such as a rope that stays in the world." args="name, bytes" sig="[{&#x22;s&#x22;:&#x22;particles.Register&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;name&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;bytes&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}],[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;name&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}],&#x22;d&#x22;:&#x22;The name of the resource in the form `particles/\u003cpath\u003e.vpcf`, with at most 255 characters. Any other name throws an error.&#x22;},{&#x22;n&#x22;:&#x22;bytes&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}],&#x22;d&#x22;:&#x22;The data of the compiled particle system. An empty string throws an error.&#x22;}]" returns="[{&#x22;n&#x22;:&#x22;ok&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}],&#x22;d&#x22;:&#x22;`true` if the particle system was loaded.&#x22;},{&#x22;n&#x22;:&#x22;reason&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}],&#x22;d&#x22;:&#x22;The reason why the loading failed, if `ok` is `false`.&#x22;}]">
    <ApiNotes>
      `bytes` must be a compiled CS2 particle system, which is the content of a `.vpcf_c` file. Bad
      data can crash the game.

      The name must not be used by any resource of the game. A name that a script registered before
      it unloaded can be registered again. A name that is already registered throws an error.

      The registration belongs to this script. Only this script can create effects from the name.
      When the script unloads, those effects are removed without their end cap and the resource is
      freed.

      A script can register at most 32 particle systems. Each one can be at most 4 MB. Going over
      either limit throws an error.
    </ApiNotes>

    <ApiExample title="Register and draw a rope">
      ```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/rendering/particles:2:b3060b0a4590"
      local ok, err = particles.Register("particles/my_script/rope.vpcf", require("rope_bytes"))
      if not ok then print(err) return end

      local rope = particles.Create("particles/my_script/rope.vpcf")
      if rope then rope:SetPath(0, { Vector(0, 0, 64), Vector(256, 0, 64) }) end
      ```
    </ApiExample>
  </ApiMember>

  <ApiMember kind="type" name="particles.Attachment" summary="How an effect or a control point follows its entity." ret="[[{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;}]]">
    <ApiEnum name="particles.Attachment" values="[[&#x22;ABSORIGIN&#x22;,&#x22;0&#x22;,&#x22;At the origin of the entity when the effect is created.&#x22;],[&#x22;ABSORIGIN_FOLLOW&#x22;,&#x22;1&#x22;,&#x22;Follows the origin of the entity.&#x22;],[&#x22;CUSTOMORIGIN&#x22;,&#x22;2&#x22;,&#x22;At a custom origin when the effect is created.&#x22;],[&#x22;CUSTOMORIGIN_FOLLOW&#x22;,&#x22;3&#x22;,&#x22;Follows a custom origin.&#x22;],[&#x22;POINT&#x22;,&#x22;4&#x22;,&#x22;At a named attachment when the effect is created.&#x22;],[&#x22;POINT_FOLLOW&#x22;,&#x22;5&#x22;,&#x22;Follows a named attachment.&#x22;],[&#x22;EYES_FOLLOW&#x22;,&#x22;6&#x22;,&#x22;Follows the eyes of the entity.&#x22;],[&#x22;OVERHEAD_FOLLOW&#x22;,&#x22;7&#x22;,&#x22;Follows a point above the entity.&#x22;],[&#x22;WORLDORIGIN&#x22;,&#x22;8&#x22;,&#x22;In world space. The script sets the control points.&#x22;],[&#x22;ROOTBONE_FOLLOW&#x22;,&#x22;9&#x22;,&#x22;Follows the root bone.&#x22;],[&#x22;RENDERORIGIN_FOLLOW&#x22;,&#x22;10&#x22;,&#x22;Follows the render origin of the entity.&#x22;],[&#x22;CENTER_FOLLOW&#x22;,&#x22;13&#x22;,&#x22;Follows the center of the entity.&#x22;]]" />
  </ApiMember>
</ApiMembers>
