jecs/modules/Spring/vector3.luau

--!native
--!optimize 2
--!strict

export type Spring = {
	type: "Vector3",
	d: number,
	f: number,
	g: Vector3,
	p: Vector3,
	v: vector
}

local EPS = 1e-5 -- epsilon for stability checks around pathological frequency/damping values

local function create(d: number, f: number, origo: Vector3, goal: Vector3): Spring
	return {
		type = "Vector3",
		d = d,
		f = f,
		g = goal,
		p = origo,
		v = vector.create(0, 0, 0),
	}
end

local function step(spring: Spring, dt: number): Vector3
	local f = spring.f
	local d = spring.d
	local g = (spring.g :: any)::vector
	local v = spring.v
	local p = (spring.p :: any)::vector

	if d == 1 then -- critically damped
		local q = math.exp(-f*dt)
		local w = dt*q

		local c0 = q + w*f
		local c2 = q - w*f
		local c3 = w*f*f

		local o = p - g
		p = o * c0 + v * w + g
		v = v * c2 - o * c3
	elseif d < 1 then -- underdamped
		local q = math.exp(-d*f*dt)
		local c = math.sqrt(1 - d*d)

		local i = math.cos(dt*f*c)
		local j = math.sin(dt*f*c)

		-- Damping ratios approaching 1 can cause division by very small numbers.
		-- To mitigate that, group terms around z=j/c and find an approximation for z.
		-- Start with the definition of z:
		--    z = sin(dt*f*c)/c
		-- Substitute a=dt*f:
		--    z = sin(a*c)/c
		-- Take the Maclaurin expansion of z with respect to c:
		--    z = a - (a^3*c^2)/6 + (a^5*c^4)/120 + O(c^6)
		--    z ≈ a - (a^3*c^2)/6 + (a^5*c^4)/120
		-- Rewrite in Horner form:
		--    z ≈ a + ((a*a)*(c*c)*(c*c)/20 - c*c)*(a*a*a)/6

		local z
		if c > EPS then
			z = j/c
		else
			local a = dt*f
			z = a + ((a*a)*(c*c)*(c*c)/20 - c*c)*(a*a*a)/6
		end

		-- Frequencies approaching 0 present a similar problem.
		-- We want an approximation for y as f approaches 0, where:
		--    y = sin(dt*f*c)/(f*c)
		-- Substitute b=dt*c:
		--    y = sin(b*c)/b
		-- Now reapply the process from z.

		local y
		if f*c > EPS then
			y = j/(f*c)
		else
			local b = f*c
			y = dt + ((dt*dt)*(b*b)*(b*b)/20 - b*b)*(dt*dt*dt)/6
		end

		local o = p - g

		p = (o * (i + z*d) + v * y) * q + g
		v = (v * (i - z*d) - o * (z*f)) * q
	else -- overdamped
		local c = math.sqrt(d*d - 1)

		local r1 = -f*(d + c)
		local r2 = -f*(d - c)

		local ec1 = math.exp(r1*dt)
		local ec2 = math.exp(r2*dt)

		local o = p - g

		local co2 = (v - o*r1)/(2*f*c)
		local co1 = ec1*(o - co2)

		p = co1 + co2*ec2 + g
		v = co1*r1 + co2*ec2*r2
	end

	spring.p = (p :: any) :: Vector3
	spring.v = (v :: any) :: Vector3
	return (p :: any) :: Vector3
end

local SLEEP_OFFSET_SQ_LIMIT = (1/3840)^2 -- square of the offset sleep limit
local SLEEP_VELOCITY_SQ_LIMIT = 1e-2^2 -- square of the velocity sleep limit

local function can_sleep(spring: Spring): boolean
	if vector.magnitude(spring.v)^2 > SLEEP_VELOCITY_SQ_LIMIT then
		return false
	end

	if (spring.p - spring.g).Magnitude^2 > SLEEP_OFFSET_SQ_LIMIT then
		return false
	end

	return true
end

return {
	create = create,
	step = step,
	can_sleep = can_sleep,
}