GPUParticles2D

package
v0.0.0-...-357ca8a Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 20, 2025 License: MIT Imports: 32 Imported by: 0

Documentation

Overview

2D particle node used to create a variety of particle systems and effects. GPUParticles2D features an emitter that generates some number of particles at a given rate.

Use the ProcessMaterial property to add a ParticleProcessMaterial to configure particle appearance and behavior. Alternatively, you can add a ShaderMaterial which will be applied to all particles.

2D particles can optionally collide with LightOccluder2D, but they don't collide with PhysicsBody2D nodes.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Advanced 

type Advanced = class

Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.

type Any 

type Any interface {
	gd.IsClass
	AsGPUParticles2D() Instance
}

type DrawOrder 

type DrawOrder int //gd:GPUParticles2D.DrawOrder

const (
	// Particles are drawn in the order emitted.
	DrawOrderIndex DrawOrder = 0
	// Particles are drawn in order of remaining lifetime. In other words, the particle with the highest lifetime is drawn at the front.
	DrawOrderLifetime DrawOrder = 1
	// Particles are drawn in reverse order of remaining lifetime. In other words, the particle with the lowest lifetime is drawn at the front.
	DrawOrderReverseLifetime DrawOrder = 2
)

type EmitFlags 

type EmitFlags int //gd:GPUParticles2D.EmitFlags

const (
	// Particle starts at the specified position.
	EmitFlagPosition EmitFlags = 1
	// Particle starts with specified rotation and scale.
	EmitFlagRotationScale EmitFlags = 2
	// Particle starts with the specified velocity vector, which defines the emission direction and speed.
	EmitFlagVelocity EmitFlags = 4
	// Particle starts with specified color.
	EmitFlagColor EmitFlags = 8
	// Particle starts with specified CUSTOM data.
	EmitFlagCustom EmitFlags = 16
)

type Expanded 

type Expanded = MoreArgs

type Extension 

type Extension[T gdclass.Interface] struct{ gdclass.Extension[T, Instance] }

Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension

func (*Extension[T]) AsCanvasItem 

func (self *Extension[T]) AsCanvasItem() CanvasItem.Instance

func (*Extension[T]) AsGPUParticles2D 

func (self *Extension[T]) AsGPUParticles2D() Instance

func (*Extension[T]) AsNode 

func (self *Extension[T]) AsNode() Node.Instance

func (*Extension[T]) AsNode2D 

func (self *Extension[T]) AsNode2D() Node2D.Instance

func (*Extension[T]) AsObject 

func (self *Extension[T]) AsObject() [1]gd.Object

type ID 

type ID Object.ID

ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.

func (ID) Instance 

func (id ID) Instance() (Instance, bool)

type Instance 

type Instance [1]gdclass.GPUParticles2D

Instance of the class with convieniently typed arguments and results. 

var Nil Instance

Nil is a nil/null instance of the class. Equivalent to the zero value.

func New 

func New() Instance

func (Instance) Amount 

func (self Instance) Amount() int

The number of particles to emit in one emission cycle. The effective emission rate is (amount * amount_ratio) / lifetime particles per second. Higher values will increase GPU requirements, even if not all particles are visible at a given time or if AmountRatio is decreased.

Note: Changing this value will cause the particle system to restart. To avoid this, change AmountRatio instead.

func (Instance) AmountRatio 

func (self Instance) AmountRatio() Float.X

The ratio of particles that should actually be emitted. If set to a value lower than 1.0, this will set the amount of emitted particles throughout the lifetime to amount * amount_ratio. Unlike changing Amount, changing AmountRatio while emitting does not affect already-emitted particles and doesn't cause the particle system to restart. AmountRatio can be used to create effects that make the number of emitted particles vary over time.

Note: Reducing the AmountRatio has no performance benefit, since resources need to be allocated and processed for the total Amount of particles regardless of the AmountRatio. If you don't intend to change the number of particles emitted while the particles are emitting, make sure AmountRatio is set to 1 and change Amount to your liking instead.

func (Instance) AsCanvasItem 

func (self Instance) AsCanvasItem() CanvasItem.Instance

func (Instance) AsGPUParticles2D 

func (self Instance) AsGPUParticles2D() Instance

func (Instance) AsNode 

func (self Instance) AsNode() Node.Instance

func (Instance) AsNode2D 

func (self Instance) AsNode2D() Node2D.Instance

func (Instance) AsObject 

func (self Instance) AsObject() [1]gd.Object

func (Instance) CaptureRect 

func (self Instance) CaptureRect() Rect2.PositionSize

