ParticleItem

View source
ceramic.ParticleItem (Class)

Represents a single particle in a particle system.

ParticleItem holds all the data for an individual particle including its physical properties, visual appearance, and animation state. Particles are managed by ParticleEmitter and should not be instantiated directly by user code.

The particle's properties can change over its lifetime through:

  • Linear interpolation between start and end values
  • Physics simulation (velocity, acceleration, drag)
  • Direct property manipulation

Visual synchronization: When visual*Active flags are true, the particle automatically updates the corresponding properties on its visual. This allows the particle system to control the visual appearance efficiently.

See: ParticleEmitter The system that manages particle lifecycles, Visual The visual representation of the particle

Instance Members

visual: Visual

The visual representation of this particle. Can be any Visual subclass (Quad, Mesh, etc.). Managed by the ParticleEmitter's pooling system.

visualScaleActive: Bool

Whether particle scale should be applied to the visual. When true, changes to scaleX/scaleY update visual.scaleX/scaleY.

visualColorActive: Bool

Whether particle color should be applied to the visual. When true, changes to color update visual's color (for Quad/Mesh).

visualPositionActive: Bool

Whether particle position should be applied to the visual. When true, changes to x/y update visual.x/y.

visualRotationActive: Bool

Whether particle angle should be applied to the visual. When true, changes to angle update visual.rotation.

visualAlphaActive: Bool

Whether particle alpha should be applied to the visual. When true, changes to alpha update visual.alpha.

active: Bool

Whether this particle is currently active in the simulation. Inactive particles are in the recycling pool.

lifespan: Float

Total lifetime of the particle in seconds. When age >= lifespan, the particle is recycled. Set to 0 for infinite lifetime.

age: Float

Current age of the particle in seconds. Increases each update by delta time. Used to calculate interpolation progress.

time: Float

The timestamp when this particle was emitted. Uses Timer.now for absolute time reference. Useful for time-based effects or debugging.

random: Float

A random value between 0 and 1 unique to this particle. Generated when emitted, remains constant during lifetime. Useful for randomizing behavior without additional RNG calls.

status: Int

Custom status field for user-defined particle states. Can be used to track special conditions, animation states, or any integer-based status specific to your implementation.

colorRangeActive: Bool

Whether color interpolation over lifetime is active. When true, color interpolates from colorRangeStart to colorRangeEnd.

colorRangeStart: Color

Starting color for interpolation. The particle begins with this color at age 0.

colorRangeEnd: Color

Ending color for interpolation. The particle reaches this color at the end of its lifespan.

color: Color

Current color of the particle. When visualColorActive is true, automatically syncs with visual's color. Supports Quad and Mesh visuals.

accelerationRangeActive: Bool

Whether acceleration interpolation over lifetime is active.

accelerationRangeStartX: Float

Starting X acceleration for interpolation.

accelerationRangeStartY: Float

Starting Y acceleration for interpolation.

accelerationRangeEndX: Float

Ending X acceleration for interpolation.

accelerationRangeEndY: Float

Ending Y acceleration for interpolation.

accelerationX: Float

Current X acceleration in pixels per second squared. Positive values accelerate right, negative left.

accelerationY: Float

Current Y acceleration in pixels per second squared. Positive values accelerate down, negative up. Common use: positive value for gravity effect.

dragRangeActive: Bool

Whether drag interpolation over lifetime is active.

dragRangeStartX: Float

Starting X drag coefficient for interpolation.

dragRangeStartY: Float

Starting Y drag coefficient for interpolation.

dragRangeEndX: Float

Ending X drag coefficient for interpolation.

dragRangeEndY: Float

Ending Y drag coefficient for interpolation.

dragX: Float

Current X drag coefficient. Reduces velocity over time, simulating air resistance. Higher values = more resistance.

dragY: Float

Current Y drag coefficient. Reduces velocity over time, simulating air resistance. Higher values = more resistance.

velocityRangeActive: Bool

Whether velocity interpolation over lifetime is active.

velocityRangeStartX: Float

Starting X velocity for interpolation.

velocityRangeStartY: Float

Starting Y velocity for interpolation.

velocityRangeEndX: Float

Ending X velocity for interpolation.

velocityRangeEndY: Float

Ending Y velocity for interpolation.

velocityX: Float

Current X velocity in pixels per second. Positive = right, negative = left.

velocityY: Float

Current Y velocity in pixels per second. Positive = down, negative = up.

angularVelocityRangeActive: Bool

Whether angular velocity interpolation over lifetime is active.

angularVelocityRangeStart: Float

Starting angular velocity for interpolation.

angularVelocityRangeEnd: Float

Ending angular velocity for interpolation.

angularVelocity: Float

Current angular velocity in degrees per second. Positive = clockwise, negative = counter-clockwise.

angularAccelerationRangeActive: Bool

Whether angular acceleration is active. Note: Currently doesn't support interpolation.

angularAccelerationRangeStart: Float

Starting angular acceleration (unused currently).

angularAccelerationRangeEnd: Float

Ending angular acceleration (unused currently).

angularAcceleration: Float

Angular acceleration in degrees per second squared. Changes angular velocity over time.

angularDrag: Float

Angular drag coefficient. Reduces angular velocity over time. Higher values = more rotational resistance.

scaleRangeActive: Bool

Whether scale interpolation over lifetime is active.

scaleRangeStartX: Float

Starting X scale for interpolation.

scaleRangeStartY: Float

Starting Y scale for interpolation.

scaleRangeEndX: Float

Ending X scale for interpolation.

scaleRangeEndY: Float

Ending Y scale for interpolation.

scaleX: Float

Current X scale factor. When visualScaleActive is true, automatically syncs with visual.scaleX. 1.0 = normal size, 2.0 = double width, 0.5 = half width.

scaleY: Float

Current Y scale factor. When visualScaleActive is true, automatically syncs with visual.scaleY. 1.0 = normal size, 2.0 = double height, 0.5 = half height.

Current X position in pixels. When visualPositionActive is true, automatically syncs with visual.x. Relative to the particle's parent visual.

Current Y position in pixels. When visualPositionActive is true, automatically syncs with visual.y. Relative to the particle's parent visual.

angle: Float

Current rotation angle in degrees. When visualRotationActive is true, automatically syncs with visual.rotation. 0 = no rotation, 90 = quarter turn clockwise.

alphaRangeActive: Bool

Whether alpha interpolation over lifetime is active.

alphaRangeStart: Float

Starting alpha for interpolation. 1.0 = fully opaque.

alphaRangeEnd: Float

Ending alpha for interpolation. 0.0 = fully transparent.

alpha: Float

Current alpha transparency. When visualAlphaActive is true, automatically syncs with visual.alpha. Range: 0.0 (invisible) to 1.0 (opaque).

scale(scaleX: Float, scaleY: Float): Void

Sets both X and Y scale factors at once.

Name Type Description
scaleX Float Horizontal scale factor
scaleY Float Vertical scale factor
pos(x: Float, y: Float): Void

Sets both X and Y position at once.

Name Type Description
x Float Horizontal position in pixels
y Float Vertical position in pixels
reset(): Void

Resets all particle properties to default values.

Called by ParticleEmitter when recycling a particle. Ensures clean state for reused particles.

Private Members

new(): Void

Private constructor - ParticleItems are created and managed by ParticleEmitter. User code should not instantiate particles directly.

Metadata

Name Parameters
:allow ceramic.ParticleEmitter