ore.lua 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267
  1. ---@meta
  2. ---Ore definition
  3. -----------------
  4. -- Used by `minetest.register_ore`.
  5. ---@class mt.OreDef
  6. ---@field ore_type mt.OreType
  7. ---@field ore string
  8. ---@field ore_param2 number Facedir rotation. Default is 0 (unchanged rotation).
  9. ---@field wherein string|string[]
  10. -- Ore has a 1 out of `clust_scarcity` chance of spawning in a node.
  11. -- If the desired average distance between ores is `d`, set this to
  12. -- `d` * `d` * `d`.
  13. ---@field clust_scarcity number
  14. ---@field clust_num_ores number Number of ores in a cluster.
  15. -- Size of the bounding box of the cluster.
  16. -- In this example, there is a 3 * 3 * 3 cluster where 8 out of the 27
  17. -- nodes are coal ore.
  18. ---@field clust_size number
  19. ---@field y_min number Lower limit for ore.
  20. ---@field y_max number Upper limit for ore.
  21. ---@field flags mt.OreFlags
  22. -- If noise is above this threshold, ore is placed. Not needed for a
  23. -- uniform distribution.
  24. ---@field noise_threshold number
  25. ---@field noise_params mt.NoiseParams
  26. ---@field biomes string[]
  27. ---@field column_height_min number "sheet" type only.
  28. ---@field column_height_max number "sheet" type only.
  29. ---@field column_midpoint_factor number "sheet" type only.
  30. ---@field np_puff_top mt.NoiseParams "puff" type only.
  31. ---@field np_puff_bottom mt.NoiseParams "puff" type only.
  32. ---@field random_factor number "vein" type only.
  33. ---@field np_stratum_thickness mt.NoiseParams "stratum" type only.
  34. ---@field stratum_thickness number "stratum" type only.
  35. --[[
  36. NoiseParams structure describing one of the perlin noises
  37. used for ore distribution.
  38. * Needed by "sheet", "puff", "blob" and "vein" ores.
  39. * Omit from "scatter" ore for a uniform ore distribution.
  40. * Omit from "stratum" ore for a simple horizontal strata from y_min to y_max.
  41. Example for 2D or 3D perlin noise or perlin noise maps:
  42. np_terrain = {
  43. offset = 0,
  44. scale = 1,
  45. spread = {x = 500, y = 500, z = 500},
  46. seed = 571347,
  47. octaves = 5,
  48. persistence = 0.63,
  49. lacunarity = 2.0,
  50. flags = "defaults, absvalue",
  51. }
  52. For 2D noise the Z component of `spread` is still defined but is ignored. A
  53. single noise parameter table can be used for 2D or 3D noise.
  54. ]]
  55. ---@class mt.NoiseParams
  56. --[[ After the multiplication by `scale` this is added to the result and is the
  57. final step in creating the noise value. Can be positive or negative. ]]
  58. ---@field offset number
  59. --[[ Once all octaves have been combined, the result is multiplied by this.
  60. Can be positive or negative. ]]
  61. ---@field scale number
  62. --[[
  63. For octave1, this is roughly the change of input value needed for a very
  64. large variation in the noise value generated by octave1. It is almost like a
  65. `wavelength` for the wavy noise variation. Each additional octave has a
  66. `wavelength` that is smaller than the previous octave, to create finer detail.
  67. `spread` will therefore roughly be the typical size of the largest structures in
  68. the final noise variation.
  69. `spread` is a vector with values for x, y, z to allow the noise variation to be
  70. stretched or compressed in the desired axes. Values are positive numbers.
  71. ]]
  72. ---@field spread mt.Vector
  73. --[[
  74. This is a whole number that determines the entire pattern of the noise
  75. variation. Altering it enables different noise patterns to be created. With
  76. other parameters equal, different seeds produce different noise patterns and
  77. identical seeds produce identical noise patterns.
  78. For this parameter you can randomly choose any whole number. Usually it is
  79. preferable for this to be different from other seeds, but sometimes it is useful
  80. to be able to create identical noise patterns.
  81. In some noise APIs the world seed is added to the seed specified in noise
  82. parameters. This is done to make the resulting noise pattern vary in different
  83. worlds, and be 'world-specific'.
  84. ]]
  85. ---@field seed number
  86. --[[
  87. The number of simple noise generators that are combined. A whole number, 1 or
  88. more. Each additional octave adds finer detail to the noise but also increases
  89. the noise calculation load. 3 is a typical minimum for a high quality, complex
  90. and natural-looking noise variation. 1 octave has a slight 'gridlike'
  91. appearance.
  92. Choose the number of octaves according to the `spread` and `lacunarity`, and the
  93. size of the finest detail you require. For example: if `spread` is 512 nodes,
  94. `lacunarity` is 2.0 and finest detail required is 16 nodes, octaves will be 6
  95. because the 'wavelengths' of the octaves will be 512, 256, 128, 64, 32, 16
  96. nodes. Warning: If the 'wavelength' of any octave falls below 1 an error will
  97. occur.
  98. ]]
  99. ---@field octaves number
  100. --[[
  101. Each additional octave has an amplitude that is the amplitude of the previous
  102. octave multiplied by `persistence`, to reduce the amplitude of finer details, as
  103. is often helpful and natural to do so. Since this controls the balance of fine
  104. detail to large-scale detail `persistence` can be thought of as the 'roughness'
  105. of the noise.
  106. A positive or negative non-zero number, often between 0.3 and 1.0. A common
  107. medium value is 0.5, such that each octave has half the amplitude of the
  108. previous octave. This may need to be tuned when altering `lacunarity`; when
  109. doing so consider that a common medium value is 1 / lacunarity.
  110. ]]
  111. ---@field persistence number
  112. --[[
  113. Each additional octave has a 'wavelength' that is the 'wavelength' of the
  114. previous octave multiplied by 1 / lacunarity, to create finer detail.
  115. 'lacunarity' is often 2.0 so 'wavelength' often halves per octave.
  116. A positive number no smaller than 1.0. Values below 2.0 create higher quality
  117. noise at the expense of requiring more octaves to cover a paticular range of
  118. 'wavelengths'.
  119. ]]
  120. ---@field lacunarity number
  121. -- Leave this field unset for no special handling.
  122. ---@field flags nil|string
  123. -- Specify this if you would like to keep auto-selection of eased/not-eased
  124. -- while specifying some other flags.
  125. ---|"defaults"
  126. -- Maps noise gradient values onto a quintic S-curve before performing
  127. -- interpolation. This results in smooth, rolling noise. Disable this (`noeased`)
  128. -- for sharp-looking noise with a slightly gridded appearance. If no flags are
  129. -- specified (or defaults is), 2D noise is eased and 3D noise is not eased.
  130. -- Easing a 3D noise significantly increases the noise calculation load,
  131. -- so use with restraint.
  132. ---|"eased"
  133. --The absolute value of each octave's noise variation is used when combining
  134. -- the octaves. The final perlin noise variation is created as follows:
  135. -- noise = offset + scale _ (abs(octave1) + abs(octave2) _ persistence +
  136. -- abs(octave3) _ persistence ^ 2 + abs(octave4) _ persistence ^ 3 + ...)
  137. ---|"absvalue"
  138. -- These tell in what manner the ore is generated.
  139. --
  140. -- All default ores are of the uniformly-distributed `scatter` type.
  141. ---@alias mt.OreType
  142. -- Randomly chooses a location and generates a cluster of ore.
  143. --
  144. -- If `noise_params` is specified, the ore will be placed if the 3D perlin noise
  145. -- at that point is greater than the `noise_threshold`, giving the ability to
  146. -- create a non-equal distribution of ore.
  147. ---|"scatter"
  148. -- Creates a sheet of ore in a blob shape according to the 2D perlin noise
  149. -- described by `noise_params` and `noise_threshold`. This is essentially an
  150. -- improved version of the so-called "stratus" ore seen in some unofficial mods.
  151. --
  152. -- This sheet consists of vertical columns of uniform randomly distributed height,
  153. -- varying between the inclusive range `column_height_min` and `column_height_max`.
  154. -- If `column_height_min` is not specified, this parameter defaults to 1.
  155. -- If `column_height_max` is not specified, this parameter defaults to `clust_size`
  156. -- for reverse compatibility. New code should prefer `column_height_max`.
  157. --
  158. -- The `column_midpoint_factor` parameter controls the position of the column at
  159. -- which ore emanates from.
  160. -- If 1, columns grow upward. If 0, columns grow downward. If 0.5, columns grow
  161. -- equally starting from each direction.
  162. -- `column_midpoint_factor` is a decimal number ranging in value from 0 to 1. If
  163. -- this parameter is not specified, the default is 0.5.
  164. --
  165. -- The ore parameters `clust_scarcity` and `clust_num_ores` are ignored for this
  166. -- ore type.
  167. ---|"sheet"
  168. -- Creates a sheet of ore in a cloud-like puff shape.
  169. --
  170. -- As with the `sheet` ore type, the size and shape of puffs are described by
  171. -- `noise_params` and `noise_threshold` and are placed at random vertical
  172. -- positions within the currently generated chunk.
  173. --
  174. -- The vertical top and bottom displacement of each puff are determined by the
  175. -- noise parameters `np_puff_top` and `np_puff_bottom`, respectively.
  176. ---|"puff"
  177. -- Creates a deformed sphere of ore according to 3d perlin noise described by
  178. -- `noise_params`. The maximum size of the blob is `clust_size`, and
  179. -- `clust_scarcity` has the same meaning as with the `scatter` type.
  180. ---|"blob"
  181. -- Creates veins of ore varying in density by according to the intersection of two
  182. -- instances of 3d perlin noise with different seeds, both described by
  183. -- `noise_params`.
  184. --
  185. -- `random_factor` varies the influence random chance has on placement of an ore
  186. -- inside the vein, which is `1` by default. Note that modifying this parameter
  187. -- may require adjusting `noise_threshold`.
  188. --
  189. -- The parameters `clust_scarcity`, `clust_num_ores`, and `clust_size` are ignored
  190. -- by this ore type.
  191. --
  192. -- This ore type is difficult to control since it is sensitive to small changes.
  193. -- The following is a decent set of parameters to work from:
  194. --
  195. -- noise_params = {
  196. -- offset = 0,
  197. -- scale = 3,
  198. -- spread = {x=200, y=200, z=200},
  199. -- seed = 5390,
  200. -- octaves = 4,
  201. -- persistence = 0.5,
  202. -- lacunarity = 2.0,
  203. -- flags = "eased",
  204. -- },
  205. -- noise_threshold = 1.6
  206. --
  207. -- **WARNING**: Use this ore type *very* sparingly since it is ~200x more
  208. -- computationally expensive than any other ore.
  209. ---|"vein"
  210. -- Creates a single undulating ore stratum that is continuous across mapchunk
  211. -- borders and horizontally spans the world.
  212. --
  213. -- The 2D perlin noise described by `noise_params` defines the Y co-ordinate of
  214. -- the stratum midpoint. The 2D perlin noise described by `np_stratum_thickness`
  215. -- defines the stratum's vertical thickness (in units of nodes). Due to being
  216. -- continuous across mapchunk borders the stratum's vertical thickness is
  217. -- unlimited.
  218. --
  219. -- If the noise parameter `noise_params` is omitted the ore will occur from y_min
  220. -- to y_max in a simple horizontal stratum.
  221. --
  222. -- A parameter `stratum_thickness` can be provided instead of the noise parameter
  223. -- `np_stratum_thickness`, to create a constant thickness.
  224. --
  225. -- Leaving out one or both noise parameters makes the ore generation less
  226. -- intensive, useful when adding multiple strata.
  227. --
  228. -- `y_min` and `y_max` define the limits of the ore generation and for performance
  229. -- reasons should be set as close together as possible but without clipping the
  230. -- stratum's Y variation.
  231. --
  232. -- Each node in the stratum has a 1-in-`clust_scarcity` chance of being ore, so a
  233. -- solid-ore stratum would require a `clust_scarcity` of 1.
  234. --
  235. -- The parameters `clust_num_ores`, `clust_size`, `noise_threshold` and
  236. -- `random_factor` are ignored by this ore type.
  237. ---|"stratum"
  238. ---@alias mt.OreFlagString
  239. -- If set, puff ore generation will not taper down large differences in
  240. -- displacement when approaching the edge of a puff. This flag has no effect for
  241. -- ore types other than `puff`.
  242. ---|"puff_cliffs"
  243. -- By default, when noise described by `np_puff_top` or `np_puff_bottom` results
  244. -- in a negative displacement, the sub-column at that point is not generated. With
  245. -- this attribute set, puff ore generation will instead generate the absolute
  246. -- difference in noise displacement values. This flag has no effect for ore types
  247. -- other than `puff`.
  248. ---|"puff_additive_composition"
  249. ---@alias mt.OreFlagsTable table<mt.OreFlagString|string, boolean>
  250. ---@alias mt.OreFlags mt.OreFlagString|mt.OreFlagsTable