工坊手册

主题

SpaceUnit ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

继承成员 ​

1 个来源 / 4 属性 / 25 函数 / 6 事件

空间单位的公共基类，为所有存在于三维世界中的单位统一提供轴心变换、标签管理与空间层级查询能力。它以轴心为核心完成整体的位置与朝向调整，支持沿自身局部坐标系做相对位移，并可按名称增删与查询标签。判断对象是否处于层级顶层或向上查找顶层对象也由它负责。

适用场景 ​

在场景中创建好具体单位后，需要把它们当作一个整体搬动或打上分组标记时使用，例如将一个模型单位移动到目标轴心位置再补充标签，便于后续按标签统一处理。

使用要点 ​

SpaceUnit 不能直接创建，应先通过 world:CreateUnit("WorldUnit", {...}) 或 world:CreateUnit("TriggerUnit", {...}) 得到具体子类实例，再调用其继承来的能力。读取整体变换用 GetPivot 拿到 CFrame，整体设置用 PivotTo，做相对调整用 ApplyPivotDelta，需要沿对象自身坐标系平移则用 TranslateBy。标签相关操作按 HasTag、AddTag、RemoveTag 的顺序按需调用，层级判断使用 IsTopLevel 与 FindTopLevel。

注意事项 ​

SpaceUnit 是不可直接创建的空间基类，应创建 WorldUnit、TriggerUnit 等公开具体子类后使用其继承能力。TranslateBy(delta) 沿对象自身坐标系平移，不是世界坐标系；例如对象旋转后，TranslateBy(Vector3.New(0, 0, 1)) 会沿对象本地 Z 轴移动。轴心读写只使用当前公开的 GetPivot、PivotTo 与 ApplyPivotDelta。

代码示例 ​

用具体空间单位调用 SpaceUnit 能力 ​

lua
-- @runtime client
local world = game:GetService("World")

-- SpaceUnit 是基类，脚本中创建具体子类（例如 TriggerUnit）后使用继承能力
local unit = world:CreateUnit("TriggerUnit", {
    Name = "TaggedTrigger",
    Position = Vector3.New(0, 5, 0),
    Scale = Vector3.New(3, 2, 1),
})

unit:AddTag("checkpoint")
if unit:HasTag("checkpoint") then
    unit:TranslateBy(Vector3.New(0, 0, 1))
end

local pivot = unit:GetPivot()
unit:PivotTo(pivot * CFrame.New(0, 0, 2))

属性 (2) ​

Name类型默认值说明
TagsArray<String>[]SpaceUnit 的标签属性，标题为“标签”，用于表示组件拥有的标签，类型为 Array，默认值为空数组。
EcaPathString""SpaceUnit 的触发器路径属性，标题为“触发器路径”，类型为 String，默认值为空字符串。

关联类型 ​

函数 (9) ​

HasTag ​

签名：HasTag(tag: String) -> Bool (是否拥有指定标签)

判断 SpaceUnit 是否拥有指定标签，返回 Bool 表示是否拥有该标签。

参数类型说明
tagString要检查的标签名称

返回值 Bool (是否拥有指定标签)

示例代码

检查具体空间单位标签

lua
-- @runtime client
local world = game:GetService("World")
local unit = world:CreateUnit("TriggerUnit", { Name = "Checkpoint" })

unit:AddTag("checkpoint")
if unit:HasTag("checkpoint") then
    print("已标记为检查点")
end

AddTag ​

签名：AddTag(tag: String) -> void

为 SpaceUnit 增加一个标签，标签以字符串形式传入；调用后该标签会被加入该对象的标签集合。

参数类型说明
tagString要添加的标签名称

返回值 void

示例代码

给具体空间单位添加标签

lua
-- @runtime client
local world = game:GetService("World")
local unit = world:CreateUnit("TriggerUnit", { Name = "Checkpoint" })

unit:AddTag("checkpoint")
print("标签已添加:", unit:HasTag("checkpoint"))

RemoveTag ​

签名：RemoveTag(tag: String) -> void

