class_gpuparticles2d.rst 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507
  1. :github_url: hide
  2. .. DO NOT EDIT THIS FILE!!!
  3. .. Generated automatically from Godot engine sources.
  4. .. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
  5. .. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/GPUParticles2D.xml.
  6. .. _class_GPUParticles2D:
  7. GPUParticles2D
  8. ==============
  9. **Inherits:** :ref:`Node2D<class_Node2D>` **<** :ref:`CanvasItem<class_CanvasItem>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
  10. 2D particle emitter.
  11. Description
  12. -----------
  13. 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.
  14. Use the ``process_material`` property to add a :ref:`ParticleProcessMaterial<class_ParticleProcessMaterial>` to configure particle appearance and behavior. Alternatively, you can add a :ref:`ShaderMaterial<class_ShaderMaterial>` which will be applied to all particles.
  15. Tutorials
  16. ---------
  17. - :doc:`Particle systems (2D) <../tutorials/2d/particle_systems_2d>`
  18. - `2D Dodge The Creeps Demo <https://godotengine.org/asset-library/asset/515>`__
  19. Properties
  20. ----------
  21. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  22. | :ref:`int<class_int>` | :ref:`amount<class_GPUParticles2D_property_amount>` | ``8`` |
  23. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  24. | :ref:`float<class_float>` | :ref:`collision_base_size<class_GPUParticles2D_property_collision_base_size>` | ``1.0`` |
  25. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  26. | :ref:`DrawOrder<enum_GPUParticles2D_DrawOrder>` | :ref:`draw_order<class_GPUParticles2D_property_draw_order>` | ``1`` |
  27. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  28. | :ref:`bool<class_bool>` | :ref:`emitting<class_GPUParticles2D_property_emitting>` | ``true`` |
  29. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  30. | :ref:`float<class_float>` | :ref:`explosiveness<class_GPUParticles2D_property_explosiveness>` | ``0.0`` |
  31. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  32. | :ref:`int<class_int>` | :ref:`fixed_fps<class_GPUParticles2D_property_fixed_fps>` | ``30`` |
  33. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  34. | :ref:`bool<class_bool>` | :ref:`fract_delta<class_GPUParticles2D_property_fract_delta>` | ``true`` |
  35. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  36. | :ref:`bool<class_bool>` | :ref:`interpolate<class_GPUParticles2D_property_interpolate>` | ``true`` |
  37. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  38. | :ref:`float<class_float>` | :ref:`lifetime<class_GPUParticles2D_property_lifetime>` | ``1.0`` |
  39. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  40. | :ref:`bool<class_bool>` | :ref:`local_coords<class_GPUParticles2D_property_local_coords>` | ``false`` |
  41. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  42. | :ref:`bool<class_bool>` | :ref:`one_shot<class_GPUParticles2D_property_one_shot>` | ``false`` |
  43. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  44. | :ref:`float<class_float>` | :ref:`preprocess<class_GPUParticles2D_property_preprocess>` | ``0.0`` |
  45. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  46. | :ref:`Material<class_Material>` | :ref:`process_material<class_GPUParticles2D_property_process_material>` | |
  47. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  48. | :ref:`float<class_float>` | :ref:`randomness<class_GPUParticles2D_property_randomness>` | ``0.0`` |
  49. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  50. | :ref:`float<class_float>` | :ref:`speed_scale<class_GPUParticles2D_property_speed_scale>` | ``1.0`` |
  51. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  52. | :ref:`NodePath<class_NodePath>` | :ref:`sub_emitter<class_GPUParticles2D_property_sub_emitter>` | ``NodePath("")`` |
  53. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  54. | :ref:`Texture2D<class_Texture2D>` | :ref:`texture<class_GPUParticles2D_property_texture>` | |
  55. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  56. | :ref:`bool<class_bool>` | :ref:`trail_enabled<class_GPUParticles2D_property_trail_enabled>` | ``false`` |
  57. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  58. | :ref:`float<class_float>` | :ref:`trail_length_secs<class_GPUParticles2D_property_trail_length_secs>` | ``0.3`` |
  59. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  60. | :ref:`int<class_int>` | :ref:`trail_section_subdivisions<class_GPUParticles2D_property_trail_section_subdivisions>` | ``4`` |
  61. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  62. | :ref:`int<class_int>` | :ref:`trail_sections<class_GPUParticles2D_property_trail_sections>` | ``8`` |
  63. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  64. | :ref:`Rect2<class_Rect2>` | :ref:`visibility_rect<class_GPUParticles2D_property_visibility_rect>` | ``Rect2(-100, -100, 200, 200)`` |
  65. +-------------------------------------------------+---------------------------------------------------------------------------------------------+---------------------------------+
  66. Methods
  67. -------
  68. +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  69. | :ref:`Rect2<class_Rect2>` | :ref:`capture_rect<class_GPUParticles2D_method_capture_rect>` **(** **)** |const| |
  70. +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  71. | void | :ref:`emit_particle<class_GPUParticles2D_method_emit_particle>` **(** :ref:`Transform2D<class_Transform2D>` xform, :ref:`Vector2<class_Vector2>` velocity, :ref:`Color<class_Color>` color, :ref:`Color<class_Color>` custom, :ref:`int<class_int>` flags **)** |
  72. +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  73. | void | :ref:`restart<class_GPUParticles2D_method_restart>` **(** **)** |
  74. +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  75. Enumerations
  76. ------------
  77. .. _enum_GPUParticles2D_DrawOrder:
  78. .. _class_GPUParticles2D_constant_DRAW_ORDER_INDEX:
  79. .. _class_GPUParticles2D_constant_DRAW_ORDER_LIFETIME:
  80. .. _class_GPUParticles2D_constant_DRAW_ORDER_REVERSE_LIFETIME:
  81. enum **DrawOrder**:
  82. - **DRAW_ORDER_INDEX** = **0** --- Particles are drawn in the order emitted.
  83. - **DRAW_ORDER_LIFETIME** = **1** --- Particles are drawn in order of remaining lifetime.
  84. - **DRAW_ORDER_REVERSE_LIFETIME** = **2**
  85. ----
  86. .. _enum_GPUParticles2D_EmitFlags:
  87. .. _class_GPUParticles2D_constant_EMIT_FLAG_POSITION:
  88. .. _class_GPUParticles2D_constant_EMIT_FLAG_ROTATION_SCALE:
  89. .. _class_GPUParticles2D_constant_EMIT_FLAG_VELOCITY:
  90. .. _class_GPUParticles2D_constant_EMIT_FLAG_COLOR:
  91. .. _class_GPUParticles2D_constant_EMIT_FLAG_CUSTOM:
  92. enum **EmitFlags**:
  93. - **EMIT_FLAG_POSITION** = **1** --- Particle starts at the specified position.
  94. - **EMIT_FLAG_ROTATION_SCALE** = **2** --- Particle starts with specified rotation and scale.
  95. - **EMIT_FLAG_VELOCITY** = **4** --- Particle starts with the specified velocity vector, which defines the emission direction and speed.
  96. - **EMIT_FLAG_COLOR** = **8** --- Particle starts with specified color.
  97. - **EMIT_FLAG_CUSTOM** = **16** --- Particle starts with specified ``CUSTOM`` data.
  98. Property Descriptions
  99. ---------------------
  100. .. _class_GPUParticles2D_property_amount:
  101. - :ref:`int<class_int>` **amount**
  102. +-----------+-------------------+
  103. | *Default* | ``8`` |
  104. +-----------+-------------------+
  105. | *Setter* | set_amount(value) |
  106. +-----------+-------------------+
  107. | *Getter* | get_amount() |
  108. +-----------+-------------------+
  109. Number of particles emitted in one emission cycle.
  110. ----
  111. .. _class_GPUParticles2D_property_collision_base_size:
  112. - :ref:`float<class_float>` **collision_base_size**
  113. +-----------+--------------------------------+
  114. | *Default* | ``1.0`` |
  115. +-----------+--------------------------------+
  116. | *Setter* | set_collision_base_size(value) |
  117. +-----------+--------------------------------+
  118. | *Getter* | get_collision_base_size() |
  119. +-----------+--------------------------------+
  120. ----
  121. .. _class_GPUParticles2D_property_draw_order:
  122. - :ref:`DrawOrder<enum_GPUParticles2D_DrawOrder>` **draw_order**
  123. +-----------+-----------------------+
  124. | *Default* | ``1`` |
  125. +-----------+-----------------------+
  126. | *Setter* | set_draw_order(value) |
  127. +-----------+-----------------------+
  128. | *Getter* | get_draw_order() |
  129. +-----------+-----------------------+
  130. Particle draw order. Uses :ref:`DrawOrder<enum_GPUParticles2D_DrawOrder>` values.
  131. ----
  132. .. _class_GPUParticles2D_property_emitting:
  133. - :ref:`bool<class_bool>` **emitting**
  134. +-----------+---------------------+
  135. | *Default* | ``true`` |
  136. +-----------+---------------------+
  137. | *Setter* | set_emitting(value) |
  138. +-----------+---------------------+
  139. | *Getter* | is_emitting() |
  140. +-----------+---------------------+
  141. If ``true``, particles are being emitted.
  142. ----
  143. .. _class_GPUParticles2D_property_explosiveness:
  144. - :ref:`float<class_float>` **explosiveness**
  145. +-----------+--------------------------------+
  146. | *Default* | ``0.0`` |
  147. +-----------+--------------------------------+
  148. | *Setter* | set_explosiveness_ratio(value) |
  149. +-----------+--------------------------------+
  150. | *Getter* | get_explosiveness_ratio() |
  151. +-----------+--------------------------------+
  152. 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.
  153. ----
  154. .. _class_GPUParticles2D_property_fixed_fps:
  155. - :ref:`int<class_int>` **fixed_fps**
  156. +-----------+----------------------+
  157. | *Default* | ``30`` |
  158. +-----------+----------------------+
  159. | *Setter* | set_fixed_fps(value) |
  160. +-----------+----------------------+
  161. | *Getter* | get_fixed_fps() |
  162. +-----------+----------------------+
  163. The particle system's frame rate is fixed to a value. For instance, 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.
  164. ----
  165. .. _class_GPUParticles2D_property_fract_delta:
  166. - :ref:`bool<class_bool>` **fract_delta**
  167. +-----------+-----------------------------+
  168. | *Default* | ``true`` |
  169. +-----------+-----------------------------+
  170. | *Setter* | set_fractional_delta(value) |
  171. +-----------+-----------------------------+
  172. | *Getter* | get_fractional_delta() |
  173. +-----------+-----------------------------+
  174. If ``true``, results in fractional delta calculation which has a smoother particles display effect.
  175. ----
  176. .. _class_GPUParticles2D_property_interpolate:
  177. - :ref:`bool<class_bool>` **interpolate**
  178. +-----------+------------------------+
  179. | *Default* | ``true`` |
  180. +-----------+------------------------+
  181. | *Setter* | set_interpolate(value) |
  182. +-----------+------------------------+
  183. | *Getter* | get_interpolate() |
  184. +-----------+------------------------+
  185. Enables particle interpolation, which makes the particle movement smoother when their :ref:`fixed_fps<class_GPUParticles2D_property_fixed_fps>` is lower than the screen refresh rate.
  186. ----
  187. .. _class_GPUParticles2D_property_lifetime:
  188. - :ref:`float<class_float>` **lifetime**
  189. +-----------+---------------------+
  190. | *Default* | ``1.0`` |
  191. +-----------+---------------------+
  192. | *Setter* | set_lifetime(value) |
  193. +-----------+---------------------+
  194. | *Getter* | get_lifetime() |
  195. +-----------+---------------------+
  196. Amount of time each particle will exist.
  197. ----
  198. .. _class_GPUParticles2D_property_local_coords:
  199. - :ref:`bool<class_bool>` **local_coords**
  200. +-----------+----------------------------------+
  201. | *Default* | ``false`` |
  202. +-----------+----------------------------------+
  203. | *Setter* | set_use_local_coordinates(value) |
  204. +-----------+----------------------------------+
  205. | *Getter* | get_use_local_coordinates() |
  206. +-----------+----------------------------------+
  207. 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.
  208. ----
  209. .. _class_GPUParticles2D_property_one_shot:
  210. - :ref:`bool<class_bool>` **one_shot**
  211. +-----------+---------------------+
  212. | *Default* | ``false`` |
  213. +-----------+---------------------+
  214. | *Setter* | set_one_shot(value) |
  215. +-----------+---------------------+
  216. | *Getter* | get_one_shot() |
  217. +-----------+---------------------+
  218. If ``true``, only one emission cycle occurs. If set ``true`` during a cycle, emission will stop at the cycle's end.
  219. ----
  220. .. _class_GPUParticles2D_property_preprocess:
  221. - :ref:`float<class_float>` **preprocess**
  222. +-----------+-----------------------------+
  223. | *Default* | ``0.0`` |
  224. +-----------+-----------------------------+
  225. | *Setter* | set_pre_process_time(value) |
  226. +-----------+-----------------------------+
  227. | *Getter* | get_pre_process_time() |
  228. +-----------+-----------------------------+
  229. Particle system starts as if it had already run for this many seconds.
  230. ----
  231. .. _class_GPUParticles2D_property_process_material:
  232. - :ref:`Material<class_Material>` **process_material**
  233. +----------+-----------------------------+
  234. | *Setter* | set_process_material(value) |
  235. +----------+-----------------------------+
  236. | *Getter* | get_process_material() |
  237. +----------+-----------------------------+
  238. :ref:`Material<class_Material>` for processing particles. Can be a :ref:`ParticleProcessMaterial<class_ParticleProcessMaterial>` or a :ref:`ShaderMaterial<class_ShaderMaterial>`.
  239. ----
  240. .. _class_GPUParticles2D_property_randomness:
  241. - :ref:`float<class_float>` **randomness**
  242. +-----------+-----------------------------+
  243. | *Default* | ``0.0`` |
  244. +-----------+-----------------------------+
  245. | *Setter* | set_randomness_ratio(value) |
  246. +-----------+-----------------------------+
  247. | *Getter* | get_randomness_ratio() |
  248. +-----------+-----------------------------+
  249. Emission lifetime randomness ratio.
  250. ----
  251. .. _class_GPUParticles2D_property_speed_scale:
  252. - :ref:`float<class_float>` **speed_scale**
  253. +-----------+------------------------+
  254. | *Default* | ``1.0`` |
  255. +-----------+------------------------+
  256. | *Setter* | set_speed_scale(value) |
  257. +-----------+------------------------+
  258. | *Getter* | get_speed_scale() |
  259. +-----------+------------------------+
  260. Particle system's running speed scaling ratio. A value of ``0`` can be used to pause the particles.
  261. ----
  262. .. _class_GPUParticles2D_property_sub_emitter:
  263. - :ref:`NodePath<class_NodePath>` **sub_emitter**
  264. +-----------+------------------------+
  265. | *Default* | ``NodePath("")`` |
  266. +-----------+------------------------+
  267. | *Setter* | set_sub_emitter(value) |
  268. +-----------+------------------------+
  269. | *Getter* | get_sub_emitter() |
  270. +-----------+------------------------+
  271. The :ref:`NodePath<class_NodePath>` to the ``GPUParticles2D`` used for sub-emissions.
  272. ----
  273. .. _class_GPUParticles2D_property_texture:
  274. - :ref:`Texture2D<class_Texture2D>` **texture**
  275. +----------+--------------------+
  276. | *Setter* | set_texture(value) |
  277. +----------+--------------------+
  278. | *Getter* | get_texture() |
  279. +----------+--------------------+
  280. Particle texture. If ``null``, particles will be squares.
  281. ----
  282. .. _class_GPUParticles2D_property_trail_enabled:
  283. - :ref:`bool<class_bool>` **trail_enabled**
  284. +-----------+--------------------------+
  285. | *Default* | ``false`` |
  286. +-----------+--------------------------+
  287. | *Setter* | set_trail_enabled(value) |
  288. +-----------+--------------------------+
  289. | *Getter* | is_trail_enabled() |
  290. +-----------+--------------------------+
  291. ----
  292. .. _class_GPUParticles2D_property_trail_length_secs:
  293. - :ref:`float<class_float>` **trail_length_secs**
  294. +-----------+-------------------------+
  295. | *Default* | ``0.3`` |
  296. +-----------+-------------------------+
  297. | *Setter* | set_trail_length(value) |
  298. +-----------+-------------------------+
  299. | *Getter* | get_trail_length() |
  300. +-----------+-------------------------+
  301. ----
  302. .. _class_GPUParticles2D_property_trail_section_subdivisions:
  303. - :ref:`int<class_int>` **trail_section_subdivisions**
  304. +-----------+---------------------------------------+
  305. | *Default* | ``4`` |
  306. +-----------+---------------------------------------+
  307. | *Setter* | set_trail_section_subdivisions(value) |
  308. +-----------+---------------------------------------+
  309. | *Getter* | get_trail_section_subdivisions() |
  310. +-----------+---------------------------------------+
  311. ----
  312. .. _class_GPUParticles2D_property_trail_sections:
  313. - :ref:`int<class_int>` **trail_sections**
  314. +-----------+---------------------------+
  315. | *Default* | ``8`` |
  316. +-----------+---------------------------+
  317. | *Setter* | set_trail_sections(value) |
  318. +-----------+---------------------------+
  319. | *Getter* | get_trail_sections() |
  320. +-----------+---------------------------+
  321. ----
  322. .. _class_GPUParticles2D_property_visibility_rect:
  323. - :ref:`Rect2<class_Rect2>` **visibility_rect**
  324. +-----------+---------------------------------+
  325. | *Default* | ``Rect2(-100, -100, 200, 200)`` |
  326. +-----------+---------------------------------+
  327. | *Setter* | set_visibility_rect(value) |
  328. +-----------+---------------------------------+
  329. | *Getter* | get_visibility_rect() |
  330. +-----------+---------------------------------+
  331. The :ref:`Rect2<class_Rect2>` that determines the node's region which needs to be visible on screen for the particle system to be active.
  332. Grow the rect if particles suddenly appear/disappear when the node enters/exits the screen. The :ref:`Rect2<class_Rect2>` can be grown via code or with the **Particles → Generate Visibility Rect** editor tool.
  333. Method Descriptions
  334. -------------------
  335. .. _class_GPUParticles2D_method_capture_rect:
  336. - :ref:`Rect2<class_Rect2>` **capture_rect** **(** **)** |const|
  337. Returns a rectangle containing the positions of all existing particles.
  338. ----
  339. .. _class_GPUParticles2D_method_emit_particle:
  340. - void **emit_particle** **(** :ref:`Transform2D<class_Transform2D>` xform, :ref:`Vector2<class_Vector2>` velocity, :ref:`Color<class_Color>` color, :ref:`Color<class_Color>` custom, :ref:`int<class_int>` flags **)**
  341. Emits a single particle. Whether ``xform``, ``velocity``, ``color`` and ``custom`` are applied depends on the value of ``flags``. See :ref:`EmitFlags<enum_GPUParticles2D_EmitFlags>`.
  342. ----
  343. .. _class_GPUParticles2D_method_restart:
  344. - void **restart** **(** **)**
  345. Restarts all the existing particles.
  346. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
  347. .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
  348. .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
  349. .. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
  350. .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
  351. .. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`