Returns a rectangle containing the positions of all existing particles.

Note: When using threaded rendering this method synchronizes the rendering thread. Calling it often may have a negative impact on performance.

func (Instance) CollisionBaseSize 

func (self Instance) CollisionBaseSize() Float.X

Multiplier for particle's collision radius. 1.0 corresponds to the size of the sprite. If particles appear to sink into the ground when colliding, increase this value. If particles appear to float when colliding, decrease this value. Only effective if ParticleProcessMaterial.CollisionMode is [Particleprocessmaterial.CollisionRigid] or [Particleprocessmaterial.CollisionHideOnContact].

Note: Particles always have a spherical collision shape.

func (Instance) ConvertFromParticles 

func (self Instance) ConvertFromParticles(particles Node.Instance)

Sets this node's properties to match a given CPUParticles2D node.

func (Instance) DrawOrder 

func (self Instance) DrawOrder() DrawOrder

Particle draw order.

func (Instance) EmitParticle 

func (self Instance) EmitParticle(xform Transform2D.OriginXY, velocity Vector2.XY, color Color.RGBA, custom Color.RGBA, flags int)

Emits a single particle. Whether 'xform', 'velocity', 'color' and 'custom' are applied depends on the value of 'flags'. See EmitFlags.

The default ParticleProcessMaterial will overwrite 'color' and use the contents of 'custom' as (rotation, age, animation, lifetime).

Note: EmitParticle is only supported on the Forward+ and Mobile rendering methods, not Compatibility.

func (Instance) Emitting 

func (self Instance) Emitting() bool

If true, particles are being emitted. Emitting can be used to start and stop particles from emitting. However, if OneShot is true setting Emitting to true will not restart the emission cycle unless all active particles have finished processing. Use the OnFinished signal to be notified once all active particles finish processing.

Note: For OneShot emitters, due to the particles being computed on the GPU, there may be a short period after receiving the OnFinished signal during which setting this to true will not restart the emission cycle.

Tip: If your OneShot emitter needs to immediately restart emitting particles once OnFinished signal is received, consider calling Restart instead of setting Emitting.

func (Instance) Explosiveness 

func (self Instance) Explosiveness() Float.X

How rapidly particles in an emission cycle are emitted. If greater than 0, there will be a gap in emissions before the next cycle begins.

func (Instance) FixedFps 

func (self Instance) FixedFps() int

The particle system's frame rate is fixed to a value. For example, changing the value to 2 will make the particles render at 2 frames per second. Note this does not slow down the simulation of the particle system itself.

func (Instance) FractDelta 

func (self Instance) FractDelta() bool

If true, results in fractional delta calculation which has a smoother particles display effect.

func (Instance) ID 

func (self Instance) ID() ID

func (Instance) InterpToEnd 

func (self Instance) InterpToEnd() Float.X

Causes all the particles in this node to interpolate towards the end of their lifetime.

Note: This only works when used with a ParticleProcessMaterial. It needs to be manually implemented for custom process shaders.

func (Instance) Interpolate 

func (self Instance) Interpolate() bool

Enables particle interpolation, which makes the particle movement smoother when their FixedFps is lower than the screen refresh rate.

func (Instance) Lifetime 

func (self Instance) Lifetime() Float.X

The amount of time each particle will exist (in seconds). The effective emission rate is (amount * amount_ratio) / lifetime particles per second.

func (Instance) LocalCoords 

func (self Instance) LocalCoords() bool

If true, particles use the parent node's coordinate space (known as local coordinates). This will cause particles to move and rotate along the GPUParticles2D node (and its parents) when it is moved or rotated. If false, particles use global coordinates; they will not move or rotate along the GPUParticles2D node (and its parents) when it is moved or rotated.

func (Instance) MoreArgs 

func (self Instance) MoreArgs() MoreArgs

MoreArgs enables certain functions to be called with additional 'optional' arguments.

func (Instance) OnFinished 

func (self Instance) OnFinished(cb func(), flags ...Signal.Flags)

Emitted when all active particles have finished processing. To immediately restart the emission cycle, call Restart.

This signal is never emitted when OneShot is disabled, as particles will be emitted and processed continuously.

Note: For OneShot emitters, due to the particles being computed on the GPU, there may be a short period after receiving the signal during which setting Emitting to true will not restart the emission cycle. This delay is avoided by instead calling Restart.

func (Instance) OneShot 

func (self Instance) OneShot() bool

If true, only one emission cycle occurs. If set true during a cycle, emission will stop at the cycle's end.

