Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

GPUParticles2D

Hérite de : Node2D < CanvasItem < Node < Object

Un émetteur de particules 2D.

Description

Nœud de particules 2D utilisé pour créer une variété de systèmes et d'effets de particules. GPUParticles2D dispose d'un émetteur qui génère un certain nombre de particules à un taux donné.

Utilisez la propriété process_material pour ajouter un ParticleProcessMaterial pour configurer l'apparence et le comportement des particules. Alternativement, vous pouvez ajouter un ShaderMaterial qui sera appliqué à toutes les particules.

Les particules 2D peuvent optionnellement entrer en collision avec des nœuds LightOccluder2D, mais elles n'entrent pas en collision avec des nœuds PhysicsBody2D.

Tutoriels

Propriétés

int

amount

8

float

amount_ratio

1.0

float

collision_base_size

1.0

DrawOrder

draw_order

1

bool

emitting

true

float

explosiveness

0.0

int

fixed_fps

30

bool

fract_delta

true

float

interp_to_end

0.0

bool

interpolate

true

float

lifetime

1.0

bool

local_coords

false

bool

one_shot

false

float

preprocess

0.0

Material

process_material

float

randomness

0.0

int

seed

0

float

speed_scale

1.0

NodePath

sub_emitter

NodePath("")

Texture2D

texture

bool

trail_enabled

false

float

trail_lifetime

0.3

int

trail_section_subdivisions

4

int

trail_sections

8

bool

use_fixed_seed

false

Rect2

visibility_rect

Rect2(-100, -100, 200, 200)

Méthodes

Rect2

capture_rect() const

void

convert_from_particles(particles: Node)

void

emit_particle(xform: Transform2D, velocity: Vector2, color: Color, custom: Color, flags: int)

void

request_particles_process(process_time: float, process_time_residual: float = 0)

void

restart(keep_seed: bool = false)

Signaux

finished() 🔗

Émis lorsque toutes les particules actives ont terminé le traitement. Pour redémarrer immédiatement le cycle d'émission, appelez restart().

Ce signal n'est jamais émis lorsque one_shot est désactivé, car les particules seront émises et traitées en continu.

Note : Pour les émetteurs one_shot, à cause des particules calculées sur le GPU, il peut y avoir une courte période après avoir reçu le signal finished pendant laquelle définir emitting à true ne redémarre pas le cycle d'émission. Ce retard est évité en appelant plutôt restart().

Énumérations

enum DrawOrder: 🔗

DrawOrder DRAW_ORDER_INDEX = 0

Les particules sont affichées dans l'ordre dans lequel elles ont été émises.

DrawOrder DRAW_ORDER_LIFETIME = 1

Les particules sont dessinées dans l'ordre de leur durée de vie restante. En d'autres termes, la particule avec la durée de vie la plus grande est dessinée à l'avant.

DrawOrder DRAW_ORDER_REVERSE_LIFETIME = 2

Les particules sont dessinées dans l'ordre inverse du temps de vie restant. En d'autres termes, la particule avec la vie la plus basse est dessinée à l'avant.

enum EmitFlags: 🔗

EmitFlags EMIT_FLAG_POSITION = 1

La particule commence à la position spécifiée.

EmitFlags EMIT_FLAG_ROTATION_SCALE = 2

La particule commence avec la rotation et l'échelle spécifiées.

EmitFlags EMIT_FLAG_VELOCITY = 4

La particule commence avec le vecteur de vélocité spécifié, qui définit la direction et la vitesse de l'émission.

EmitFlags EMIT_FLAG_COLOR = 8

La particule commence avec la couleur spécifiée.

EmitFlags EMIT_FLAG_CUSTOM = 16

La particule commence avec les données personnalisées CUSTOM spécifiées.

Descriptions des propriétés

int amount = 8 🔗

  • void set_amount(value: int)

  • int get_amount()

Le nombre de particules à émettre dans un cycle d'émission. Le taux d'émission effectif est de (amount * amount_ratio) / lifetime particules par seconde. Des valeurs plus élevées augmenteront le coût sur le GPU, même si toutes les particules ne sont pas visibles à un moment donné ou si amount_ratio est diminué.

Note : Modifier cette valeur entraînera le redémarrage du système de particules. Pour éviter cela, modifiez plutôt amount_ratio.

float amount_ratio = 1.0 🔗

  • void set_amount_ratio(value: float)

  • float get_amount_ratio()

Le ratio de particule qui devraient être réellement émises. Si la valeur est inférieure à 1.0, cela permettra de définir la quantité de particules émises tout au long de la vie à amount * amount_ratio. Contrairement à la modification de amount, modifier amount_ratio tout en émettant n'affecte pas les particules déjà émises et ne provoque pas le redémarrage du système de particules. amount_ratio peut être utilisé pour créer des effets qui font varier le nombre de particules émises au fil du temps.

Note : La réduction de la valeur de amount_ratio n'a pas d'avantage de performance, puisque les ressources doivent être allouées et traitées pour le nombre total (amount) de particules, peu importe amount_ratio. Si vous n'avez pas l'intention de modifier le nombre de particules émises pendant que les particules émettent, assurez-vous que amount_ratio soit défini à 1 et changez plutôt amount à votre goût.

