Skip to main content

ReactEmitter

Types​

NormalId2D​

</>
type NormalId2D = "Top" | "Right" | "Bottom" | "Left"

Used for Emission Direction on the Rectangle shape. Functions like the regular NormalId, but without the Z-axis (Front, Back)

ParticleEmitterShape2D​

</>
type ParticleEmitterShape2D = "Rectangle" | "Annulus"

Controls the shape of the emitter, where Rectangle is the 2D equivalent of Box and Annulus is the 2D equivalent of Disc.
Annulus also functions like a 2D version of Cylinder or Sphere when ShapePartial is set to 1.

ParticleEmitterShapeStyle2D​

</>
type ParticleEmitterShapeStyle2D = "Area" | "Perimeter"

Controls where particles will be emitted within the emitter's shape.
Area is the 2D equivalent of Volume, and Perimeter is the 2D equivalent of Surface.

For an Annulus shape, a ShapePartial of 0 is equivalent to the perimeter.

EmitterProps​

</>
interface EmitterProps {
Acceleration: Vector2--

[0, 0] Acceleration along the X and Y axes.

Brightness: number--

[1] How bright this particle appears. Note that since ImageLabels do not get brighter at RGB values above 255, this has limited use.

Color: ColorSequence--

[255, 255, 255] The Color of each particle over its lifetime. Use ColorSequence.new(Color3.new(r, g, b)) for a solid color.

Drag: number--

[0] Determines the rate in seconds particles lose half their speed through exponential decay. Setting to negative will cause particles' velocity to grow exponentially.

EmissionDirection: NormalId2D--

[Top] Face of the emitter to emit from when Shape is Rectangle.

Enabled: boolean--

[true] Will emit particles at Rate * TimeScale per second when enabled. Particles can be manually emitted on a disbled emitter with the imperative API.

FlipbookFramerate: NumberRange--

[1] Determines how fast the flipbook texture animates in frames per second. Applies to FlipbookModes Loop and Random.

FlipbookImageSize: Vector2--

[1024, 1024] The dimensions of the actual image.

FlipbookLayout: ParticleFlipbookLayout--

[None] Determines the layout of the flipbook texture.

FlipbookMode: ParticleFlipbookMode--

[Loop] Determines the type of the flipbook animation.

FlipbookSizeX: number--

[1] The number of cells in the flipbook texture when using FlipbookMode Custom.

FlipbookSizeY: number--

[1] the number of rows in the flipbook texture when using FlipbookMode Custom.

FlipbookStartRandom: boolean--

[false] Determines whether to start at a random frame chosen per particle instead of starting at frame zero. Can be used with Framerate zero for a random texture.

Lifetime: NumberRange--

[5, 10] Defines a random range of ages for newly emitted particles. Particles will despawn after their age passes their lifetime.

Rate: number--

[20] How many particles to emit per second (at TimeScale 1) when the Emitter is enabled. Goes to 200, but be careful because UI particles are a lot more expensive than ParticleEmitters.

Rotation: NumberRange--

[0] Defines a random range of rotations in degrees for the particle to start at.

RotSpeed: NumberRange--

[0] Determines the range of angular speeds of emitted particles, measured in degrees per second.

Shape: ParticleEmitterShape2D--

[Rectangle] 2D Shape of the emitter, either Rectangle (like Box) or Annulus (like Cylinder, Disc, or Sphere).

ShapeDimensions: Vector2--

[1, 1] Absolute size of the emitter. A React State can be helpful for this.

ShapeInOut: Enum.ParticleEmitterShapeInOut--

[Outward] Selects whether particles emit outward only, inward only, or in both dimensions.

ShapePartial: number--

[1] For Annulus shapes, a multiplier between [0, 1] for the inner radius relative to the outer radius, where 1 is a full circle and 0 is the perimeter.

ShapeStyle: ParticleEmitterShapeStyle2D--

[Area] If particles should spawn in the whole area of the shape or just on the perimeter of the shape.

Size: NumberSequence--

[1] Determines the relative size over individual particles' lifetimes. Use NumberSequence.new(n) for a single size. Size is relative to the ParticleRenderer (relative to the larger of the two dimensions).

Speed: NumberRange--

[5] A range of speeds for the particle to start at. Can be set negative to have the particle go backwards.

SpreadAngle: number--

[0] A number determining the degrees either side of the emission direction to randomly offset the starting direction of particles by.

Squash: NumberSequence--

[0] Allows for non-uniform scaling of particles over their lifetimes. >0 elongates it vertically, and <0 elongates it horizontally.

Texture: Content--

[sparkles] The texture of each particle, given as a Content (e.g. Content.fromAssetId(xxxx) or Content.fromUri("rbxassetid://xxxx")).

TimeScale: number--

[1] Multiplier to how fast particles are simulated. Allows for values outside the range [0, 1]. Applies to rate as well.

Transparency: NumberRange--

[0] Determines the transparency of individual particles over their lifetimes. Use NumberSequence.new(n) for a single transparency.

}

