twodeeparticles

README

twodeeparticles

An engine-agnostic 2D particle system simulator for Go

twodeeparticles does not render particles itself. Any rendering engine can be used, for example Ebiten. For a demo program using Ebiten, see _demo.

License

twodeeparticles is licensed under the MIT license.

Documentation

Overview

Package twodeeparticles contains types to simulate a particle system.

Index

• type DurationOverTimeFunc
• type NormalizedDuration
  • func (t NormalizedDuration) Duration(m time.Duration) time.Duration
• type Particle
  • func (p *Particle) Angle() float64
  • func (p *Particle) Color() color.Color
  • func (p *Particle) Data() interface{}
  • func (p *Particle) Kill()
  • func (p *Particle) Lifetime() time.Duration
  • func (p *Particle) Position() (float64, float64)
  • func (p *Particle) Scale() (float64, float64)
  • func (p *Particle) System() *ParticleSystem
  • func (p *Particle) Velocity() (float64, float64)
• type ParticleColorOverNormalizedTimeFunc
• type ParticleDataOverNormalizedTimeFunc
• type ParticleDeathFunc
• type ParticleSystem
  • func NewParticleSystem() *ParticleSystem
  • func (s *ParticleSystem) Duration(now time.Time) time.Duration
  • func (s *ParticleSystem) ForEachParticle(f ParticleVisitFunc, now time.Time)
  • func (s *ParticleSystem) NumParticles() int
  • func (s *ParticleSystem) Reset()
  • func (s *ParticleSystem) Update(now time.Time)
• type ParticleTwoValuesOverNormalizedTimeFunc
• type ParticleValueOverNormalizedTimeFunc
• type ParticleVisitFunc
• type TwoValuesOverTimeFunc
• type ValueOverTimeFunc

Types

type DurationOverTimeFunc

type DurationOverTimeFunc func(d time.Duration, delta time.Duration) time.Duration

DurationOverTimeFunc is a function that returns a duration after duration d has passed. delta is the duration since the last update (for example, the duration since the last GPU frame.)

type NormalizedDuration

type NormalizedDuration float64

