Plugin for Godot 4¶
Requirements¶
Godot 4.1 or higher
Installation¶
Extract the addons folder from the plugin archive.
Move the addons folder into your Godot project’s root folder.
Start the Godot editor and enable the plugin in the project settings.
It may be necessary to restart the Godot editor after enabling the plugin.
Usage¶
Importing effects¶
Save the effect you created in Pixelpart as a .ppfx file and place it inside the folder of your Godot project. Then in Godot, import the effect file as a Pixelpart Effect. You can set a scale value here if the effect appears too small or too large when imported into Godot.
Playing effect¶
In order to actually play the effect, create a new PixelpartEffect node in your scene (PixelpartEffect2D for 2D scenes) and move the imported effect asset onto the Effect field in the node’s inspector window. The effect will now be played inside you game and you can use the effect node like any other Node3D or Node2D node.
Scripting¶
An effect and its particle emitters, particle types, force fields and colliders can be controlled dynamically from GDScript.
PixelpartEffect(2D)¶
The PixelpartEffect
class and its 2D equivalent PixelpartEffect2D
are responsible for playing a single effect. They provide means to pause and resume the effect, to modify effect inputs and to access scene objects of the effect.
Properties¶
PixelpartEffectResource effect
The attached effect resource.
bool playing
Whether the effect is currently playing or not.
bool loop
Whether the effect restarts automatically after time
loop_time
.float loop_time
Time after which the effect loops (only effective if
loop = true
).float speed
How fast the effect is being played.
float frame_rate
At which rate the effect is simulated, in frames per second.
Dictionary inputs
Dictionary of effect input values. Do not use to change effect inputs at runtime, use
set_input_
methods instead.bool flip_h
Whether the effect is flipped horizontally. Only available for
PixelpartEffect2D
.bool flip_v
Whether the effect is flipped vertically. Only available for
PixelpartEffect2D
.
Methods¶
void set_effect(PixelpartEffectResource effect_res)
Sets
effect
.PixelpartEffectResource get_effect()
Returns
effect
.void play(bool p)
Starts playing the effect or pauses the effect if
p = false
.void pause()
Pauses the effect.
void restart()
Restarts the effect and removes all existing particles.
void reset()
Restarts the effect, but does not remove existing particles.
bool is_playing()
Returns whether the effect is currently playing or is paused.
float get_time()
Returns the time in seconds since the effect has started playing.
void set_loop(bool l)
Sets
loop
.bool get_loop()
Returns
loop
.void set_loop_time(float l)
Sets
loop_time
.float get_loop_time()
Returns
loop_time
.void set_speed(float s)
Sets
speed
.float get_speed()
Returns
speed
.void set_frame_rate(float r)
Sets
frame_rate
.float get_frame_rate()
Returns
frame_rate
.void set_inputs(Dictionary in)
Sets
inputs
.float get_inputs()
Returns
inputs
.void set_flip_h(bool flip)
Sets
flip_h
. Only available forPixelpartEffect2D
.void set_flip_v(bool flip)
Sets
flip_v
. Only available forPixelpartEffect2D
.bool get_flip_h()
Returns
flip_h
. Only available forPixelpartEffect2D
.bool get_flip_v()
Returns
flip_v
. Only available forPixelpartEffect2D
.void set_input_bool(String name, bool value)
Sets the effect input
name
to the given value. The effect input must be of typebool
.void set_input_int(String name, int value)
Sets the effect input
name
to the given value. The effect input must be of typeint
.void set_input_float(String name, float value)
Sets the effect input
name
to the given value. The effect input must be of typefloat
.void set_input_float2(String name, Vector2 value)
Sets the effect input
name
to the given value. The effect input must be of typeVector2
.void set_input_float3(String name, Vector3 value)
Sets the effect input
name
to the given value. The effect input must be of typeVector3
.void set_input_float4(String name, Vector4 value)
Sets the effect input
name
to the given value. The effect input must be of typeVector4
.bool get_input_bool(String name)
Returns the value of the effect input
name
. The effect input must be of typebool
.int get_input_int(String name)
Returns the value of the effect input
name
. The effect input must be of typeint
.float get_input_float(String name)
Returns the value of the effect input
name
. The effect input must be of typefloat
.Vector2 get_input_float2(String name)
Returns the value of the effect input
name
. The effect input must be of typeVector2
.Vector3 get_input_float3(String name)
Returns the value of the effect input
name
. The effect input must be of typeVector3
.Vector4 get_input_float4(String name)
Returns the value of the effect input
name
. The effect input must be of typeVector4
.int get_input_type(String name)
Returns the type of the effect input
name
or-1
if the effect input cannot be found.Array get_input_names()
Returns the names of available effect inputs.
void spawn_particles(String particleTypeName, int count)
Instantly generates
count
particles of the type with the nameparticleTypeName
.float get_import_scale()
Returns the scale applied to the effect resource.
PixelpartParticleEmitter find_particle_emitter(String name)
Returns the particle emitter with the given name or
null
if no particle emitter with this name exists.PixelpartParticleType find_particle_type(String name)
Returns the particle type with the given name or
null
if no particle type with this name exists.PixelpartForceField find_force_field(String name)
Returns the force field with the given name or
null
if no force field with this name exists.PixelpartCollider find_collider(String name)
Returns the collider with the given name or
null
if no collider with this name exists.PixelpartParticleEmitter get_particle_emitter(int id)
Returns the particle emitter with the given id or
null
if no particle emitter with this id exists.PixelpartParticleType get_particle_type(int id)
Returns the particle type with the given id or
null
if no particle type with this id exists.PixelpartForceField get_force_field(int id)
Returns the force field with the given id or
null
if no field field with this id exists.PixelpartCollider get_collider(int id)
Returns the collider with the given id or
null
if no collider with this id exists.PixelpartParticleEmitter get_particle_emitter_at_index(int index)
Returns the particle emitter at the given index, starting with 0, or
null
if no particle emitter exists at this index.PixelpartParticleType get_particle_type_at_index(int index)
Returns the particle type at the given index, starting with 0, or
null
if no particle type exists at this index.PixelpartForceField get_force_field_at_index(int index)
Returns the force field at the given index, starting with 0, or
null
if no force field exists at this index.PixelpartCollider get_collider_at_index(int index)
Returns the collider at the given index, starting with 0, or
null
if no collider exists at this index.
PixelpartParticleEmitter¶
The PixelpartParticleEmitter
class provides access to the properties of a particle emitter.
Properties¶
float lifetime_start
When the emitter becomes active, in seconds.
float lifetime_duration
How long the emitter stays active, in seconds.
bool repeat
Whether the emitter continues to stay active after
lifetime_duration
has passed.int shape
Shape of the emitter area.
int distribution
How particles are distributed in the emitter area.
int grid_order
In which order particles are spawned in
GRID_ORDERED
particle distribution mode.int emission_mode
How particles are created over the lifetime of the emitter.
int direction_mode
In which direction particles are accelerated towards in relation to the emitter area.
Methods¶
int get_id()
Returns the ID of the emitter.
int get_parent_id()
Returns the ID of the parent particle type.
String get_name()
Returns the name of the emitter.
void set_lifetime_start(float time)
Sets
lifetime_start
.void set_lifetime_duration(float time)
Sets
lifetime_duration
.void set_repeat(bool value)
Sets
repeat
.float get_lifetime_start()
Returns
lifetime_start
.float get_lifetime_duration()
Returns
lifetime_duration
.bool get_repeat()
Returns
repeat
.bool is_active()
Returns whether the emitter is active and spawns particles at the current point in time.
float get_local_time()
Returns the time fraction the emitter has been active for, in range 0.0 (0%) to 1.0 (100%).
PixelpartAnimatedPropertyFloat3 get_position()
Returns the motion path of the emitter.
void set_shape(int type)
Sets
shape
.int get_shape()
Returns
shape
.void add_shape_point(Vector3 point)
Adds a new point to the emitter shape. Only applicable for emitter shape
PATH
.void remove_shape_point(int index)
Removes the point at
index
from the emitter shape. Only applicable for emitter shapePATH
.void set_shape_point(int index, Vector3 point)
Changes the location of the point at
index
in the emitter shape. Only applicable for emitter shapePATH
.int get_num_shape_points()
Returns the number of points in the emitter shape. Only applicable for emitter shape
PATH
.Vector3 get_shape_point(int index)
Returns the location of the point at
index
in the emitter shape. Only applicable for emitter shapePATH
.PixelpartAnimatedPropertyFloat3 get_size()
Returns the animation property for the size of the emitter area.
PixelpartAnimatedPropertyFloat3 get_orientation()
Returns the animation property for the orientation of the emitter area in degrees.
void set_distribution(int mode)
Sets
distribution
.int get_distribution()
Returns
distribution
.void set_grid_order(int mode)
Sets
grid_order
.int get_grid_order()
Returns
grid_order
.void set_grid_size(int width, int height, int depth)
Changes the number of grid cells in the emitter shape for particle distribution modes
GRID_RANDOM
andGRID_ORDERED
.int get_grid_width()
Returns the number of grid cells in the emitter shape in the right direction.
int get_grid_height()
Returns the number of grid cells in the emitter shape in the up direction.
int get_grid_depth()
Returns the number of grid cells in the emitter shape in the forward direction.
void set_emission_mode(int mode)
Sets
emission_mode
.int get_emission_mode()
Returns
emission_mode
.void set_direction_mode(int mode)
Sets
direction_mode
.int get_direction_mode()
Returns
direction_mode
.PixelpartAnimatedPropertyFloat3 get_direction()
Returns the animation property for the emission direction in degrees.
PixelpartAnimatedPropertyFloat get_spread()
Returns the animation property for the variance in emission direction in degrees.
PixelpartParticleType¶
Properties¶
bool position_relative
Whether the position of particles is tied to the position of their emitter.
int rotation_mode
Whether the
rotation
property is interpreted as an angle or an angular velocity (ANGLE
,VELOCITY
).int alignment_mode
To which object or vector particles align (
NONE
,CAMERA
,MOTION
,EMISSION
,EMITTER
).bool visible
Whether the particles of this particle type are visible.
int layer
Layer on which the particles are drawn, starting at 0.
Methods¶
int get_id()
Returns the ID of the particle type.
int get_parent_id()
Returns the ID of the parent emitter.
String get_name()
Returns the name of the particle type.
PixelpartAnimatedPropertyFloat3 get_position()
Returns the motion path of particles.
PixelpartAnimatedPropertyFloat get_num_particles()
Returns the animation property for the number of the particles spawned.
PixelpartAnimatedPropertyFloat get_lifespan()
Returns the animation property for the lifespan of particles.
PixelpartStaticPropertyFloat get_lifespan_variance()
Returns the property for the variance in the lifespan of particles.
void set_position_relative(bool mode)
Sets
position_relative
.bool is_position_relative()
Returns
position_relative
.PixelpartStaticPropertyFloat get_motion_path_force()
Returns the property for how much the motion path influences the particle position.
PixelpartAnimatedPropertyFloat get_initial_velocity()
Returns the animation property for the starting velocity of particles.
PixelpartAnimatedPropertyFloat get_inherited_velocity()
Returns the animation property for how much speed particles inherit from the parent particle or emitter.
PixelpartStaticPropertyFloat get_velocity_variance()
Returns the property for how much the velocities of particles vary.
PixelpartAnimatedPropertyFloat get_acceleration()
Returns the animation property for the linear acceleration of particles over their lifetime.
PixelpartAnimatedPropertyFloat get_radial_acceleration()
Returns the animation property for the radial acceleration of particles over their lifetime.
void set_rotation_mode(int mode)
Sets
rotation_mode
.int get_rotation_mode()
Returns
rotation_mode
.void set_alignment_mode(int mode)
Sets
alignment_mode
.int get_alignment_mode()
Returns
alignment_mode
.PixelpartAnimatedPropertyFloat3 get_initial_rotation()
Returns the animation property for the starting rotation of particles.
PixelpartAnimatedPropertyFloat3 get_rotation()
Returns the animation property for the rotation of particles over their lifetime.
PixelpartAnimatedPropertyFloat3 get_rotation_by_speed()
Returns the animation property for the particle rotation based on velocity.
PixelpartStaticPropertyFloat3 get_rotation_variance()
Returns the property for how much the rotations of particles vary, in degrees.
PixelpartStaticPropertyFloat3 get_angular_velocity_variance()
Returns the property for how much the angular velocities of particles vary, in degrees per second.
PixelpartStaticPropertyFloat3 get_pivot()
Returns the property for the rotation center of particles.
PixelpartAnimatedPropertyFloat get_physical_size()
Returns the animation property for the physical size of particles over their lifetime.
PixelpartAnimatedPropertyFloat get_weight()
Returns the animation property for the weight of particles over their lifetime.
PixelpartAnimatedPropertyFloat get_bounce()
Returns the animation property for the bounce of particles over their lifetime.
PixelpartAnimatedPropertyFloat get_friction()
Returns the animation property for the friction of particles over their lifetime.
void set_visible(bool mode)
Sets
visible
.bool is_visible()
Returns
visible
.void set_layer(int layer)
Sets
layer
.int get_layer()
Returns
layer
.PixelpartAnimatedPropertyFloat get_initial_size()
Returns the animation property for the starting size of particles.
PixelpartAnimatedPropertyFloat3 get_size()
Returns the animation property for the size of particles over their lifetime.
PixelpartStaticPropertyFloat get_size_variance()
Returns the animation property for the variance in particle sizes.
PixelpartAnimatedPropertyFloat3 get_stretch()
Returns the animation property for how much particles are stretched based on their speed.
PixelpartAnimatedPropertyFloat4 get_color()
Returns the animation property for the colors of particles over their lifetime.
PixelpartStaticPropertyFloat4 get_color_variance()
Returns the property for how the color varies between particles. The individual vector components are hue, saturation and value according to the HSV color model.
PixelpartAnimatedPropertyFloat get_initial_opacity()
Returns the animation property for the initial opacity of particles.
PixelpartAnimatedPropertyFloat get_opacity()
Returns the animation property for the opacity of particles over their lifetime.
PixelpartStaticPropertyFloat get_opacity_variance()
Returns the property for how the opacity varies between particles.
PixelpartForceField¶
Properties¶
float lifetime_start
When the force field becomes active, in seconds.
float lifetime_duration
How long the force field stays active, in seconds.
bool repeat
Whether the force field continues to stay active after
lifetime_duration
has passed.int type
Type of the force field (
ATTRACTION_FIELD
,ACCELERATION_FIELD
,VECTOR_FIELD
,NOISE_FIELD
,DRAG_FIELD
).int vector_filter
How velocity values are interpolated between the cells of the vector field. Only applicable for type
VECTOR_FIELD
.bool noise_animated
Whether the noise field is animated. Only applicable for type
NOISE_FIELD
.
Methods¶
int get_id()
Returns the ID of the force field.
String get_name()
Returns the name of the force field.
void set_lifetime_start(float time)
Sets
lifetime_start
.void set_lifetime_duration(float time)
Sets
lifetime_duration
.void set_repeat(bool value)
Sets
repeat
.float get_lifetime_start()
Returns
lifetime_start
.float get_lifetime_duration()
Returns
lifetime_duration
.bool get_repeat()
Returns
repeat
.bool is_active()
Returns whether the force field is active.
float get_local_time()
Returns the time fraction the force field has been active for, in range
0.0
(0%) to1.0
(100%).PixelpartAnimatedPropertyFloat3 get_position()
Returns the motion path of the force field.
void set_type(int type)
Sets
type
.int get_type()
Returns
type
.PixelpartAnimatedPropertyFloat3 get_size()
Returns the animation property for the size of the force field.
PixelpartAnimatedPropertyFloat3 get_orientation()
Returns the animation property for the orientation of the force field.
PixelpartAnimatedPropertyFloat get_strength()
Returns the animation property for the strength of the force field.
PixelpartAnimatedPropertyFloat3 get_acceleration_direction()
Returns the animation property for the force direction of the force field. Only applicable for type
ACCELERATION_FIELD
.PixelpartAnimatedPropertyFloat get_acceleration_direction_variance()
Returns the animation property for the variance in force direction between different cells of the force field. Only applicable for type
ACCELERATION_FIELD
.PixelpartAnimatedPropertyFloat get_acceleration_strength_variance()
Returns the animation property for the variance in force strength between different cells of the force field. Only applicable for type
ACCELERATION_FIELD
.void set_grid_size(int width, int height, int depth)
Sets the number of cells in each dimension of the force field grid. Each cell of the grid varies in direction and strength determined by the direction and strength variance values. Only applicable for type
ACCELERATION_FIELD
.int get_acceleration_grid_width()
Returns the number of grid cells on the X axis of the force field grid. Only applicable for type
ACCELERATION_FIELD
.int get_acceleration_grid_height()
Returns the number of grid cells on the Y axis of the force field grid. Only applicable for type
ACCELERATION_FIELD
.int get_acceleration_grid_depth()
Returns the number of grid cells on the Z axis of the force field grid. Only applicable for type
ACCELERATION_FIELD
.void set_vector_filter(int filter)
Sets
vector_filter
.int get_vector_filter()
Returns
vector_filter
.PixelpartAnimatedPropertyFloat get_vector_tightness()
Returns the animation property for how directly particles follow the vectors in the force field. Only applicable for type
VECTOR_FIELD
.PixelpartStaticPropertyInt get_noise_octaves()
Returns the property for how many layers of noise are blended together to produce the final velocity vector. Only applicable for type
NOISE_FIELD
.PixelpartAnimatedPropertyFloat get_noise_frequency()
Returns the animation property of the base frequency of the noise generation. Only applicable for type
NOISE_FIELD
.PixelpartAnimatedPropertyFloat get_noise_persistence()
Returns the animation property for how much the amplitude changes after each noise octave. Only applicable for type
NOISE_FIELD
.PixelpartAnimatedPropertyFloat get_noise_lacunarity()
Returns the animation property for how much the frequency changes after each noise octave. Only applicable for type
NOISE_FIELD
.void set_noise_animated(bool animated)
Sets
noise_animated
.bool get_noise_animated()
Returns
noise_animated
.PixelpartStaticPropertyFloat get_noise_animation_time_scale()
Returns the property for how fast the noise field changes. Only applicable for type
NOISE_FIELD
.PixelpartStaticPropertyFloat get_noise_animation_time_base()
Returns the property of the time offset of the noise animation. Only applicable for type
NOISE_FIELD
.PixelpartStaticPropertyFloat get_drag_velocity_influence()
Returns the property for how strongly the drag force is influenced by the particle velocity. Only applicable for type
DRAG_FIELD
.PixelpartStaticPropertyFloat get_drag_size_influence()
Returns the property for how strongly the drag force is influenced by the particle size. Only applicable for type
DRAG_FIELD
.
PixelpartCollider¶
Properties¶
float lifetime_start
When the collider becomes active, in seconds.
float lifetime_duration
How long the collider stays active, in seconds.
bool repeat
Whether the collider continues to stay active after
lifetime_duration
has passed.
Methods¶
int get_id()
Returns the ID of the collider.
String get_name()
Returns the name of the collider.
void set_lifetime_start(float time)
Sets
lifetime_start
.void set_lifetime_duration(float time)
Sets
lifetime_duration
.void set_repeat(bool value)
Sets
repeat
.float get_lifetime_start()
Returns
lifetime_start
.float get_lifetime_duration()
Returns
lifetime_duration
.bool get_repeat()
Returns
repeat
.bool is_active()
Returns whether the collider is active.
float get_local_time()
Returns the time fraction the collider has been active for, in range 0.0 (0%) to 1.0 (100%).
void add_point(Vector3 point)
Adds a vertex to the collider at the given position.
void set_point(int index, Vector3 point)
Sets the position of the given vertex.
void remove_point(int index)
Removes the given vertex from the collider.
Vector3 get_point(int index)
Returns the position of the given vertex.
int get_num_points()
Returns the number of vertices.
PixelpartStaticPropertyFloat get_width()
Returns the property of the width of the collider. Only applicable for 3D effects.
PixelpartStaticPropertyFloat get_orientation()
Returns the property of the orientation of the collider. Only applicable for 3D effects.
PixelpartStaticPropertyBool get_kill_on_contact()
Returns the property for whether particles are killed on contact with the collider.
PixelpartAnimatedPropertyFloat get_bounce()
Returns the animation property for the bounciness of the collider.
PixelpartAnimatedPropertyFloat get_friction()
Returns the animation property for the friction of the collider.
PixelpartAnimatedProperty*¶
Scene objects of an effect like particle emitters and force fields have properties that change over time. Such properties are represented by the class family PixelpartAnimatedProperty*
. There are classes for the types int
, float
, Vector2
, Vector3
or Vector4
depending on the type of the property, which offer methods to modify the keyframes of the animation.
Properties¶
int interpolation
Interpolation applied to the animation curve (
OFF
,LINEAR
,SPLINE
).
Methods¶
T get(float position)
Returns the (interpolated) value of the animation property at time
position
in range0.0
to1.0
.void add_point(float position, T value)
Adds a keyframe at time
position
with valuevalue
.void remove_point(int index)
Removes the keyframe with the given index from the animation.
void set_point(int index, T value)
Sets the value of the keyframe with the given index to
value
.void set_point_position(int index, float position)
Move the time of the keyframe with the given index to
position
.void clear()
Removes all keyframes from the animation.
void contains_points()
Returns whether the animation property contains any keyframes.
int get_num_points()
Returns the number of keyframes.
T get_point(int index)
Returns the value of the keyframe with the given index.
int get_point_index(float position, float epsilon)
Return the index of the keyframe closest to time
position
.void set_interpolation(int method)
Sets
interpolation
.int get_interpolation()
Returns
interpolation
.void enable_adaptive_cache()
Enables an adaptive cache, which resizes itself automatically if the number of keyframes increases or decreases a lot.
void enable_fixed_cache(int size)
Enables a fixed cache with the given size, which only stores up to
size
different value.
PixelpartStaticProperty*¶
Scene objects of an effect like particle emitters and force fields have properties that do not change over time. Such properties are represented by the class family PixelpartStaticProperty*
. There are classes for the types bool
, int
, float
, Vector2
, Vector3
or Vector4
depending on the type of the property.
Methods¶
T get()
Returns the value of the property considering active effect inputs.
void set_value(T value)
Sets the value of the property.
T get_value()
Returns the value of the property without considering effect inputs.
Platform Support¶
Platforms |
Architectures |
Supported |
---|---|---|
Windows |
x64, x86 |
|
Linux |
x64, x86 |
|
macOS |
Universal |
|
Android |
||
iOS |
||
Web |
||
Console |