float collision_base_size = 1.0 🔗

  • void set_collision_base_size(value: float)

  • float get_collision_base_size()

Multiplicateur pour le rayon de collision des particules. 1.0 correspond à la taille du sprite. Si les particules semblent s'enfoncer dans le sol lors de la collision, augmentez cette valeur. Si les particules semblent flotter lors de la collision, diminuez cette valeur. Seulement effectif si ParticleProcessMaterial.collision_mode vaut ParticleProcessMaterial.COLLISION_RIGID ou ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT.

Note : Les particules ont toujours une forme de collision sphérique.

DrawOrder draw_order = 1 🔗

Ordre de dessin des particules.

bool emitting = true 🔗

  • void set_emitting(value: bool)

  • bool is_emitting()

Si true, des particules sont émises. emitting peut être utilisé pour démarrer et arrêter l'émission des particules. Toutefois, si one_shot vaut true, définir emitting à true ne redémarrera pas le cycle d'émission à moins que toutes les particules actives n'aient fini de traiter. Utilisez le signal finished pour être averti quand toutes les particules actives ont fini de traiter.

Note : Pour les émetteurs one_shot, à cause des particules calculées sur le GPU, il peut y avoir une courte période après avoir reçu le signal finished pendant laquelle définir cette valeur à true ne redémarre pas le cycle d'émission.

Astuce : Si votre émetteur one_shot doit immédiatement redémarrer l'émission de particules une fois le signal finished reçu, envisagez d'appeler restart() au lieu de définir emitting.

float explosiveness = 0.0 🔗

  • void set_explosiveness_ratio(value: float)

  • float get_explosiveness_ratio()

La rapidité avec laquelle les particules d’un cycle d’émission sont émises. Si elle est supérieure à 0, il y aura un écart dans les émissions avant le début du prochain cycle.

int fixed_fps = 30 🔗

  • void set_fixed_fps(value: int)

  • int get_fixed_fps()

Le taux de rafraîchissement du système de particules est fixé à une valeur. Par exemple, changer la valeur à 2 rendra les particules à 2 trames par seconde. Notez que cela ne ralentit pas la simulation du système de particules lui-même.

bool fract_delta = true 🔗

  • void set_fractional_delta(value: bool)

  • bool get_fractional_delta()

Si true, utilise un calcul d'étape fractionnelle qui permet affichage plus lisse des particules.

float interp_to_end = 0.0 🔗

  • void set_interp_to_end(value: float)

  • float get_interp_to_end()

Cause toutes les particules de ce nœud à interpoler vers la fin de leur vie.

Note : Cela ne fonctionne que lors qu’utilisé avec un ParticleProcessMaterial. Il doit être implémenté manuellement pour les shaders de traitement personnalisés.

bool interpolate = true 🔗

  • void set_interpolate(value: bool)

  • bool get_interpolate()

Active l'interpolation des particules, ce qui rend le mouvement des particules plus fluide lorsque leur taux de rafraichissement fixed_fps est inférieur au taux de rafraîchissement de l'écran.

float lifetime = 1.0 🔗

  • void set_lifetime(value: float)

  • float get_lifetime()

La durée pendant laquelle chaque particule existera (en secondes). Le taux d'émission effectif est de (amount * amount_ratio) / lifetime particules par seconde.

bool local_coords = false 🔗

  • void set_use_local_coordinates(value: bool)

  • bool get_use_local_coordinates()

Si true, les particules utilisent l'espace de coordonnées du nœud parent (aussi appelées coordonnées locales). Cela causera les particules de se déplacer et tourner avec le nœud GPUParticles2D (et ses parents) lorsqu'il est déplacé ou tourné. Si false, les particules utilisent des coordonnées globales, cela ne causera pas les particules de se déplacer et tourner avec le nœud GPUParticles2D (et ses parents) lorsqu'il est déplacé ou en tourné.

bool one_shot = false 🔗

  • void set_one_shot(value: bool)

  • bool get_one_shot()

Si true, un seul cycle d'émission se produit. Si définit à true pendant un cycle, l'émission s'arrêtera à la fin de ce cycle.

float preprocess = 0.0 🔗

  • void set_pre_process_time(value: float)

  • float get_pre_process_time()

Le système de particules commence comme s'il s'était déjà exécuté pendant ce nombre de secondes.

Note : Cela peut être très cher si défini à un nombre élevé car il nécessite l'exécution du shader de particules un certain nombre de fois égal à fixed_fps (ou 30, si fixed_fps vaut 0) pour chaque seconde. Dans les cas extrêmes, il peut même conduire à un crash GPU en raison du volume de travail effectué en une seule trame.

Material process_material 🔗

Material pour le traitement des particules. Peut être un ParticleProcessMaterial ou un ShaderMaterial.

float randomness = 0.0 🔗

  • void set_randomness_ratio(value: float)

  • float get_randomness_ratio()

