class_randomnumbergenerator.rst 9.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222
  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/3.6/doc/tools/make_rst.py.
  5. .. XML source: https://github.com/godotengine/godot/tree/3.6/doc/classes/RandomNumberGenerator.xml.
  6. .. _class_RandomNumberGenerator:
  7. RandomNumberGenerator
  8. =====================
  9. **Inherits:** :ref:`Reference<class_Reference>` **<** :ref:`Object<class_Object>`
  10. A class for generating pseudo-random numbers.
  11. .. rst-class:: classref-introduction-group
  12. Description
  13. -----------
  14. RandomNumberGenerator is a class for generating pseudo-random numbers. It currently uses `PCG32 <http://www.pcg-random.org/>`__.
  15. \ **Note:** The underlying algorithm is an implementation detail. As a result, it should not be depended upon for reproducible random streams across Godot versions.
  16. To generate a random float number (within a given range) based on a time-dependant seed:
  17. ::
  18. var rng = RandomNumberGenerator.new()
  19. func _ready():
  20. rng.randomize()
  21. var my_random_number = rng.randf_range(-10.0, 10.0)
  22. \ **Note:** The default values of :ref:`seed<class_RandomNumberGenerator_property_seed>` and :ref:`state<class_RandomNumberGenerator_property_state>` properties are pseudo-random, and changes when calling :ref:`randomize<class_RandomNumberGenerator_method_randomize>`. The ``0`` value documented here is a placeholder, and not the actual default seed.
  23. .. rst-class:: classref-introduction-group
  24. Tutorials
  25. ---------
  26. - :doc:`Random number generation <../tutorials/math/random_number_generation>`
  27. .. rst-class:: classref-reftable-group
  28. Properties
  29. ----------
  30. .. table::
  31. :widths: auto
  32. +-----------------------+----------------------------------------------------------+-------+
  33. | :ref:`int<class_int>` | :ref:`seed<class_RandomNumberGenerator_property_seed>` | ``0`` |
  34. +-----------------------+----------------------------------------------------------+-------+
  35. | :ref:`int<class_int>` | :ref:`state<class_RandomNumberGenerator_property_state>` | ``0`` |
  36. +-----------------------+----------------------------------------------------------+-------+
  37. .. rst-class:: classref-reftable-group
  38. Methods
  39. -------
  40. .. table::
  41. :widths: auto
  42. +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
  43. | :ref:`float<class_float>` | :ref:`randf<class_RandomNumberGenerator_method_randf>` **(** **)** |
  44. +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
  45. | :ref:`float<class_float>` | :ref:`randf_range<class_RandomNumberGenerator_method_randf_range>` **(** :ref:`float<class_float>` from, :ref:`float<class_float>` to **)** |
  46. +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
  47. | :ref:`float<class_float>` | :ref:`randfn<class_RandomNumberGenerator_method_randfn>` **(** :ref:`float<class_float>` mean=0.0, :ref:`float<class_float>` deviation=1.0 **)** |
  48. +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
  49. | :ref:`int<class_int>` | :ref:`randi<class_RandomNumberGenerator_method_randi>` **(** **)** |
  50. +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
  51. | :ref:`int<class_int>` | :ref:`randi_range<class_RandomNumberGenerator_method_randi_range>` **(** :ref:`int<class_int>` from, :ref:`int<class_int>` to **)** |
  52. +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
  53. | void | :ref:`randomize<class_RandomNumberGenerator_method_randomize>` **(** **)** |
  54. +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
  55. .. rst-class:: classref-section-separator
  56. ----
  57. .. rst-class:: classref-descriptions-group
  58. Property Descriptions
  59. ---------------------
  60. .. _class_RandomNumberGenerator_property_seed:
  61. .. rst-class:: classref-property
  62. :ref:`int<class_int>` **seed** = ``0``
  63. .. rst-class:: classref-property-setget
  64. - void **set_seed** **(** :ref:`int<class_int>` value **)**
  65. - :ref:`int<class_int>` **get_seed** **(** **)**
  66. Initializes the random number generator state based on the given seed value. A given seed will give a reproducible sequence of pseudo-random numbers.
  67. \ **Note:** The RNG does not have an avalanche effect, and can output similar random streams given similar seeds. Consider using a hash function to improve your seed quality if they're sourced externally.
  68. \ **Note:** Setting this property produces a side effect of changing the internal :ref:`state<class_RandomNumberGenerator_property_state>`, so make sure to initialize the seed *before* modifying the :ref:`state<class_RandomNumberGenerator_property_state>`:
  69. ::
  70. var rng = RandomNumberGenerator.new()
  71. rng.seed = hash("Godot")
  72. rng.state = 100 # Restore to some previously saved state.
  73. \ **Warning:** the getter of this property returns the previous :ref:`state<class_RandomNumberGenerator_property_state>`, and not the initial seed value, which is going to be fixed in Godot 4.0.
  74. .. rst-class:: classref-item-separator
  75. ----
  76. .. _class_RandomNumberGenerator_property_state:
  77. .. rst-class:: classref-property
  78. :ref:`int<class_int>` **state** = ``0``
  79. .. rst-class:: classref-property-setget
  80. - void **set_state** **(** :ref:`int<class_int>` value **)**
  81. - :ref:`int<class_int>` **get_state** **(** **)**
  82. The current state of the random number generator. Save and restore this property to restore the generator to a previous state:
  83. ::
  84. var rng = RandomNumberGenerator.new()
  85. print(rng.randf())
  86. var saved_state = rng.state # Store current state.
  87. print(rng.randf()) # Advance internal state.
  88. rng.state = saved_state # Restore the state.
  89. print(rng.randf()) # Prints the same value as in previous.
  90. \ **Note:** Do not set state to arbitrary values, since the random number generator requires the state to have certain qualities to behave properly. It should only be set to values that came from the state property itself. To initialize the random number generator with arbitrary input, use :ref:`seed<class_RandomNumberGenerator_property_seed>` instead.
  91. .. rst-class:: classref-section-separator
  92. ----
  93. .. rst-class:: classref-descriptions-group
  94. Method Descriptions
  95. -------------------
  96. .. _class_RandomNumberGenerator_method_randf:
  97. .. rst-class:: classref-method
  98. :ref:`float<class_float>` **randf** **(** **)**
  99. Generates a pseudo-random float between ``0.0`` and ``1.0`` (inclusive).
  100. .. rst-class:: classref-item-separator
  101. ----
  102. .. _class_RandomNumberGenerator_method_randf_range:
  103. .. rst-class:: classref-method
  104. :ref:`float<class_float>` **randf_range** **(** :ref:`float<class_float>` from, :ref:`float<class_float>` to **)**
  105. Generates a pseudo-random float between ``from`` and ``to`` (inclusive).
  106. .. rst-class:: classref-item-separator
  107. ----
  108. .. _class_RandomNumberGenerator_method_randfn:
  109. .. rst-class:: classref-method
  110. :ref:`float<class_float>` **randfn** **(** :ref:`float<class_float>` mean=0.0, :ref:`float<class_float>` deviation=1.0 **)**
  111. Generates a `normally-distributed <https://en.wikipedia.org/wiki/Normal_distribution>`__ pseudo-random number, using Box-Muller transform with the specified ``mean`` and a standard ``deviation``. This is also called Gaussian distribution.
  112. .. rst-class:: classref-item-separator
  113. ----
  114. .. _class_RandomNumberGenerator_method_randi:
  115. .. rst-class:: classref-method
  116. :ref:`int<class_int>` **randi** **(** **)**
  117. Generates a pseudo-random 32-bit unsigned integer between ``0`` and ``4294967295`` (inclusive).
  118. .. rst-class:: classref-item-separator
  119. ----
  120. .. _class_RandomNumberGenerator_method_randi_range:
  121. .. rst-class:: classref-method
  122. :ref:`int<class_int>` **randi_range** **(** :ref:`int<class_int>` from, :ref:`int<class_int>` to **)**
  123. Generates a pseudo-random 32-bit signed integer between ``from`` and ``to`` (inclusive).
  124. .. rst-class:: classref-item-separator
  125. ----
  126. .. _class_RandomNumberGenerator_method_randomize:
  127. .. rst-class:: classref-method
  128. void **randomize** **(** **)**
  129. Setups a time-based seed to generator.
  130. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
  131. .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
  132. .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
  133. .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`