diff --git a/data/scripts/types/vector3.lua b/data/scripts/types/vector3.lua index 79c852a..a173e4b 100644 --- a/data/scripts/types/vector3.lua +++ b/data/scripts/types/vector3.lua @@ -1,3 +1,7 @@ +--- @class Vector3 +--- @field x number +--- @field y number +--- @field z number local Vector3 = { x = 0, y = 0, @@ -8,6 +12,9 @@ local Vector3 = { setmetatable(Vector3, Vector3) +---Returns true if the provided table can be coerced into a Vector3. +---@param t table +---@return boolean local function is_weak_vector3(t) if type(t) ~= "table" then return false end @@ -19,6 +26,9 @@ local function is_weak_vector3(t) end end +---Returns a Vector3 multiplied either component-wise (if b is a weak table) or multiplies each component by b if b is a number. +---@param b number|table|Vector3 +---@return Vector3 function Vector3:__mul(b) if type(b) == "number" then return Vector3{ @@ -39,6 +49,9 @@ function Vector3:__mul(b) return Vector3() end +---Returns a Vector3 divided either component-wise (if b is a weak table) or divides each component by b if b is a number. +---@param b number|table|Vector3 +---@return Vector3 function Vector3:__div(b) if type(b) == "number" then return Vector3{ @@ -59,6 +72,9 @@ function Vector3:__div(b) return Vector3() end +---Returns a Vector3 with each component added together. +---@param b table|Vector3 +---@return Vector3 function Vector3:__add(b) if not is_weak_vector3(b) then error("Vector3: other must be a Vector3-like table.") @@ -72,6 +88,9 @@ function Vector3:__add(b) } end +---Returns a Vector3 with this vector's components subtracted from b. +---@param b table|Vector3 +---@return Vector3 function Vector3:__sub(b) if not is_weak_vector3(b) then error("Vector3: other must be a Vector3-like table.") @@ -85,6 +104,8 @@ function Vector3:__sub(b) } end +---Returns a new Vector3 with each component being a negation of this. +---@return Vector3 function Vector3:__unm() return Vector3{ -self.x, @@ -141,6 +162,9 @@ function Vector3:normalized() return Vector3(self.x / length, self.y / length, self.z / length) end +---Returns the dot product of this vector with `with`. +---@param with table|Vector3 +---@return number function Vector3:dot(with) if not is_weak_vector3(with) then error("Vector3: with must be a Vector3-like table. Returning 0") @@ -151,6 +175,9 @@ function Vector3:dot(with) return self.x * v2.x + self.y * v2.y + self.z * v2.z end +---Returns the cross product of this vector with `with`. +---@param with table|Vector3 +---@return Vector3 function Vector3:cross(with) if not is_weak_vector3(with) then error("Vector3: with must be a Vector3-like table. Returning Vector3()") @@ -164,7 +191,10 @@ function Vector3:cross(with) } end - +---Returns a vector rotated about `axis` by `angle` radians +---@param axis table|Vector3 +---@param angle number +---@return Vector3 function Vector3:rotated(axis, angle) if not is_weak_vector3(axis) then error("Vector3: axis must be a Vector3-like table. Returning Vector3()") @@ -177,7 +207,7 @@ function Vector3:rotated(axis, angle) -- __mul is only defined for the left operand (table), numbers don't get metatables. -- as such, the ordering of operations here is specific local v = (self * cosa) + (axis * ((1 - cosa) * self:dot(axis))) + (axis:cross(self) * sina) - return v + return Vector3(v) end ---- CONSTANTS