luau-lang/rfcs
1
0
Fork 0
mirror of https://github.com/luau-lang/rfcs.git synced 2025-05-04 10:43:48 +01:00
Code Issues Projects Releases Packages Wiki Activity

Add math.map to the standard library

Browse source
This commit is contained in:
MagmaBurnsV 2024-09-07 15:08:51 -04:00 • committed by GitHub
parent b344467d6a
commit 17bfcac8ea
Signed by: DevComp
GPG key ID: B5690EEEBB952194
1 changed files with 36 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
docs/function-math-map.md Normal file
View file

@ -0,0 +1,36 @@
# math.map
## Summary
Add a `map` function to the `math` library, which maps a number from one range to another.
## Motivation
Numerical mapping is a very common operation within game development. With only a brief search of the CoreScript source on the Roblox Client Tracker, there are about [three](https://github.com/MaximumADHD/Roblox-Client-Tracker/blob/9add9114d12e24cf08fa5680dbc95ace2af5c981/scripts/CoreScripts/Modules/PlayerList/Components/PresentationMobile/PlayerListApp.lua#L51) [different](https://github.com/MaximumADHD/Roblox-Client-Tracker/blob/9add9114d12e24cf08fa5680dbc95ace2af5c981/scripts/PlayerScripts/StarterPlayerScriptsCommon/RbxCharacterSounds.lua#L55) [implementations](https://github.com/MaximumADHD/Roblox-Client-Tracker/blob/9add9114d12e24cf08fa5680dbc95ace2af5c981/scripts/PlayerScripts/StarterPlayerScripts/PlayerModule.module/CameraModule/CameraUtils.lua#L53) of this function, each having about five to ten uses per context.
A native function would help boost ergonomics and provide potential performance benefits in these cases.
## Design
A new function, `math.map`, will be added and will act equivalently to the following user-defined function.
```luau
function math.map(x: number, inmin: number, inmax: number, outmin: number, outmax: number): number
return outmin + (x - inmin) * (outmax - outmin) / (inmax - inmin)
end
```
Just like common Luau implementations, `x` is allowed to be outside the input range. Since clamped mapping is not as widely used and can be easily replicated using `math.clamp`, it would not be supported.
## Drawbacks
This would add a new function to the native library, taking yet another fastcall slot.
The function may also not provide enough performance improvements to warrant its addition, so implementations of this should be benchmarked.
## Alternatives
Not doing anything and letting people continue writing their own mapping functions. This would keep the same problems as before.
If the use of clamped mapping turns out to be more widespread, then adding an optional sixth argument to enable clamping could be considered. Not doing this may lead to the same problem of people writing their own implementations as before.