工坊手册

主题

SpaceUnit ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

继承成员 ​

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

SpaceUnit 是三维世界中所有可放置物体的空间基类，统一提供位置、旋转与缩放相关的变换能力。它通过轴心（Pivot）读取与写入控制物体在场景中的摆放，并支持标签标记、所属玩家记录以及空间层级顶端查询等辅助功能。实际使用时通常不直接操作该基类，而是通过其具体子类（如 WorldUnit、TriggerUnit）获得继承的空间能力。

适用场景 ​

在需要统一处理场景中各类空间物体的变换、标签或层级归属时，可以通过具体子类实例调用 SpaceUnit 提供的方法。例如在测试用例中，先创建 PhysicsUnit 或 TriggerUnit，再通过类型判断确认继承关系，并使用 PivotTo 等方法移动物体。

使用要点 ​

SpaceUnit 本身不能直接创建，需要先通过 World:CreateUnit 创建其具体子类（如 TriggerUnit、PhysicsUnit、WorldUnit 等），获得实例后即可调用继承自 SpaceUnit 的轴心与标签方法。常见的调用顺序是：使用 GetPivot 读取当前轴心、用 PivotTo 设置新位置或旋转、用 TranslateBy 沿自身坐标系平移；标签管理则通过 AddTag、HasTag、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))

属性 (3) ​

Name类型默认值说明
TagsArray<String>[]SpaceUnit 拥有的标签列表。
EcaPathString""SpaceUnit 的触发器路径。
OwnerInt-3SpaceUnit 的所属玩家 ID。

关联类型 ​

函数 (9) ​

HasTag ​

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

判断当前 SpaceUnit 是否拥有指定的标签。

参数类型说明
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

为当前空间单元添加一个字符串标签，用于标识或分类该空间。

参数类型说明
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 (轴心点的坐标变换矩阵)

获取单位当前轴心（Pivot）的 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

将单位的轴心设置到指定的 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

对单位应用一个轴心增量变换。传入一个 CFrame 作为相对增量，使单位在当前轴心的基础上移动或旋转。

参数类型说明
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 (是否为顶层对象)

示例代码

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

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 (层级树中最顶层的 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