Class Effects.ParticleGroups

Create and manage particle groups.

Functions

ParticleGroup(objectID, maxParticles) Create a ParticleGroup for managing collections of particles with Lua-driven behavior.
ParticleGroup:Start() Start emitting particles.
ParticleGroup:Stop() Stop emitting particles.
ParticleGroup:Pause() Pause the group.
ParticleGroup:Resume() Resume a paused group.
ParticleGroup:EmitBurst(count) Emit a burst of particles immediately.
ParticleGroup:GetActiveCount() Get number of active particles.
ParticleGroup:SetEmissionRate(rate) Set the emission rate in particles per second.
ParticleGroup:SetPosition(pos) Set the emitter position.
ParticleGroup:GetPosition() Get the emitter position.
ParticleGroup:SetInitialVelocity(vel) Set initial velocity for new particles.
ParticleGroup:SetInitialVelocityRandom(range) Set random range added to initial velocity.
ParticleGroup:SetInitialAcceleration(accel) Set initial acceleration for new particles.
ParticleGroup:SetLifetime(seconds) Set a fixed lifetime for new particles.
ParticleGroup:SetLifetimeRange(minSeconds, maxSeconds) Set lifetime range for new particles.
ParticleGroup:SetInitialSize(size) Set a fixed initial size for new particles.
ParticleGroup:SetInitialSizeRange(min, max) Set initial size range for new particles.
ParticleGroup:SetInitialColor(color) Set initial color for new particles.
ParticleGroup:SetInitialColorRange(min, max) Set initial color range for new particles.
ParticleGroup:SetInitialRotation(rotation) Set initial rotation for new particles in degrees.
ParticleGroup:SetInitialRotationVelocity(rotVel) Set initial rotational velocity for new particles.
ParticleGroup:SetBlendMode(mode) Set blend mode for rendering.
ParticleGroup:SetObjectID(objectID) Set the object slot (sprite sequence or mesh object) for the group.
ParticleGroup:SetSubIndex(index) Set sprite or mesh sub-index for newly emitted particles.
ParticleGroup:GetSubIndex() Get the current sprite or mesh sub-index used for new particles.
ParticleGroup:GetObjectID() Get the current object slot ID.
ParticleGroup:IsMeshGroup() Check if this group renders 3D meshes.
ParticleGroup:SetInitialOrientation(orientation) Set initial orientation for mesh particles in degrees (pitch, yaw, roll).
ParticleGroup:SetContactRadius(radius) Set the contact radius used for deadly bounds detection.
ParticleGroup:GetParticle(index) Get a specific particle's data as a table.
ParticleGroup:SetParticle(index, data) Set a specific particle's properties from a table.
ParticleGroup:ForEachParticle(callback) Iterate over all active particles, calling a function for each.

Tables

Particle Structure for a Particle table.


Functions

ParticleGroup(objectID, maxParticles)
Create a ParticleGroup for managing collections of particles with Lua-driven behavior. If the specified object ID is a sprite sequence, particles render as sprites. If it is a mesh object (moveable), particles render as 3D meshes, and the sub index selects which mesh within the object to draw.

Parameters:

  • objectID ObjID Object slot ID (sprite sequence or mesh object).
  • maxParticles int Maximum number of particles in the group.

Returns:

    ParticleGroup A new ParticleGroup.

Usage:

    local group = TEN.Effects.ParticleGroup(TEN.Objects.ObjID.DEFAULT_SPRITES, 200)
 group:SetPosition(Vec3(0, 0, 1024))
 group:Start()
ParticleGroup:Start()
Start emitting particles.

Usage:

    group:Start()
ParticleGroup:Stop()
Stop emitting particles. Existing particles continue until they expire.

Usage:

    group:Stop()
ParticleGroup:Pause()
Pause the group. Stops emission and freezes all existing particles in place.

Usage:

    group:Pause()
ParticleGroup:Resume()
Resume a paused group.

Usage:

    group:Resume()
ParticleGroup:EmitBurst(count)
Emit a burst of particles immediately.

