FuzzyEq documentation poorly describes implemented behavior

Bug Reports Documentation Issues
,
#1

The documentation of Vector3::FuzzyEq currently reads as:

Returns true if the X, Y, and Z components of the other Vector3 are within epsilon units of each corresponding component of this Vector3.

This (brief) description does not accurate encompass what the function does. As described in Vector3:FuzzyEq (and its alias :isClose) return incorrect results - #2 by evaera, the Vector3::FuzzyEq method is not as simple as performing an epsilon check between two points.

Expected vs Actual Behavior

If Vector3::FuzzyEq was to perform an epsilon check between two points, one might write this function and expect it to produce the same results:

--[[ Checks if the [closed ball](https://en.wikipedia.org/wiki/Ball_(mathematics)) of `b` contains point `a`. ]]
local function vecEpsilonCheck(a: Vector3, b: Vector3, epsilon: number): boolean
	return math.abs(a.X - b.X) <= epsilon and math.abs(a.Y - b.Y) <= epsilon and math.abs(a.Z - b.Z) <= epsilon
end

this function indeed does exactly what Vector3::FuzzyEq says it does – it checks that each component is within epsilon units of the corresponding component.

However, the actual implementation in the engine appears to be closer to what @evaera wrote:

function fuzzyEq(a, b, epsilon)
	return a == b or math.abs(a - b) <= (math.abs(a) + 1) * epsilon
end

function fuzzyEqVec(v1, v2, epsilon)
	for _, axis in ipairs({"X", "Y", "Z"}) do
		if not fuzzyEq(v1[axis], v2[axis], epsilon) then
			return false
		end
	end
	
	return true
end

which has some key differences:

  • The implementation scales as vectors get larger (likely to accommodate for floating point magic?)
  • Similar to CFrame::FuzzyEq, which specifies epsilon should be small and positive
  • Returns true for more cases than the simple vecEpsilonCheck closed ball check

It would be helpful for an engineer or someone to check the implementation of Vector3::FuzzyEq, and write some better docs about how this function actually works.

Ideally the docs explain (or at least point to) the scaling behavior, indicate that the epsilon should be small and positive (like CFrame::FuzzyEq), and potentially warn developers about larger epsilon values producing unexpected results.

Page URL: https://create.roblox.com/docs/reference/engine/datatypes/Vector3#FuzzyEq

1 Like
#2

Thanks for the report! We’ll follow up when we have an update for you!

1 Like