Facteur d'aléatoire de durée de vie de l'émission.

int seed = 0 🔗

  • void set_seed(value: int)

  • int get_seed()

Définit la graine de l'aléatoire utilisée par le système de particules. Seulement effectif si use_fixed_seed vaut true.

float speed_scale = 1.0 🔗

  • void set_speed_scale(value: float)

  • float get_speed_scale()

Le facteur de vitesse du système de particules. Une valeur de 0 peut être utilisée pour arrêter les particules.

NodePath sub_emitter = NodePath("") 🔗

Chemin vers un autre nœud GPUParticles2D qui sera utilisé comme sous-émetteur (voir ParticleProcessMaterial.sub_emitter_mode). Les sous-émetteurs peuvent être utilisés pour réaliser des effets comme des feux d'artifice, des étincelles sur les collisions, des bulles éclatant en des gouttes d'eau, et plus encore.

Note : Lorsque sub_emitter est défini, le nœud GPUParticles2D cible n'émettra plus de particules tout seul.

Texture2D texture 🔗

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.particles_animation and set CanvasItemMaterial.particles_anim_h_frames, CanvasItemMaterial.particles_anim_v_frames, and CanvasItemMaterial.particles_anim_loop to match the flipbook texture.

bool trail_enabled = false 🔗

  • void set_trail_enabled(value: bool)

  • bool is_trail_enabled()

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

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

float trail_lifetime = 0.3 🔗

  • void set_trail_lifetime(value: float)

  • float get_trail_lifetime()

La durée que chaque traînée de particule devrait représenter (en secondes). Seulement effectif si trail_enabled vaut true.

int trail_section_subdivisions = 4 🔗

  • void set_trail_section_subdivisions(value: int)

  • int get_trail_section_subdivisions()

Le nombre de sous-divisions à utiliser pour le rendu de traînée de particule. Des valeurs plus élevées peuvent entraîner des courbes de traînée plus lisses, au coût de la performance en raison d'une complexité accrue du maillage. Voir aussi trail_sections. Seulement effectif si trail_enabled vaut true.

int trail_sections = 8 🔗

  • void set_trail_sections(value: int)

  • int get_trail_sections()

Le nombre de sections à utiliser pour le rendu de traînée de particule. Des valeurs plus élevées peuvent entraîner des courbes de traînée plus lisses, au coût de la performance en raison d'une complexité accrue du maillage. Voir aussi trail_section_subdivisions. Seulement effectif si trail_enabled vaut true.

bool use_fixed_seed = false 🔗

  • void set_use_fixed_seed(value: bool)

  • bool get_use_fixed_seed()

Si true, les particules utiliseront la même graine pour chaque simulation en utilisant la graine définie dans seed. Ceci est utile pour les situations où le résultat visuel devrait être consistant entre les replays, par exemple en utilisant le mode Création de film.

Rect2 visibility_rect = Rect2(-100, -100, 200, 200) 🔗

  • void set_visibility_rect(value: Rect2)

  • Rect2 get_visibility_rect()

Le Rect2 qui détermine la région du nœud qui doit être visible à l'écran pour que le système de particules soit actif.

Agrandissez le rectangle si les particules apparaissent/disparaissent soudainement lorsque le nœud entre/sort de l'écran. Le Rect2 peut être agrandi par code ou avec l'outil d'éditeur Particules → Générer Rect de Visibilité.

Descriptions des méthodes

Rect2 capture_rect() const 🔗

Renvoie un rectangle contenant les positions de toutes les particules existantes.

Note : Lors de l'utilisation du rendu par thread, cette méthode synchronise le thread de rendu. L'appeler souvent peut avoir un impact négatif sur les performances.

void convert_from_particles(particles: Node) 🔗

Défini les propriétés de ce nœud pour correspondre à un nœud CPUParticles2D donné.

void emit_particle(xform: Transform2D, velocity: Vector2, color: Color, custom: Color, flags: int) 🔗

Émet une seule particule. Si xform, velocity, color et custom sont appliqués ou non dépend de la valeur de flags. Voir EmitFlags.

Par défaut, ParticleProcessMaterial va écraser color et utiliser le contenu de custom comme (rotation, âge, animation, durée de vie).

Note : emit_particle() n'est supporté que sur les méthodes de rendu Forward+ et Mobile, pas Compatibilité.

void request_particles_process(process_time: float, process_time_residual: float = 0) 🔗

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

process_time defines the time that the particles will process while emitting is on. process_time_residual defines the time that particles will process with emitting turned off for the simulation. When combined with speed_scale set to 0.0, this is useful to be able to seek a particle system timeline.

void restart(keep_seed: bool = false) 🔗

Redémarre le cycle d'émission de particules, enlevant les particules existantes. Pour éviter que les particules ne disparaissent du viewport, attendez le signal finished avant d'appeler.

Note : Le signal finished n'est émis que par des émetteurs one_shot.

Si keep_seed vaut true, la graine actuelle de l'aléatoire sera préservée. Utile pour l'avancement et la lecture.