为 SpaceUnit 移除一个标签，标签以字符串形式传入，调用后会从该对象的标签集合中删除对应标签。

参数类型说明
tagString要移除的标签名称

返回值 void

示例代码

移除具体空间单位标签

lua
-- @runtime client
local world = game:GetService("World")
local unit = world:CreateUnit("TriggerUnit", { Name = "Checkpoint" })

unit:AddTag("checkpoint")
unit:RemoveTag("checkpoint")
print("是否仍有标签:", unit:HasTag("checkpoint"))

GetPivot ​

签名：GetPivot() -> CFrame (轴心点的坐标变换矩阵)

获取 SpaceUnit 轴心点的坐标变换矩阵，返回值为 CFrame。

返回值 CFrame (轴心点的坐标变换矩阵)

示例代码

读取具体空间单位轴心

lua
-- @runtime client
local world = game:GetService("World")
local unit = world:CreateUnit("TriggerUnit", { Position = Vector3.New(0, 5, 0) })

local pivot = unit:GetPivot()
print("当前轴心:", pivot)

PivotTo ​

签名：PivotTo(cframe: CFrame) -> void

将 SpaceUnit 的轴心变换设置为指定的 CFrame，参数 cframe 为目标轴心变换。

参数类型说明
cframeCFrame目标轴心点的坐标变换矩阵

返回值 void

示例代码

设置具体空间单位轴心

lua
-- @runtime client
local world = game:GetService("World")
local unit = world:CreateUnit("TriggerUnit", { Position = Vector3.New(0, 5, 0) })

unit:PivotTo(CFrame.New(0, 5, 2))
print("已移动到新轴心")

ApplyPivotDelta ​

签名：ApplyPivotDelta(delta: CFrame) -> void

对 SpaceUnit 的轴心应用一个由 CFrame 表示的增量变换，参数 delta 即为该增量变换矩阵。

参数类型说明
deltaCFrame要施加的增量 CFrame 变换

返回值 void

示例代码

对具体空间单位应用轴心增量

lua
-- @runtime client
local world = game:GetService("World")
local unit = world:CreateUnit("TriggerUnit", { Position = Vector3.New(0, 5, 0) })

unit:ApplyPivotDelta(CFrame.New(0, 0, 2))
print("已按当前轴心增量移动")

TranslateBy ​

签名：TranslateBy(delta: Vector3) -> void

按对象自身坐标系中的 delta 向量平移当前 SpaceUnit。

参数类型说明
deltaVector3在对象自身坐标系下的平移向量

返回值 void

示例代码

沿本地坐标移动具体空间单位

lua
-- @runtime client
local world = game:GetService("World")
local unit = world:CreateUnit("TriggerUnit", { Position = Vector3.New(0, 5, 0) })

unit:TranslateBy(Vector3.New(0, 0, 1))
print("已沿自身前方移动")

IsTopLevel ​

签名：IsTopLevel() -> Bool (是否为顶层对象)

判断 SpaceUnit 是否为顶层对象，返回 Bool 表示是否为顶层对象。

返回值 Bool (是否为顶层对象)

示例代码

判断具体空间单位是否顶层

lua
-- @runtime client
local world = game:GetService("World")
local unit = world:CreateUnit("TriggerUnit", { Name = "TopLevelTrigger" })

if unit:IsTopLevel() then
    print("该单位位于当前层级顶层")
end

FindTopLevel ​

签名：FindTopLevel() -> SpaceUnit (层级树中最顶层的 SpaceUnit，若自身已是顶层则返回自身)

查找层级树中最顶层的 SpaceUnit，若自身已经是顶层对象则返回自身。

返回值 SpaceUnit (层级树中最顶层的 SpaceUnit，若自身已是顶层则返回自身)

示例代码

查找具体空间单位顶层对象

lua
-- @runtime client
local world = game:GetService("World")
local unit = world:CreateUnit("TriggerUnit", { Name = "TopLevelTrigger" })

local top = unit:FindTopLevel()
if top ~= nil then
    print("顶层对象:", top.Name)
end