跳到主要内容
中文系列课

Vector

表示一个包含三个分量的向量。使用 Vector.xy 创建的向量 z = 0。所有长度和插值运算（length、dot、distance、normalized、lerp 等）都会使用全部三个分量；当 z = 0 时，它们的行为与 2D 数学完全一致。

字段​

x​

向量的 x 分量（只读）。

local v = Vector.xy(10, -5)
local xValue = v.x  -- 10

y​

向量的 y 分量（只读）。

local v = Vector.xy(10, -5)
local yValue = v.y  -- -5

z​

向量的 z 分量（只读）。使用 Vector.xy 创建的向量该值为零；由返回 Vector 的 3D API 填充。

local v = m:transformPoint(1, 2, 3)
local zValue = v.z

构造函数​

xy​

xy(x: number, y: number) -> Vector

创建一个具有指定 x 和 y 分量的向量。

local v = Vector.xy(5, -2)  -- 5 -2

xyz​

xyz(x: number, y: number, z: number) -> Vector

创建一个具有指定 x、y 和 z 分量的向量。

local v = Vector.xyz(1, 2, 3)

origin​

origin() -> Vector

返回零向量 (0, 0)。

local origin = Vector.origin()  -- 0 0

cross3​

cross3(a: Vector, b: Vector) -> Vector

返回两个向量的 3D 叉积。

local z = Vector.cross3(Vector.xyz(1,0,0), Vector.xyz(0,1,0))  -- 0 0 1

scaleAndAdd​

scaleAndAdd(a: Vector, b: Vector, scale: number) -> Vector

返回 a + b * scale。

local r = Vector.scaleAndAdd(Vector.xy(1,2), Vector.xy(3,4), 2)  -- 7 10

scaleAndSub​

scaleAndSub(a: Vector, b: Vector, scale: number) -> Vector

返回 a - b * scale。

local r = Vector.scaleAndSub(Vector.xy(7,10), Vector.xy(3,4), 2)  -- 1 2

lerp​

lerp(from: Vector, to: Vector, t: number) -> Vector

返回 from 向量与 to 向量之间的线性插值，使用 t，其中 0 返回 from 向量，1 返回 to 向量。

local p = Vector.lerp(Vector.xy(0,0), Vector.xy(8,0), 0.25)  -- 2 0

normalized​

normalized(v: Vector) -> Vector

返回给定向量的归一化副本。

local n = Vector.normalized(Vector.xy(10, 0))  -- Vector.xy(1, 0)

静态函数​

distance​

distance(a: Vector, b: Vector) -> number

返回两个向量之间的距离。

local d = Vector.distance(Vector.xy(3, 4), Vector.xy(0, 0))  -- 5

distanceSquared​

distanceSquared(a: Vector, b: Vector) -> number

返回两个向量之间距离的平方。

local d2 = Vector.distanceSquared(Vector.xy(3,4), Vector.xy(0,0))  -- 25

dot​

dot(a: Vector, b: Vector) -> number

返回两个向量的点积。

local dp = Vector.dot(Vector.xy(1,2), Vector.xy(3,4))  -- 11 (1*3 + 2*4)

cross​

cross(a: Vector, b: Vector) -> number

返回两个向量的叉积（3D 叉积的 z 分量）。

local c = Vector.cross(Vector.xy(1, 0), Vector.xy(0, 1))  -- 1

length​

length(v: Vector) -> number

返回给定向量的长度。

local len = Vector.length(Vector.xy(3, 4))  -- 5

lengthSquared​

lengthSquared(v: Vector) -> number

返回给定向量长度的平方。

local len2 = Vector.lengthSquared(Vector.xy(3, 4))  -- 25

方法​

length​

length() -> number
注意

已弃用 - 请改用 Vector.length。

返回向量的长度。

lengthSquared​

lengthSquared() -> number
注意

已弃用 - 请改用 Vector.lengthSquared。

返回向量长度的平方。

local v = Vector.xy(3, 4)
local len2 = v:lengthSquared()  -- 25

normalized​

normalized() -> Vector
注意

已弃用 - 请改用 Vector.normalized。

返回向量的归一化副本。如果长度为零，结果为零向量。

local v = Vector.xy(10, 0)
local n = v:normalized()  -- 1 0

__eq​

__eq(rhs: Vector) -> boolean

如果两个向量的各分量相等，则返回 true。

local a = Vector.xy(1, 2)
local b = Vector.xy(1, 2)
local c = Vector.xy(2, 1)
print(a == b)  -- true
print(a == c)  -- false

__unm​

__unm() -> Vector

返回取反后的向量。

local v = Vector.xy(2, -3)
local neg = -v   -- -2 3

__add​

__add(rhs: Vector) -> Vector

返回两个向量的和。

local a = Vector.xy(2, 3)
local b = Vector.xy(-1, 5)
local c = a + b  -- 1 8

__sub​

__sub(rhs: Vector) -> Vector

返回两个向量的差。

local a = Vector.xy(2, 3)
local b = Vector.xy(-1, 5)
local c = a - b  -- 3 -2

__mul​

__mul(rhs: number) -> Vector

返回按给定数值缩放后的向量。

local v = Vector.xy(3, -2)
local doubled = v * 2    -- 6 -4

__div​

__div(rhs: number) -> Vector

返回除以给定数值后的向量。

local v = Vector.xy(6, -4)
local half = v / 2    -- 3 -2

distance​

distance(other: Vector) -> number
注意

已弃用 - 请改用 Vector.distance。

返回到另一个向量的距离。

local a = Vector.xy(0, 0)
local b = Vector.xy(3, 4)
print(a:distance(b))  -- 5

distanceSquared​

distanceSquared(other: Vector) -> number
注意

已弃用 - 请改用 Vector.distanceSquared。

返回到另一个向量距离的平方。

local a = Vector.xy(0, 0)
local b = Vector.xy(3, 4)
print(a:distanceSquared(b))  -- 25

dot​

dot(other: Vector) -> number
注意

已弃用 - 请改用 Vector.dot。

返回该向量与另一个向量的点积。

local a = Vector.xy(1, 2)
local b = Vector.xy(3, 4)
print(a:dot(b))  -- 11  (1*3 + 2*4)

lerp​

lerp(other: Vector, t: number) -> Vector
注意

已弃用 - 请改用 Vector.lerp。

返回该向量与另一个向量之间的线性插值，使用 t，其中 0 返回该向量，1 返回另一个向量。

local a = Vector.xy(0, 0)
local b = Vector.xy(10, 0)
local p = a:lerp(b, 0.5)  -- 5 0

writeToBuffer​

writeToBuffer(buf: buffer, byteOffset: number) -> ()

将 x、y、z 作为 12 字节（三个 float32）写入缓冲区中 byteOffset 处。

local buf = buffer.create(12)
Vector.xyz(1, 2, 3):writeToBuffer(buf, 0)

writeVec4​

writeVec4(buf: buffer, byteOffset: number, w: number) -> ()

将 x、y、z、w 作为 16 字节（四个 float32）写入缓冲区中 byteOffset 处，与 vec4 uniform-buffer 槽位匹配。

local ubo = buffer.create(16)
lightDir:writeVec4(ubo, 0, 0)  -- w = 0 for a direction