LuaAPI/mathx - Revision history

Celtic Minstrel: Document lerp_index

2024-09-21T17:47:56Z

Document lerp_index

Shiki: /* mathx.random */ Move text

2024-06-17T23:15:38Z

‎mathx.random: Move text

Shiki: /* mathx.random */ Go more into details, when porting from helper.rand one might overlook these cases.

2024-06-17T21:38:14Z

‎mathx.random: Go more into details, when porting from helper.rand one might overlook these cases.

Laela at 18:04, 18 April 2024

2024-04-18T18:04:31Z

Celtic Minstrel: Document clamp and lerp

2023-02-06T03:44:08Z

Document clamp and lerp

Celtic Minstrel: Fix an incorrect header

2023-02-06T03:39:23Z

Fix an incorrect header

Celtic Minstrel: Document the mathx module

2021-06-30T02:27:59Z

Document the mathx module

New page

==== mathx.random ====

* '''mathx.random'''([''m'', [''n'']]) → ''random number''

This function returns a random number generated by the synced random generator, which is also used by [set_variable]rand=. This function has the same interface as [http://www.lua.org/manual/5.2/manual.html#pdf-math.random math.random] so it can take 0, 1 or 2 arguments.

In map generation scripts, the values returned by this function depend on the seed the map author has input (if any).

Be careful as '''random''' is not safe in certain events, see [[EventWML#Multiplayer_safety|Multiplayer_safety]].

==== mathx.random_choice ====

* '''mathx.random_choice'''(''spec'') → ''choice''

Chooses a random element from its input. The input can be a string (as
[[InternalActionsWML#.5Bset_variable.5D|set_variable's rand=]]), in which case it will be split on commas and consider integer ranges; or it can be a Lua array, in which case the elements can be either simple values or a table of two integers, representing a range.

<syntaxhighlight lang=lua>
-- create a random unit at (1, 1) on side=1 :
wesnoth.units.to_map{
type = mathx.random_choice{"Dwarvish Fighter", "Dwarvish Thunderer", "Dwarvish Scout"}
x = 1, y = 1
}
</syntaxhighlight>

Note that '''random_choice''' is only safe in certain events, see [[EventWML#Multiplayer_safety|Multiplayer Safety]].

==== mathx.round ====

* '''mathx.round'''(''n'') → ''number''

Rounds a number to the nearest integer, using the "round half away from zero" method (see [http://en.wikipedia.org/wiki/Rounding_numbers#Round_half_away_from_zero here] for a more detailed explanation).

<syntaxhighlight lang=lua>
-- this number will be rounded up
mathx.round(345.67) -- returns 346
-- this one will be rounded down
mathx.round(543.21) -- returns 543
-- an integer stays integer
mathx.round(123) -- returns 123
-- works also for negative numbers
mathx.round(-369.84) -- returns -370
mathx.round(-246.42) -- returns -246
</syntaxhighlight>

==== helper.shuffle ====

* '''mathx.shuffle'''(''array'', [''random function''])

This function randomly sorts in place the elements of the table passed as argument, following the Fisher-Yates algorithm. It returns no value.

<syntaxhighlight lang=lua>
local locs = wesnoth.map.find{ terrain="G*" }
mathx.shuffle(locs)
</syntaxhighlight>

This function uses the synced RNG ('''mathx.random''') by default and should not cause out-of-sync errors. It is also possible to pass a different random generator as a second argument; a random generator is a function that takes two integers ''a'' and ''b'' and returns a random integer in the range [''a'',''b'']. For example, '''math.random''' can be passed if you need unsynced random calls (for example because it's used for user interface code):

<syntaxhighlight lang=lua>
local locs = wesnoth.map.find{ terrain="G*" }
mathx.shuffle(locs, math.random)
</syntaxhighlight>

[[Category: Lua Reference]]

← Older revision		Revision as of 17:47, 21 September 2024
Line 16:		Line 16:

	Calculates a linear interpolation between ''min'' and ''max''. If ''alpha'' is 0, it will return ''min''. If ''alpha'' is 1, it will return ''max''. If ''alpha'' is between 0 and 1, it interpolates between them. Values outside the range will yield an extrapolation.		Calculates a linear interpolation between ''min'' and ''max''. If ''alpha'' is 0, it will return ''min''. If ''alpha'' is 1, it will return ''max''. If ''alpha'' is between 0 and 1, it interpolates between them. Values outside the range will yield an extrapolation.
		+
		+	==== mathx.lerp_index ====
		+
		+	{{DevFeature1.19\|4}}
		+
		+	* '''mathx.lerp_index'''(''array'', ''ratio'') → ''closest value''
		+
		+	Returns the element of the array that falls closest to the specified ratio of its length.
		+
		+	'''Example''': <syntaxhighlight lang=lua inline>mathx.lerp_index({12, 32, 8, 97}, 0.27})</syntaxhighlight> returns 32.

	==== mathx.random ====		==== mathx.random ====

← Older revision		Revision as of 21:38, 17 June 2024
Line 26:		Line 26:

	Be careful as '''random''' is not safe in certain events, see [[EventWML#Multiplayer_safety\|Multiplayer_safety]].		Be careful as '''random''' is not safe in certain events, see [[EventWML#Multiplayer_safety\|Multiplayer_safety]].
		+
		+	Some things to watch out:
		+	* When giving 1 argument, you need to guarantee that it is greater than 0.
		+	** If your smallest value possible is 0, you can use the form mathx.random(0, n) instead.
		+	* When giving 2 arguments, the first is not allowed to be bigger than the second one.

	==== mathx.random_choice ====		==== mathx.random_choice ====

← Older revision		Revision as of 18:04, 18 April 2024
Line 1:		Line 1:
		+	== Functions ==

	==== mathx.clamp ====		==== mathx.clamp ====

← Older revision		Revision as of 03:44, 6 February 2023
Line 1:		Line 1:
		+
		+	==== mathx.clamp ====
		+
		+	{{DevFeature1.17\|0}}
		+
		+	* '''mathx.clamp'''(''value'', ''min'', ''max'') → ''clamped value''
		+
		+	Clamps a value between a specified minimum and maximum. If the ''value'' is less then ''min'', it returns ''min''. If the value is greater than ''max'', it returns ''max''. Otherwise, it returns ''value''.
		+
		+	==== mathx.lerp ====
		+
		+	{{DevFeature1.17\|0}}
		+
		+	* '''mathx.lerp'''(''min'', ''max'', ''alpha'') → ''interpolated value''
		+
		+	Calculates a linear interpolation between ''min'' and ''max''. If ''alpha'' is 0, it will return ''min''. If ''alpha'' is 1, it will return ''max''. If ''alpha'' is between 0 and 1, it interpolates between them. Values outside the range will yield an extrapolation.

	==== mathx.random ====		==== mathx.random ====

@@ Line 22: / Line 22: @@
 This function returns a random number generated by the synced random generator, which is also used by [set_variable]rand=. This function has the same interface as [http://www.lua.org/manual/5.2/manual.html#pdf-math.random math.random] so it can take 0, 1 or 2 arguments.
 In map generation scripts, the values returned by this function depend on the seed the map author has input (if any).
@@ Line 27: / Line 31: @@
 Be careful as '''random''' is not safe in certain events, see [[EventWML#Multiplayer_safety|Multiplayer_safety]].
 ==== mathx.random_choice ====

@@ Line 45: / Line 45: @@
 </syntaxhighlight>
-==== helper.shuffle ====
+==== mathx.shuffle ====
 * '''mathx.shuffle'''(''array'', [''random function''])