func (Instance) Preprocess 

func (self Instance) Preprocess() Float.X

Particle system starts as if it had already run for this many seconds.

Note: This can be very expensive if set to a high number as it requires running the particle shader a number of times equal to the FixedFps (or 30, if FixedFps is 0) for every second. In extreme cases it can even lead to a GPU crash due to the volume of work done in a single frame.

func (Instance) ProcessMaterial 

func (self Instance) ProcessMaterial() Material.Instance

Material for processing particles. Can be a ParticleProcessMaterial or a ShaderMaterial.

func (Instance) Randomness 

func (self Instance) Randomness() Float.X

Emission lifetime randomness ratio.

func (Instance) RequestParticlesProcess 

func (self Instance) RequestParticlesProcess(process_time Float.X)

Requests the particles to process for extra process time during a single frame.

Useful for particle playback, if used in combination with UseFixedSeed or by calling Restart with parameter keep_seed set to true.

func (Instance) Restart 

func (self Instance) Restart()

Restarts the particle emission cycle, clearing existing particles. To avoid particles vanishing from the viewport, wait for the OnFinished signal before calling.

Note: The OnFinished signal is only emitted by OneShot emitters.

If 'keep_seed' is true, the current random seed will be preserved. Useful for seeking and playback.

func (Instance) Seed 

func (self Instance) Seed() int

Sets the random seed used by the particle system. Only effective if UseFixedSeed is true.

func (Instance) SetAmount 

func (self Instance) SetAmount(value int)

SetAmount sets the property returned by [GetAmount].

func (Instance) SetAmountRatio 

func (self Instance) SetAmountRatio(value Float.X)

SetAmountRatio sets the property returned by [GetAmountRatio].

func (Instance) SetCollisionBaseSize 

func (self Instance) SetCollisionBaseSize(value Float.X)

SetCollisionBaseSize sets the property returned by [GetCollisionBaseSize].

func (Instance) SetDrawOrder 

func (self Instance) SetDrawOrder(value DrawOrder)

SetDrawOrder sets the property returned by [GetDrawOrder].

func (Instance) SetEmitting 

func (self Instance) SetEmitting(value bool)

SetEmitting sets the property returned by [IsEmitting].

func (Instance) SetExplosiveness 

func (self Instance) SetExplosiveness(value Float.X)

SetExplosiveness sets the property returned by [GetExplosivenessRatio].

func (Instance) SetFixedFps 

func (self Instance) SetFixedFps(value int)

SetFixedFps sets the property returned by [GetFixedFps].

func (Instance) SetFractDelta 

func (self Instance) SetFractDelta(value bool)

SetFractDelta sets the property returned by [GetFractionalDelta].

func (Instance) SetInterpToEnd 

func (self Instance) SetInterpToEnd(value Float.X)

SetInterpToEnd sets the property returned by [GetInterpToEnd].

func (Instance) SetInterpolate 

func (self Instance) SetInterpolate(value bool)

SetInterpolate sets the property returned by [GetInterpolate].

func (Instance) SetLifetime 

func (self Instance) SetLifetime(value Float.X)

SetLifetime sets the property returned by [GetLifetime].

func (Instance) SetLocalCoords 

func (self Instance) SetLocalCoords(value bool)

SetLocalCoords sets the property returned by [GetUseLocalCoordinates].

func (*Instance) SetObject 

func (self *Instance) SetObject(obj [1]gd.Object) bool

func (Instance) SetOneShot 

func (self Instance) SetOneShot(value bool)

SetOneShot sets the property returned by [GetOneShot].

func (Instance) SetPreprocess 

func (self Instance) SetPreprocess(value Float.X)

SetPreprocess sets the property returned by [GetPreProcessTime].

func (Instance) SetProcessMaterial 

func (self Instance) SetProcessMaterial(value Material.Instance)

SetProcessMaterial sets the property returned by [GetProcessMaterial].

func (Instance) SetRandomness 

func (self Instance) SetRandomness(value Float.X)

SetRandomness sets the property returned by [GetRandomnessRatio].

func (Instance) SetSeed 

func (self Instance) SetSeed(value int)

SetSeed sets the property returned by [GetSeed].

func (Instance) SetSpeedScale 

func (self Instance) SetSpeedScale(value Float.X)

SetSpeedScale sets the property returned by [GetSpeedScale].

func (Instance) SetSubEmitter 

func (self Instance) SetSubEmitter(value string)

SetSubEmitter sets the property returned by [GetSubEmitter].

func (Instance) SetTexture 

