From 0e5ef94579d90762c117c537020100f9a488ecde Mon Sep 17 00:00:00 2001 From: ramdoys Date: Fri, 27 Feb 2026 23:24:10 -0500 Subject: [PATCH 1/3] RFC: Add vector.sqrmagnitude function --- docs/squaredmagnitude.md | 51 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/squaredmagnitude.md diff --git a/docs/squaredmagnitude.md b/docs/squaredmagnitude.md new file mode 100644 index 00000000..de622914 --- /dev/null +++ b/docs/squaredmagnitude.md @@ -0,0 +1,51 @@ +# Squared Magnitude + +## Summary + +Introduce a `vector.sqrmagnitude` function to the vector library. This function will return the squared magnitude of a vector. + +## Motivation + +The squared magnitude of a vector is commonly used in game development. It is used for distance checks, hitbox detection, and more. In all of these cases, the actual magnitude is unnecessary. Only the relative comparison matters. This makes the square root in `vector.magnitude` an avoidable cost. Currently, the idiomatic way to compute squared magnitude in Luau is to use `vector.dot(vector, vector).` While this produces the correct result, there are problems with this: + +First, ergonomics. The most common use case for squared magnitude is comparing the squared distance between two points, which looks like this: + +```luau +local difference = vector1 - vector2 +local range = 100 + +if vector.dot(difference, difference) < range^2 then + --Within the range. +end +``` + +Developers are forced to store the difference in a local variable because `vector.dot` requires two arguments, or must subtract the two vectors twice for the arguments. With `vector.sqrmagnitude`, this becomes a single inline expression: + +```luau +local range = 100 +if vector.sqrmagnitude(vector1 - vector2) < range^2 then + --Within the range. +end +``` + +Even outside of distance comparisons, it is much easier and more understandable to write `vector.sqrmagnitude(vector)` than `vector.dot(vector, vector)`. + +Second, performance. When computing the squared distance between two points, the alternative `vector.dot(vector1 - vector2, vector1 - vector2)` computes the subtraction twice. A single parameter `vector.sqrmagnitude(vector1 - vector2)` avoids this redundancy. The subtraction is computed once and operated on directly. In case of `vector.dot`, even if someone stored the difference in a local, `vector.sqrmagnitude` would still potentially be faster since it is handled as a single intrinsic rather than going through the dot product way. + +Third, ubiquity. Squared magnitude is widely used in code where only relative comparisons are required. Many math libraries and game engines expose it due to its frequency. + +## Design + +Add one new function to the vector library: + +`vector.sqrmagnitude(vector: vector): number` + +Returns the squared magnitude of the given vector. This is equivalent to the sum of the squares of the vector's components. + +## Drawbacks + +Just like all the other vector library functions, it is safe to assume this will use a fastcall slot. Adding this function will also increase the size of the standard library. + +## Alternatives + +Do not implement the function. People can continue using `vector.dot(vector, vector)` for the same result. \ No newline at end of file From f01a73ef85913ac8cc949f0a5662cc1e20806848 Mon Sep 17 00:00:00 2001 From: ramdoys Date: Sat, 28 Feb 2026 17:00:23 -0500 Subject: [PATCH 2/3] revisions --- docs/squaredmagnitude.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/squaredmagnitude.md b/docs/squaredmagnitude.md index de622914..2f72e722 100644 --- a/docs/squaredmagnitude.md +++ b/docs/squaredmagnitude.md @@ -1,4 +1,4 @@ -# Squared Magnitude +# vector.sqrmagnitude ## Summary @@ -6,12 +6,12 @@ Introduce a `vector.sqrmagnitude` function to the vector library. This function ## Motivation -The squared magnitude of a vector is commonly used in game development. It is used for distance checks, hitbox detection, and more. In all of these cases, the actual magnitude is unnecessary. Only the relative comparison matters. This makes the square root in `vector.magnitude` an avoidable cost. Currently, the idiomatic way to compute squared magnitude in Luau is to use `vector.dot(vector, vector).` While this produces the correct result, there are problems with this: +The squared magnitude of a vector is commonly used in game development. It is used for distance checks, hitbox detection, and more. In all of these cases, the actual magnitude is unnecessary. Only the relative comparison matters. This makes the square root in `vector.magnitude` an avoidable cost. Currently, the idiomatic way to compute squared magnitude in Luau is to use `vector.dot(vec, vec)`. While this produces the correct result, there are problems with this: First, ergonomics. The most common use case for squared magnitude is comparing the squared distance between two points, which looks like this: ```luau -local difference = vector1 - vector2 +local difference = vec1 - vec2 local range = 100 if vector.dot(difference, difference) < range^2 then @@ -23,14 +23,14 @@ Developers are forced to store the difference in a local variable because `vecto ```luau local range = 100 -if vector.sqrmagnitude(vector1 - vector2) < range^2 then +if vector.sqrmagnitude(vec - vec2) < range^2 then --Within the range. end ``` -Even outside of distance comparisons, it is much easier and more understandable to write `vector.sqrmagnitude(vector)` than `vector.dot(vector, vector)`. +Even outside of distance comparisons, it is much easier and more understandable to write `vector.sqrmagnitude(vec)` than `vector.dot(vec, vec)`. -Second, performance. When computing the squared distance between two points, the alternative `vector.dot(vector1 - vector2, vector1 - vector2)` computes the subtraction twice. A single parameter `vector.sqrmagnitude(vector1 - vector2)` avoids this redundancy. The subtraction is computed once and operated on directly. In case of `vector.dot`, even if someone stored the difference in a local, `vector.sqrmagnitude` would still potentially be faster since it is handled as a single intrinsic rather than going through the dot product way. +Second, performance. When computing the squared distance between two points, the alternative `vector.dot(vec1 - vec2, vec1 - vec2)` computes the subtraction twice. A single parameter `vector.sqrmagnitude(vec1 - vec2)` avoids this redundancy. The subtraction is computed once and operated on directly. In case of `vector.dot`, even if someone stored the difference in a local, `vector.sqrmagnitude` would still potentially be faster since it is handled as a single intrinsic rather than going through the dot product way. Third, ubiquity. Squared magnitude is widely used in code where only relative comparisons are required. Many math libraries and game engines expose it due to its frequency. @@ -38,9 +38,9 @@ Third, ubiquity. Squared magnitude is widely used in code where only relative co Add one new function to the vector library: -`vector.sqrmagnitude(vector: vector): number` +`vector.sqrmagnitude(vec: vector): number` -Returns the squared magnitude of the given vector. This is equivalent to the sum of the squares of the vector's components. +Returns the squared magnitude of the given vector. This is equivalent to the sum of the squares of all of the vector's components, which includes the 4th component in 4-wide mode. ## Drawbacks @@ -48,4 +48,4 @@ Just like all the other vector library functions, it is safe to assume this will ## Alternatives -Do not implement the function. People can continue using `vector.dot(vector, vector)` for the same result. \ No newline at end of file +Do not implement the function. People can continue using `vector.dot(vec, vec)` for the same result. From 859160b02b6d0bdc34101a34b8ec32cd811c4b35 Mon Sep 17 00:00:00 2001 From: ramdoys Date: Sun, 1 Mar 2026 08:20:26 -0500 Subject: [PATCH 3/3] consistent vec naming --- docs/squaredmagnitude.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/squaredmagnitude.md b/docs/squaredmagnitude.md index 2f72e722..88a206e4 100644 --- a/docs/squaredmagnitude.md +++ b/docs/squaredmagnitude.md @@ -23,7 +23,7 @@ Developers are forced to store the difference in a local variable because `vecto ```luau local range = 100 -if vector.sqrmagnitude(vec - vec2) < range^2 then +if vector.sqrmagnitude(vec1 - vec2) < range^2 then --Within the range. end ```