Parameters:

  • count int Number of particles to emit.

Usage:

    group:EmitBurst(50)
ParticleGroup:GetActiveCount()
Get number of active particles.

Returns:

    int Number of active particles.

Usage:

    local count = group:GetActiveCount()
ParticleGroup:SetEmissionRate(rate)
Set the emission rate in particles per second.

Parameters:

  • rate float Particles per second.

Usage:

    group:SetEmissionRate(60)
ParticleGroup:SetPosition(pos)
Set the emitter position.

Parameters:

  • pos Vec3 World position.

Usage:

    group:SetPosition(Vec3(0, 0, 1024))
ParticleGroup:GetPosition()
Get the emitter position.

Returns:

    Vec3 World position.

Usage:

    local pos = group:GetPosition()
ParticleGroup:SetInitialVelocity(vel)
Set initial velocity for new particles.

Parameters:

  • vel Vec3 Velocity vector in world units per second.

Usage:

    group:SetInitialVelocity(Vec3(0, 200, 0))
ParticleGroup:SetInitialVelocityRandom(range)
Set random range added to initial velocity.

Parameters:

  • range Vec3 Per-axis random range (+/- range).

Usage:

    group:SetInitialVelocityRandom(Vec3(300, 40, 300))
ParticleGroup:SetInitialAcceleration(accel)
Set initial acceleration for new particles.

Parameters:

  • accel Vec3 Acceleration vector in world units per second squared.

Usage:

    group:SetInitialAcceleration(Vec3(0, 30, 0))
ParticleGroup:SetLifetime(seconds)
Set a fixed lifetime for new particles.

Parameters:

  • seconds float Lifetime in seconds.

Usage:

    group:SetLifetime(3.0)
ParticleGroup:SetLifetimeRange(minSeconds, maxSeconds)
Set lifetime range for new particles.

Parameters:

  • minSeconds float Minimum lifetime.
  • maxSeconds float Maximum lifetime.

Usage:

    group:SetLifetimeRange(2.0, 5.0)
ParticleGroup:SetInitialSize(size)
Set a fixed initial size for new particles.

Parameters:

  • size float Particle size in world units.

Usage:

    group:SetInitialSize(128)
ParticleGroup:SetInitialSizeRange(min, max)
Set initial size range for new particles.

Parameters:

  • min float Minimum size.
  • max float Maximum size.

Usage:

    group:SetInitialSizeRange(48, 128)
ParticleGroup:SetInitialColor(color)
Set initial color for new particles.

Parameters:

  • color Color Particle color.

Usage:

    group:SetInitialColor(Color(255, 160, 50))
ParticleGroup:SetInitialColorRange(min, max)
Set initial color range for new particles.

Parameters:

  • min Color Minimum color.
  • max Color Maximum color.

Usage:

    group:SetInitialColorRange(Color(255, 100, 20), Color(255, 200, 80))
ParticleGroup:SetInitialRotation(rotation)
Set initial rotation for new particles in degrees.

Parameters:

  • rotation float Rotation in degrees.

Usage:

    group:SetInitialRotation(90)
ParticleGroup:SetInitialRotationVelocity(rotVel)
Set initial rotational velocity for new particles.

Parameters:

  • rotVel float Rotational velocity in degrees per second.

Usage:

    group:SetInitialRotationVelocity(45)
ParticleGroup:SetBlendMode(mode)
Set blend mode for rendering. Applies to sprite groups only. Mesh groups use per-material blend modes.

Parameters:

Usage:

    group:SetBlendMode(TEN.Effects.BlendID.ADDITIVE)
ParticleGroup:SetObjectID(objectID)
Set the object slot (sprite sequence or mesh object) for the group. For sprite sequences, the sub-index selects which sprite to draw. For mesh objects, the sub-index selects which mesh to draw.

Parameters:

  • objectID ObjID Object slot ID.

Usage:

    group:SetObjectID(TEN.Objects.ObjID.DEFAULT_SPRITES)