func (self Instance) SetTexture(value Texture2D.Instance)

SetTexture sets the property returned by [GetTexture].

func (Instance) SetTrailEnabled 

func (self Instance) SetTrailEnabled(value bool)

SetTrailEnabled sets the property returned by [IsTrailEnabled].

func (Instance) SetTrailLifetime 

func (self Instance) SetTrailLifetime(value Float.X)

SetTrailLifetime sets the property returned by [GetTrailLifetime].

func (Instance) SetTrailSectionSubdivisions 

func (self Instance) SetTrailSectionSubdivisions(value int)

SetTrailSectionSubdivisions sets the property returned by [GetTrailSectionSubdivisions].

func (Instance) SetTrailSections 

func (self Instance) SetTrailSections(value int)

SetTrailSections sets the property returned by [GetTrailSections].

func (Instance) SetUseFixedSeed 

func (self Instance) SetUseFixedSeed(value bool)

SetUseFixedSeed sets the property returned by [GetUseFixedSeed].

func (Instance) SetVisibilityRect 

func (self Instance) SetVisibilityRect(value Rect2.PositionSize)

SetVisibilityRect sets the property returned by [GetVisibilityRect].

func (Instance) SpeedScale 

func (self Instance) SpeedScale() Float.X

Particle system's running speed scaling ratio. A value of 0 can be used to pause the particles.

func (Instance) SubEmitter 

func (self Instance) SubEmitter() string

Path to another GPUParticles2D node that will be used as a subemitter (see ParticleProcessMaterial.SubEmitterMode). Subemitters can be used to achieve effects such as fireworks, sparks on collision, bubbles popping into water drops, and more.

Note: When SubEmitter is set, the target GPUParticles2D node will no longer emit particles on its own.

func (Instance) Texture 

func (self Instance) Texture() Texture2D.Instance

Particle texture. If null, particles will be squares with a size of 1×1 pixels.

Note: To use a flipbook texture, assign a new CanvasItemMaterial to the GPUParticles2D's CanvasItem.Material property, then enable CanvasItemMaterial.ParticlesAnimation and set CanvasItemMaterial.ParticlesAnimHFrames, CanvasItemMaterial.ParticlesAnimVFrames, and CanvasItemMaterial.ParticlesAnimLoop to match the flipbook texture.

func (Instance) TrailEnabled 

func (self Instance) TrailEnabled() bool

If true, enables particle trails using a mesh skinning system.

Note: Unlike GPUParticles3D, the number of trail sections and subdivisions is set with the TrailSections and TrailSectionSubdivisions properties.

func (Instance) TrailLifetime 

func (self Instance) TrailLifetime() Float.X

The amount of time the particle's trail should represent (in seconds). Only effective if TrailEnabled is true.

func (Instance) TrailSectionSubdivisions 

func (self Instance) TrailSectionSubdivisions() int

The number of subdivisions to use for the particle trail rendering. Higher values can result in smoother trail curves, at the cost of performance due to increased mesh complexity. See also TrailSections. Only effective if TrailEnabled is true.

func (Instance) TrailSections 

func (self Instance) TrailSections() int

The number of sections to use for the particle trail rendering. Higher values can result in smoother trail curves, at the cost of performance due to increased mesh complexity. See also TrailSectionSubdivisions. Only effective if TrailEnabled is true.

func (Instance) UseFixedSeed 

func (self Instance) UseFixedSeed() bool

If true, particles will use the same seed for every simulation using the seed defined in Seed. This is useful for situations where the visual outcome should be consistent across replays, for example when using Movie Maker mode.

func (Instance) Virtual 

func (self Instance) Virtual(name string) reflect.Value

func (Instance) VisibilityRect 

func (self Instance) VisibilityRect() Rect2.PositionSize

The Rect2.PositionSize that determines the node's region which needs to be visible on screen for the particle system to be active.

Grow the rect if particles suddenly appear/disappear when the node enters/exits the screen. The Rect2.PositionSize can be grown via code or with the Particles → Generate Visibility Rect editor tool.

type MoreArgs 

type MoreArgs [1]gdclass.GPUParticles2D

MoreArgs is a container for Instance functions with additional 'optional' arguments.

func (MoreArgs) Restart 

func (self MoreArgs) Restart(keep_seed bool)

Restarts the particle emission cycle, clearing existing particles. To avoid particles vanishing from the viewport, wait for the OnFinished signal before calling.

Note: The OnFinished signal is only emitted by OneShot emitters.

If 'keep_seed' is true, the current random seed will be preserved. Useful for seeking and playback.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.