RFC: Add vector.sqrmagnitude function

[Ramdoys]

Rendered

[Copilot]

Pull request overview

Adds an RFC document proposing a new vector.sqrmagnitude standard library function, intended to provide an ergonomic and faster alternative to vector.dot(v, v) for squared-length comparisons in vector-heavy code.

Changes:

• Introduces a new RFC doc describing vector.sqrmagnitude and its motivation/design.
• Provides example code showing the ergonomic benefit over vector.dot.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The design section doesn’t specify 4-wide mode behavior. vector.magnitude explicitly says it includes the 4th component in 4-wide mode (see docs/vector-library.md), and vector.dot notes its 4-wide behavior as well. Please clarify whether vector.sqrmagnitude also includes the 4th component in 4-wide mode, to avoid ambiguity for implementers and users.

Suggested change

	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 (in 4-wide mode, this includes the fourth component).

[Copilot]

The inline code snippet includes the trailing period inside the backticks: vector.dot(vector, vector).. That makes the expression incorrect/misleading; the period should be punctuation outside the code span.

Suggested change

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(vector, vector)`. While this produces the correct result, there are problems with this:

[Copilot]

The document title is "Squared Magnitude", but other function RFCs use the fully-qualified function name as the H1 (e.g. # vector.lerp). Consider renaming the H1 to vector.sqrmagnitude (and optionally renaming the file to the docs/function-vector-*.md pattern) to keep the docs consistent and easier to find.

Suggested change

	# Squared Magnitude
	# vector.sqrmagnitude

[Copilot]

In the proposed signature, the parameter name is vector (vector.sqrmagnitude(vector: vector): number). This is confusing because it matches both the library name and the type name; other vector library signatures use vec/vec1/vec2 (see docs/vector-library.md). Rename the parameter to vec for consistency and readability.

Suggested change

	`vector.sqrmagnitude(vector: vector): number`
	`vector.sqrmagnitude(vec: vector): number`

[Ramdoys]

Why does Copilot do that...