ParticleGroup:SetSubIndex(index)
Set sprite or mesh sub-index for newly emitted particles.

Parameters:

  • index int Sprite or mesh sub-index.

Usage:

    group:SetSubIndex(2)
ParticleGroup:GetSubIndex()
Get the current sprite or mesh sub-index used for new particles.

Returns:

    int Current sub-index.

Usage:

    local idx = group:GetSubIndex()
ParticleGroup:GetObjectID()
Get the current object slot ID.

Returns:

    ObjID Current object slot ID.

Usage:

    local objID = group:GetObjectID()
ParticleGroup:IsMeshGroup()
Check if this group renders 3D meshes.

Returns:

    bool True if particles render as 3D meshes, false for sprites.

Usage:

    local isMesh = group:IsMeshGroup()
ParticleGroup:SetInitialOrientation(orientation)
Set initial orientation for mesh particles in degrees (pitch, yaw, roll). For sprite groups it fixes the orientation of the sprites.

Parameters:

  • orientation Rotation Orientation in degrees.

Usage:

    group:SetInitialOrientation(Rotation(0, 90, 0))
ParticleGroup:SetContactRadius(radius)
Set the contact radius used for deadly bounds detection. Uses an AABB check against Lara's deadly bounds. Default is 128 world units. New particles inherit this value.

Parameters:

  • radius float Distance in world units. Must be greater than 0.

Usage:

    group:SetContactRadius(256)
ParticleGroup:GetParticle(index)
Get a specific particle's data as a table. Returns nil if the index is out of range, the particle is inactive, or the group is invalid.

Parameters:

  • index int Particle index (0-based).

Returns:

    table or nil Particle data table.

Usage:

    local p = group:GetParticle(0)
ParticleGroup:SetParticle(index, data)
Set a specific particle's properties from a table. All rotation and orientation values are in degrees. Set teleport = true to suppress interpolation after a large position jump.

Parameters:

  • index int Particle index (0-based).
  • data table Table with properties to set.

Usage:

    group:SetParticle(0, { position = Vec3(0, 1024, 0), size = 256 })
ParticleGroup:ForEachParticle(callback)
Iterate over all active particles, calling a function for each. If the callback returns a table, those fields are applied back to the particle. All rotation and orientation values are in degrees.

Parameters:

  • callback function Function receiving (index, particleTable) for each active particle.

Usage:

    group:ForEachParticle(function(index, particle)
    return { position = particle.position + Vec3(0, 10, 0) }
end)

Tables

Particle
Structure for a Particle table.

Fields:

  • id int Unique particle ID. Read-only.
  • position Vec3 World position of the particle.
  • velocity Vec3 Directional velocity in world units per second.
  • acceleration Vec3 Acceleration applied to velocity in world units per second squared.
  • size float Current size of the particle in world units. For mesh particles, this also controls the uniform mesh scale.
  • rotation float Current rotation in degrees. Applies to sprite particles only.
  • color Color Current color of the particle.
  • age float Current age of the particle in seconds. Clamped to [0, lifetime] when set.
  • lifetime float Total lifespan of the particle in seconds. Must be greater than 0 when set.
  • ageNormalized float Current age as a normalized value between 0 and 1. Recalculated each frame; direct writes are ignored.
  • subIndex int Current sprite or mesh sub-index within the object slot.
  • objectID ObjID Object slot used to render this particle. Overrides the group default per particle.
  • orientation Rotation Current orientation in degrees along the X, Y, and Z axes. For mesh particles, controls mesh rotation. For sprite particles, a non-zero orientation renders the sprite as a fixed sprite instead of a camera-facing sprite.
  • contactRadius float Half-extent in world units used for AABB contact detection. Default is 128.
  • touchingPlayer bool Read-only. True if the particle's contact radius overlaps Lara's deadly bounds.
  • teleport bool Write-only control. Set to true to suppress interpolation after a large position, size, or rotation change.
generated by TEN-LDoc (a fork of LDoc 1.4.6)