These are the props used by useEmitter / useEmitters to create an Emitter. Every field is optional and has a default if not given.

Functions​

ParticleRenderer​

</>
ReactEmitter.ParticleRenderer(props: {
Emitter: Emitter,
LocalTransparencyModifier: number?,
ResampleMode: ResamplerMode?,
ZOffset: number?,
native: {[any]: any}?
}) → ReactElement

useEmitter​

</>
ReactEmitter.useEmitter(
props: EmitterProps | () → EmitterProps--

Using a function will enable the Imperative API

) → (
{emit: (number) → ()}?--

Imperative API if props was a function

)

useEmitters​

</>
ReactEmitter.useEmitters(
count: number,--

The number of emitters to create

props: {EmitterProps} | (index: number) → EmitterProps--

The properties for each emitter, either as a table or a function that returns a table given the index

) → (
{Emitter},--

An array of created emitters

{emit: (callback: (index: number) → number) → ()}?--

Imperative API created when passing a function as props

)

A hook that creates and manages multiple particle emitters. The props parameter can be either a table of emitter properties or a function that returns emitter properties based on the index.

Show raw api
{
    "functions": [
        {
            "name": "ParticleRenderer",
            "desc": "",
            "params": [
                {
                    "name": "props",
                    "desc": "",
                    "lua_type": "{ Emitter: Emitter, LocalTransparencyModifier: number?, ResampleMode: ResamplerMode?, ZOffset: number?, native: { [any]: any }? }"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ReactElement"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 176,
                "path": "src/components/ParticleRenderer.luau"
            }
        },
        {
            "name": "useEmitter",
            "desc": "",
            "params": [
                {
                    "name": "props",
                    "desc": "Using a function will enable the Imperative API",
                    "lua_type": "EmitterProps | () -> EmitterProps"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Emitter"
                },
                {
                    "desc": "Imperative API if props was a function",
                    "lua_type": "{ emit: (number) -> () }?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 12,
                "path": "src/hooks/useEmitter.luau"
            }
        },
        {
            "name": "useEmitters",
            "desc": "A hook that creates and manages multiple particle emitters. The `props` parameter can be either a table of emitter properties or a function that returns emitter properties based on the index.",
            "params": [
                {
                    "name": "count",
                    "desc": "The number of emitters to create",
                    "lua_type": "number"
                },
                {
                    "name": "props",
                    "desc": "The properties for each emitter, either as a table or a function that returns a table given the index",
                    "lua_type": "{ EmitterProps } | (index: number) -> EmitterProps"
                }
            ],
            "returns": [
                {
                    "desc": "An array of created emitters",
                    "lua_type": "{ Emitter }"
                },
                {
                    "desc": "Imperative API created when passing a function as props",
                    "lua_type": "{ emit: (callback: (index: number) -> number) -> () }?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 34,
                "path": "src/hooks/useEmitters.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "NormalId2D",
            "desc": "Used for Emission Direction on the Rectangle shape. \nFunctions like the regular NormalId, but without the Z-axis (Front, Back)",
            "lua_type": "\"Top\" | \"Right\" | \"Bottom\" | \"Left\"",
            "source": {
                "line": 193,
                "path": "src/core/Emitter.luau"
            }
        },
        {
            "name": "ParticleEmitterShape2D",
            "desc": "Controls the shape of the emitter, where Rectangle is the 2D equivalent of Box and Annulus is the 2D equivalent of Disc.  \nAnnulus also functions like a 2D version of Cylinder or Sphere when ShapePartial is set to 1.",
            "lua_type": "\"Rectangle\" | \"Annulus\"",
            "source": {
                "line": 207,
                "path": "src/core/Emitter.luau"
            }
        },
        {
            "name": "ParticleEmitterShapeStyle2D",
            "desc": "Controls where particles will be emitted within the emitter's shape.  \nArea is the 2D equivalent of Volume, and Perimeter is the 2D equivalent of Surface.\n\nFor an Annulus shape, a ShapePartial of 0 is equivalent to the perimeter.",
            "lua_type": "\"Area\" | \"Perimeter\"",
            "source": {
                "line": 224,
                "path": "src/core/Emitter.luau"
            }
        },
        {
            "name": "EmitterProps",
            "desc": "These are the props used by useEmitter / useEmitters to create an Emitter. Every field is optional and has a default if not given.",
            "fields": [
                {
                    "name": "Acceleration",
                    "lua_type": "Vector2",
                    "desc": "[0, 0] Acceleration along the X and Y axes."
                },
                {
                    "name": "Brightness",
                    "lua_type": "number",
                    "desc": "[1] How bright this particle appears. Note that since ImageLabels do not get brighter at RGB values above 255, this has limited use."
                },
                {
                    "name": "Color",
                    "lua_type": "ColorSequence",
                    "desc": "[255, 255, 255] The Color of each particle over its lifetime. Use `ColorSequence.new(Color3.new(r, g, b))` for a solid color."
                },
                {
                    "name": "Drag",
                    "lua_type": "number",
                    "desc": "[0] Determines the rate in seconds particles lose half their speed through exponential decay. Setting to negative will cause particles' velocity to grow exponentially."
                },
                {
                    "name": "EmissionDirection",
                    "lua_type": "NormalId2D",
                    "desc": "[Top] Face of the emitter to emit from when Shape is Rectangle."
                },
                {
                    "name": "Enabled",
                    "lua_type": "boolean",
                    "desc": "[true] Will emit particles at `Rate` * `TimeScale` per second when enabled. Particles can be manually emitted on a disbled emitter with the imperative API."
                },
                {
                    "name": "FlipbookFramerate",
                    "lua_type": "NumberRange",
                    "desc": "[1] Determines how fast the flipbook texture animates in frames per second. Applies to FlipbookModes Loop and Random."
                },
                {
                    "name": "FlipbookImageSize",
                    "lua_type": "Vector2",
                    "desc": "[1024, 1024] The dimensions of the actual image."
                },
                {
                    "name": "FlipbookLayout",
                    "lua_type": "ParticleFlipbookLayout",
                    "desc": "[None] Determines the layout of the flipbook texture."
                },
                {
                    "name": "FlipbookMode",
                    "lua_type": "ParticleFlipbookMode",
                    "desc": "[Loop] Determines the type of the flipbook animation."
                },
                {
                    "name": "FlipbookSizeX",
                    "lua_type": "number",
                    "desc": "[1] The number of cells in the flipbook texture when using FlipbookMode Custom."
                },
                {
                    "name": "FlipbookSizeY",
                    "lua_type": "number",
                    "desc": "[1] the number of rows in the flipbook texture when using FlipbookMode Custom."
                },
                {
                    "name": "FlipbookStartRandom",
                    "lua_type": "boolean",
                    "desc": "[false] Determines whether to start at a random frame chosen per particle instead of starting at frame zero. Can be used with Framerate zero for a random texture."
                },
                {
                    "name": "Lifetime",
                    "lua_type": "NumberRange",
                    "desc": "[5, 10] Defines a random range of ages for newly emitted particles. Particles will despawn after their age passes their lifetime."
                },
                {
                    "name": "Rate",
                    "lua_type": "number",
                    "desc": "[20] How many particles to emit per second (at TimeScale 1) when the Emitter is enabled. Goes to 200, but be careful because UI particles are a lot more expensive than ParticleEmitters."
                },
                {
                    "name": "Rotation",
                    "lua_type": "NumberRange",
                    "desc": "[0] Defines a random range of rotations in degrees for the particle to start at."
                },
                {
                    "name": "RotSpeed",
                    "lua_type": "NumberRange",
                    "desc": "[0] Determines the range of angular speeds of emitted particles, measured in degrees per second."
                },
                {
                    "name": "Shape",
                    "lua_type": "ParticleEmitterShape2D",
                    "desc": "[Rectangle] 2D Shape of the emitter, either Rectangle (like Box) or Annulus (like Cylinder, Disc, or Sphere)."
                },
                {
                    "name": "ShapeDimensions",
                    "lua_type": "Vector2",
                    "desc": "[1, 1] Absolute size of the emitter. A React State can be helpful for this."
                },
                {
                    "name": "ShapeInOut",
                    "lua_type": "Enum.ParticleEmitterShapeInOut",
                    "desc": "[Outward] Selects whether particles emit outward only, inward only, or in both dimensions."
                },
                {
                    "name": "ShapePartial",
                    "lua_type": "number",
                    "desc": "[1] For Annulus shapes, a multiplier between [0, 1] for the inner radius relative to the outer radius, where 1 is a full circle and 0 is the perimeter."
                },
                {
                    "name": "ShapeStyle",
                    "lua_type": "ParticleEmitterShapeStyle2D",
                    "desc": "[Area] If particles should spawn in the whole area of the shape or just on the perimeter of the shape."
                },
                {
                    "name": "Size",
                    "lua_type": "NumberSequence",
                    "desc": "[1] Determines the relative size over individual particles' lifetimes. Use `NumberSequence.new(n)` for a single size. Size is relative to the ParticleRenderer (relative to the larger of the two dimensions)."
                },
                {
                    "name": "Speed",
                    "lua_type": "NumberRange",
                    "desc": "[5] A range of speeds for the particle to start at. Can be set negative to have the particle go backwards."
                },
                {
                    "name": "SpreadAngle",
                    "lua_type": "number",
                    "desc": "[0] A number determining the degrees either side of the emission direction to randomly offset the starting direction of particles by."
                },
                {
                    "name": "Squash",
                    "lua_type": "NumberSequence",
                    "desc": "[0] Allows for non-uniform scaling of particles over their lifetimes. >0 elongates it vertically, and <0 elongates it horizontally."
                },
                {
                    "name": "Texture",
                    "lua_type": "Content",
                    "desc": "[sparkles] The texture of each particle, given as a Content (e.g. `Content.fromAssetId(xxxx)` or `Content.fromUri(\"rbxassetid://xxxx\")`)."
                },
                {
                    "name": "TimeScale",
                    "lua_type": "number",
                    "desc": "[1] Multiplier to how fast particles are simulated. Allows for values outside the range [0, 1]. Applies to rate as well."
                },
                {
                    "name": "Transparency",
                    "lua_type": "NumberRange",
                    "desc": "[0] Determines the transparency of individual particles over their lifetimes. Use `NumberSequence.new(n)` for a single transparency."
                }
            ],
            "source": {
                "line": 91,
                "path": "src/core/EmitterType.luau"
            }
        }
    ],
    "name": "ReactEmitter",
    "desc": "",
    "source": {
        "line": 6,
        "path": "src/init.luau"
    }
}