NormalizedDuration is a normalized duration during a longer duration (for example, during a particle's lifetime.) The value is always in the range [0.0,1.0], with 0.0 being the start of the longer duration and 1.0 being the end of the longer duration.

func (NormalizedDuration) Duration

func (t NormalizedDuration) Duration(m time.Duration) time.Duration

Duration converts t to a duration with respect to the longer duration m. If t is 0, it will return 0, and if t is 1, it will return m.

type Particle

type Particle struct {
	// contains filtered or unexported fields
}

A Particle is a part of a particle system.

func (*Particle) Angle

func (p *Particle) Angle() float64

Angle returns p's current rotation angle, in radians.

func (*Particle) Color

func (p *Particle) Color() color.Color

Color returns p's current color.

func (*Particle) Data

func (p *Particle) Data() interface{}

Data returns the arbitrary data that has been assigned to p (see ParticleSystem.DataOverLifetime.)

func (*Particle) Kill

func (p *Particle) Kill()

Kill kills p, even if p's lifetime has not yet been exceeded.

func (*Particle) Lifetime

func (p *Particle) Lifetime() time.Duration

Lifetime returns p's maximum lifetime.

func (*Particle) Position

func (p *Particle) Position() (float64, float64)

Position returns p's current position, in arbitrary units (for example, in pixels), relative to its system's origin.

func (*Particle) Scale

func (p *Particle) Scale() (float64, float64)

Scale returns p's current scale (size multiplier).

func (*Particle) System

func (p *Particle) System() *ParticleSystem

System returns the particle system that p is a part of.

func (*Particle) Velocity

func (p *Particle) Velocity() (float64, float64)

Velocity returns p's current velocity (direction times speed), in arbitrary units (for example, in pixels) per second.

type ParticleColorOverNormalizedTimeFunc

type ParticleColorOverNormalizedTimeFunc func(p *Particle, t NormalizedDuration, delta time.Duration) color.Color

ParticleColorOverNormalizedTimeFunc is a function that returns a color for p after p's duration t has passed. delta is the duration since the last update (for example, the duration since the last GPU frame.)

type ParticleDataOverNormalizedTimeFunc

type ParticleDataOverNormalizedTimeFunc func(old interface{}, t NormalizedDuration, delta time.Duration) interface{}

ParticleDataOverNormalizedTimeFunc is a function that returns arbitrary data for p after p's duration t has passed. The data from previous updates is passed as old and may be modified and returned. For the first update, nil is passed as the old data. delta is the duration since the last update (for example, the duration since the last GPU frame.)

type ParticleDeathFunc

type ParticleDeathFunc func(p *Particle)

ParticleDeathFunc is a function that is called when p has died.

type ParticleSystem

type ParticleSystem struct {
	// MaxParticles limits the total number of particles that are alive at a time. When particles die, new particles may be
	// spawned according to EmissionRateOverTime.
	MaxParticles int

	// DataOverLifetime returns arbitrary data for a particle, over its lifetime. This allows to attach data to the particle
	// and act on it later on. The data returned is not used by the system itself.
	DataOverLifetime ParticleDataOverNormalizedTimeFunc

	// DeathFunc is called when a particle has died. This can be used to clean up the data returned by DataOverLifetime
	// (for example, to return the data back into a pool.)
	DeathFunc ParticleDeathFunc

	// UpdateFunc is called to update a particle during its lifetime. This can be used to Particle.Kill it when certain
	// conditions are met.
	UpdateFunc ParticleVisitFunc

	// EmissionRateOverTime returns the emission rate of the system, in particles/sec, over the duration of the system.
	//
	// If EmissionRateOverTime is nil, no particles will spawn.
	EmissionRateOverTime ValueOverTimeFunc

	// EmissionPositionOverTime returns the initial position of a particle that is being spawned, over the duration
	// of the system. The position is measured in arbitrary units (for example, in pixels), and is relative to the
	// system's origin.
	//
	// If EmissionPositionOverTime is nil, particles will spawn at the origin.
	EmissionPositionOverTime TwoValuesOverTimeFunc

	// LifetimeOverTime returns the lifetime of a particle that is being spawned, in seconds, over the duration of the
	// system. After the particle has lived for that many seconds, it will die automatically.
	//
	// If LifetimeOverTime is nil, particles will die after 1 sec.
	LifetimeOverTime DurationOverTimeFunc

	// VelocityOverLifetime returns a particle's velocity (direction times speed), in arbitrary units per second,
	// over its lifetime.
	//
	// If VelocityOverLifetime is nil, particles will not move.
	VelocityOverLifetime ParticleTwoValuesOverNormalizedTimeFunc

	// ScaleOverLifetime returns a particle's scale (size multiplier), over its lifetime.
	//
	// If ScaleOverLifetime is nil, particles will use (1.0,1.0).
	ScaleOverLifetime ParticleTwoValuesOverNormalizedTimeFunc

	// ColorOverLifetime returns a particle's color, over its lifetime.
	//
	// If ColorOverLifetime is nil, particles will use color.White.
	ColorOverLifetime ParticleColorOverNormalizedTimeFunc

	// RotationOverLifetime returns a particle's angular velocity, in radians, over its lifetime.
	//
	// If RotationOverLifetime is nil, particles will not rotate.
	RotationOverLifetime ParticleValueOverNormalizedTimeFunc
	// contains filtered or unexported fields
}

A ParticleSystem simulates a number of particles. Various functions are called to customize the behavior of the particles.

The position of a particle is always relative to its system's origin. In other words, a particle system maintains its own frame of reference. Particles are not simulated in "world space." However, when particles are actually drawn on screen, the origin of the particle system can be moved freely, thus emulating a simulation in world space.

func NewParticleSystem

func NewParticleSystem() *ParticleSystem

NewParticleSystem returns a new particle system.

func (*ParticleSystem) Duration

func (s *ParticleSystem) Duration(now time.Time) time.Duration

Duration returns the duration of the system at now, that is, how long the system has been active. now should usually be time.Now().

func (*ParticleSystem) ForEachParticle

func (s *ParticleSystem) ForEachParticle(f ParticleVisitFunc, now time.Time)

ForEachParticle calls f for each alive particle in the system. now should usually be time.Now().

func (*ParticleSystem) NumParticles

func (s *ParticleSystem) NumParticles() int

NumParticles returns the number of alive particles.

func (*ParticleSystem) Reset

func (s *ParticleSystem) Reset()

Reset kills all alive particles and completely resets the system. DeathFunc will be called for all particles that were alive.

func (*ParticleSystem) Update

func (s *ParticleSystem) Update(now time.Time)

Update updates the system. now should usually be time.Now().

type ParticleTwoValuesOverNormalizedTimeFunc

type ParticleTwoValuesOverNormalizedTimeFunc func(p *Particle, t NormalizedDuration, delta time.Duration) (float64, float64)

ParticleTwoValuesOverNormalizedTimeFunc is a function that returns two values for p after p's duration t has passed. delta is the duration since the last update (for example, the duration since the last GPU frame.)

type ParticleValueOverNormalizedTimeFunc

type ParticleValueOverNormalizedTimeFunc func(p *Particle, t NormalizedDuration, delta time.Duration) float64

ParticleValueOverNormalizedTimeFunc is a function that returns a value for p after p's duration t has passed. delta is the duration since the last update (for example, the duration since the last GPU frame.)

type ParticleVisitFunc

type ParticleVisitFunc func(p *Particle, t NormalizedDuration, delta time.Duration)

ParticleVisitFunc is a function that is called for p after p's duration t has passed, when looping over all particles in the system using ParticleSystem.ForEachParticle. delta is the duration since the last update (for example, the duration since the last GPU frame.)

type TwoValuesOverTimeFunc

type TwoValuesOverTimeFunc func(d time.Duration, delta time.Duration) (float64, float64)

TwoValuesOverTimeFunc is a function that returns two values after duration d has passed. delta is the duration since the last update (for example, the duration since the last GPU frame.)

type ValueOverTimeFunc

type ValueOverTimeFunc func(d time.Duration, delta time.Duration) float64

ValueOverTimeFunc is a function that returns a value after duration d has passed. delta is the duration since the last update (for example, the duration since the last GPU frame.)