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 for PixelpartEffect2D.
void set_flip_v(bool flip): Sets flip_v. Only available for PixelpartEffect2D.
bool get_flip_h(): Returns flip_h. Only available for PixelpartEffect2D.
bool get_flip_v(): Returns flip_v. Only available for PixelpartEffect2D.
void set_input_bool(String name, bool value): Sets the effect input name to the given value. The effect input must be of type bool.
void set_input_int(String name, int value): Sets the effect input name to the given value. The effect input must be of type int.
void set_input_float(String name, float value): Sets the effect input name to the given value. The effect input must be of type float.
void set_input_float2(String name, Vector2 value): Sets the effect input name to the given value. The effect input must be of type Vector2.
void set_input_float3(String name, Vector3 value): Sets the effect input name to the given value. The effect input must be of type Vector3.
void set_input_float4(String name, Vector4 value): Sets the effect input name to the given value. The effect input must be of type Vector4.
bool get_input_bool(String name): Returns the value of the effect input name. The effect input must be of type bool.
int get_input_int(String name): Returns the value of the effect input name. The effect input must be of type int.
float get_input_float(String name): Returns the value of the effect input name. The effect input must be of type float.
Vector2 get_input_float2(String name): Returns the value of the effect input name. The effect input must be of type Vector2.
Vector3 get_input_float3(String name): Returns the value of the effect input name. The effect input must be of type Vector3.
Vector4 get_input_float4(String name): Returns the value of the effect input name. The effect input must be of type Vector4.
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 name particleTypeName.
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 shape PATH.
void set_shape_point(int index, Vector3 point): Changes the location of the point at index in the emitter shape. Only applicable for emitter shape PATH.
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 shape PATH.
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 and GRID_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%) to 1.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 range 0.0 to 1.0.
void add_point(float position, T value): Adds a keyframe at time position with value value.
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