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

• Variables
• 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() Vector
  • func (p *Particle) Scale() Vector
  • func (p *Particle) System() *ParticleSystem
  • func (p *Particle) Velocity() Vector
• type ParticleColorOverNormalizedTimeFunc
• type ParticleDataOverNormalizedTimeFunc
• type ParticleDeathFunc
• type ParticleSystem
  • func NewSystem() *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) Spawn(num int)
  • func (s *ParticleSystem) Update(now time.Time)
• type ParticleValueOverNormalizedTimeFunc
• type ParticleVectorOverNormalizedTimeFunc
• type ParticleVisitFunc
• type ValueOverTimeFunc
• type Vector
  • func (v Vector) Add(v2 Vector) Vector
  • func (v Vector) Magnitude() float64
  • func (v Vector) Multiply(d float64) Vector
  • func (v Vector) Normalize() Vector
  • func (v Vector) TryNormalize() (Vector, bool)
• type VectorOverTimeFunc

Variables

var (
	// ZeroVector is a vector with a magnitude of zero.
	ZeroVector = Vector{0.0, 0.0}

	// OneVector is a vector whose components are all one.
	OneVector = Vector{1.0, 1.0}
)

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() Vector

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() Vector

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() Vector

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 being 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/second, 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 VectorOverTimeFunc

	// LifetimeOverTime returns the lifetime of a particle that is being spawned, over the duration of the system.
	// After the duration has passed, the particle will die automatically.
	//
	// If LifetimeOverTime is nil, particles will die after 1 second.
	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 ParticleVectorOverNormalizedTimeFunc

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

	// 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 NewSystem

func NewSystem() *ParticleSystem

NewSystem 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) Spawn

func (s *ParticleSystem) Spawn(num int)

Spawn increases the number of particles to emit on the next Update by num. This can be used to instantly spawn a number of particles at any time, regardless of EmissionRateOverTime.

func (*ParticleSystem) Update

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

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

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 ParticleVectorOverNormalizedTimeFunc

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

ParticleVectorOverNormalizedTimeFunc is a function that returns a vector 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 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.)

type Vector

type Vector struct {
	X float64
	Y float64
}

A Vector is a geometric entity that has a direction and a length.

func (Vector) Add

func (v Vector) Add(v2 Vector) Vector

Add returns a vector whose components are component-wise additions of v and v2.

func (Vector) Magnitude

func (v Vector) Magnitude() float64

Magnitude returns the length of v.

func (Vector) Multiply

func (v Vector) Multiply(d float64) Vector

Multiply returns a vector whose components are v's components multiplied by d.

func (Vector) Normalize

func (v Vector) Normalize() Vector

Normalize returns a vector that has the same direction as v, but whose length is one. In other words, it returns a unit vector with the same direction as v. If v has a length of zero, it will panic.

func (Vector) TryNormalize

func (v Vector) TryNormalize() (Vector, bool)

TryNormalize returns a vector that has the same direction as v, but whose length is one. In other words, it returns a unit vector with the same direction as v. If v has a length of zero, it will return v and false, else the described result and true.

type VectorOverTimeFunc

type VectorOverTimeFunc func(d time.Duration, delta time.Duration) Vector

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