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...

GPUParticles3D

Hérite de : GeometryInstance3D < VisualInstance3D < Node3D < Node < Object

Un émetteur de particules 3D.

Description

Nœud de particules 3D utilisé pour créer une variété de systèmes et d'effets de particules. GPUParticles3D 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.

Tutoriels

Propriétés

int

amount

8

float

amount_ratio

1.0

float

collision_base_size

0.01

DrawOrder

draw_order

0

Mesh

draw_pass_1

Mesh

draw_pass_2

Mesh

draw_pass_3

Mesh

draw_pass_4

int

draw_passes

1

Skin

draw_skin

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

bool

trail_enabled

false

float

trail_lifetime

0.3

TransformAlign

transform_align

0

ParticlesTransformAlignAxis

transform_align_axis

ParticlesTransformAlignCustomSrc

transform_align_channel_filter

bool

use_fixed_seed

false

AABB

visibility_aabb

AABB(-4, -4, -4, 8, 8, 8)

Méthodes

AABB

capture_aabb() const

void

convert_from_particles(particles: Node)

void

emit_particle(xform: Transform3D, velocity: Vector3, color: Color, custom: Color, flags: int)

Mesh

get_draw_pass_mesh(pass: int) const

void

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

void

restart(keep_seed: bool = false)

void

set_draw_pass_mesh(pass: int, mesh: Mesh)

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.

DrawOrder DRAW_ORDER_VIEW_DEPTH = 3

Les particules sont affichées suivant leur profondeur à l'écran.

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.

enum TransformAlign: 🔗

TransformAlign TRANSFORM_ALIGN_DISABLED = 0

Do not align particle transforms relative to the camera or velocity.

TransformAlign TRANSFORM_ALIGN_Z_BILLBOARD = 1

Align each particle's Z axis to face the camera.

TransformAlign TRANSFORM_ALIGN_Y_TO_VELOCITY = 2

Align each particle's Y axis to the velocity vector.

TransformAlign TRANSFORM_ALIGN_Z_BILLBOARD_Y_TO_VELOCITY = 3

Align each particle's Z axis to face the camera and Y axis to the velocity vector.

TransformAlign TRANSFORM_ALIGN_LOCAL_BILLBOARD = 4

Align each particle's Z axis to face the camera, while preserving a given axis (X or Y).

Constantes

MAX_DRAW_PASSES = 4 🔗

Le nombre maximal de passes de dessin supporté.

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 = 0.01 🔗

  • void set_collision_base_size(value: float)

  • float get_collision_base_size()

Le diamètre de base de collision des particules en mètres. 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 = 0 🔗

Ordre de dessin des particules.

Note : DRAW_ORDER_INDEX est la seule option qui supporte les vecteurs de mouvement pour des effets comme le TAA. Il est suggéré d'utiliser cet ordre de dessin si les particules sont opaques pour corriger des artéfacts fantomatiques.

Mesh draw_pass_1 🔗

  • void set_draw_pass_mesh(pass: int, mesh: Mesh)

  • Mesh get_draw_pass_mesh(pass: int) const

Le Mesh qui est affiché lors de la première passe.

Mesh draw_pass_2 🔗

  • void set_draw_pass_mesh(pass: int, mesh: Mesh)

  • Mesh get_draw_pass_mesh(pass: int) const

Le Mesh qui est affiché lors de la deuxième passe.

Mesh draw_pass_3 🔗

  • void set_draw_pass_mesh(pass: int, mesh: Mesh)

  • Mesh get_draw_pass_mesh(pass: int) const

Le Mesh qui est affiché lors de la troisième passe.

Mesh draw_pass_4 🔗

  • void set_draw_pass_mesh(pass: int, mesh: Mesh)

  • Mesh get_draw_pass_mesh(pass: int) const

Le Mesh qui est affiché lors de la quatrième passe.

int draw_passes = 1 🔗

  • void set_draw_passes(value: int)

  • int get_draw_passes()

Le nombre de passes de rendu lors du rendu des particules.

Skin draw_skin 🔗

  • void set_skin(value: Skin)

  • Skin get_skin()

There is currently no description for this property. Please help us by contributing one!

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

Ratio de temps entre chaque émission. Si 0, les particules sont émises en continu. Si 1, toutes les particules sont émises simultanément.

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 GPUParticles3D (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 GPUParticles3D (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, seul un nombre de particules égal à amount sera émis.

float preprocess = 0.0 🔗

  • void set_pre_process_time(value: float)

  • float get_pre_process_time()

Durée durant laquelle pré-traiter les particules avant que l'animation commence. Vous permet de commencer l'animation un certain temps après que les particules ont commencé d'émettre.

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

Facteur d'échelle de vitesse. Une valeur de 0 peut être utilisée pour mettre en pause les particules.

NodePath sub_emitter = NodePath("") 🔗

Chemin vers un autre nœud GPUParticles3D 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 GPUParticles3D cible n'émettra plus de particules tout seul.

bool trail_enabled = false 🔗

  • void set_trail_enabled(value: bool)

  • bool is_trail_enabled()

If true, enables particle trails using a mesh skinning system. Designed to work with RibbonTrailMesh and TubeTrailMesh.

Note: BaseMaterial3D.use_particle_trails must also be enabled on the particle mesh's material. Otherwise, setting trail_enabled to true will have no effect.

Note: Unlike GPUParticles2D, the number of trail sections and subdivisions is set in the RibbonTrailMesh or the TubeTrailMesh's 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.

TransformAlign transform_align = 0 🔗

The alignment of particles. Use this for billboarding and aligning to velocity.

ParticlesTransformAlignAxis transform_align_axis 🔗

When using transform align local billboard, which axis to use for the billboarding. Supports only X or Y.

ParticlesTransformAlignCustomSrc transform_align_channel_filter 🔗

In the case of billboarded particles, which custom channel to read from to calculate their angle.

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.

AABB visibility_aabb = AABB(-4, -4, -4, 8, 8, 8) 🔗

  • void set_visibility_aabb(value: AABB)

  • AABB get_visibility_aabb()

La AABB qui détermine la région du nœud qui doit être visible à l'écran pour que le système de particules soit actif. GeometryInstance3D.extra_cull_margin est ajouté sur chaque axe de l'AABB. Les attractions et collisions de particules ne se produiront que dans cette zone.

Agrandissez la boîte si les particules apparaissent/disparaissent soudainement lorsque le nœud entre/sort de l'écran. La AABB peut être agrandie par code ou avec l'outil de l'éditeur Particules → Générer AABB.

Note : visibility_aabb est redéfini par GeometryInstance3D.custom_aabb si cette propriété est définie à une valeur non par défaut.

Descriptions des méthodes

AABB capture_aabb() const 🔗

Renvoie la boîte délimitante alignée sur les axes qui contient toutes les particules qui sont actives dans la trame actuelle.

void convert_from_particles(particles: Node) 🔗

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

void emit_particle(xform: Transform3D, velocity: Vector3, 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é.

Mesh get_draw_pass_mesh(pass: int) const 🔗

Renvoie le Mesh qui est dessiné à la passe d'index pass.

void request_particles_process(process_time: float, process_time_residual: float = 0.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.

void set_draw_pass_mesh(pass: int, mesh: Mesh) 🔗

Définit le Mesh qui est dessiné à la passe d'index pass.