工坊手册

主题

SpaceUnit ​

继承 Unit，具有位置/旋转/缩放的空间单位。通过 World 服务返回的 SpaceUnit 对象访问。

概览 ​

SpaceUnit 是所有可摆放空间单位的抽象基类，统一承载场景单位在三维空间中的位置、旋转与缩放等变换信息的读写能力。除支持逐项读取与设置上述空间状态外，还提供按属性名进行通用读写的 GetProperty 与 SetProperty，以及一次性设置位置、旋转、缩放三项的 SetTRS，便于批量或通用化地操作单位空间信息。

继承自 Unit；不可实例化，由接口返回

函数 ​

GetPosition ​

签名：GetPosition() -> Array

获取空间单位在世界空间中的位置坐标。该函数不需要参数，返回值以数组形式给出单位的世界坐标。

返回值 Array — 单位的世界坐标

调用 GetPosition

lua
-- @runtime client
local function demo(spaceUnit)
    if spaceUnit ~= nil then
        local result = spaceUnit:GetPosition()  -- 返回 Array
        if result ~= nil then
            for index, item in ipairs(result) do
                print(index, item)
            end
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local spaceUnit = createdUnits and createdUnits[1]
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

SetPosition ​

签名：SetPosition(position: Vector3)

设置空间单位在世界空间中的位置坐标。需要传入一个 Vector3 类型的位置参数，执行结果支持撤销与重做。

参数类型说明
positionVector3世界坐标

调用 SetPosition

lua
-- @runtime client
local function demo(spaceUnit)
    if spaceUnit ~= nil then
        local position = Vector3.New(0, 0, 0)  -- Vector3
        spaceUnit:SetPosition(position)
        local currentValue = spaceUnit:GetPosition()
        if currentValue ~= nil then
            print("当前值: " .. tostring(currentValue))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local spaceUnit = createdUnits and createdUnits[1]
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

GetRotation ​

签名：GetRotation() -> Quaternion

获取空间单位当前的旋转状态。该函数不需要参数，返回值为表示单位旋转的四元数。

返回值 Quaternion — 单位的旋转四元数

调用 GetRotation

lua
-- @runtime client
local function demo(spaceUnit)
    if spaceUnit ~= nil then
        local result = spaceUnit:GetRotation()  -- 返回 Quaternion
        if result ~= nil then
            print(result)
            local resultText = tostring(result)
            print(resultText)
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local spaceUnit = createdUnits and createdUnits[1]
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

SetRotation ​

签名：SetRotation(rotation: Quaternion)

设置空间单位当前的旋转状态。需要传入一个 Quaternion 类型的旋转参数，执行结果支持撤销与重做。

参数类型说明
rotationQuaternion旋转四元数

调用 SetRotation

lua
-- @runtime client
local function demo(spaceUnit)
    if spaceUnit ~= nil then
        local rotation = Quaternion.New(0, 0, 0, 1)  -- Quaternion
        spaceUnit:SetRotation(rotation)
        local currentValue = spaceUnit:GetRotation()
        if currentValue ~= nil then
            print("当前值: " .. tostring(currentValue))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local spaceUnit = createdUnits and createdUnits[1]
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

GetScale ​

签名：GetScale() -> Array

获取空间单位当前的缩放值。该函数不需要参数，返回值以数组形式给出单位的缩放数据。

返回值 Array — 单位的缩放

调用 GetScale

lua
-- @runtime client
local function demo(spaceUnit)
    if spaceUnit ~= nil then
        local result = spaceUnit:GetScale()  -- 返回 Array
        if result ~= nil then
            for index, item in ipairs(result) do
                print(index, item)
            end
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local spaceUnit = createdUnits and createdUnits[1]
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

SetScale ​

签名：SetScale(scale: Vector3)

设置空间单位当前的缩放值。需要传入一个 Vector3 类型的缩放参数，执行结果支持撤销与重做。

参数类型说明
scaleVector3缩放

调用 SetScale

lua
-- @runtime client
local function demo(spaceUnit)
    if spaceUnit ~= nil then
        local scale = Vector3.New(0, 0, 0)  -- Vector3
        spaceUnit:SetScale(scale)
        local currentValue = spaceUnit:GetScale()
        if currentValue ~= nil then
            print("当前值: " .. tostring(currentValue))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local spaceUnit = createdUnits and createdUnits[1]
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

GetProperty ​

签名：GetProperty(propName: String) -> Any

按属性名称读取空间单位的任意内置属性。需要传入一个字符串形式的属性名，属性存在时返回对应属性值，属性不存在时返回 nil。

参数类型说明
propNameString属性名（如 "Name" / "BodyType" / "SkinId" / "physic_enable"）

返回值 Any — 属性值；属性不存在时返回 nil

调用 GetProperty

lua
-- @runtime client
local function demo(spaceUnit)
    if spaceUnit ~= nil then
        local propName = "default"  -- String
        local result = spaceUnit:GetProperty(propName)  -- 返回 Any
        if result ~= nil then
            print("调用成功，结果: " .. tostring(result))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local spaceUnit = createdUnits and createdUnits[1]
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

SetProperty ​

签名：SetProperty(propName: String, value: Any)

通过属性名设置空间单元的任意内置属性。调用时需要传入属性名及目标值，执行结果支持撤销与重做。

参数类型说明
propNameString属性名（如 "Name" / "BodyType"）
valueAny属性值（枚举属性传对应数字，如 BodyType：0=Static / 1=Kinematic / 2=Dynamic）

调用 SetProperty

lua
-- @runtime client
local function demo(spaceUnit)
    if spaceUnit ~= nil then
        local propName = "default"  -- String
        local value = nil  -- Any
        spaceUnit:SetProperty(propName, value)
        local currentValue = spaceUnit:GetProperty(propName)
        if currentValue ~= nil then
            print("当前值: " .. tostring(currentValue))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local spaceUnit = createdUnits and createdUnits[1]
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

SetTRS ​

签名：SetTRS(position: Vector3, rotation: Quaternion, scale: Vector3)

一次性设置空间单位的位置、旋转和缩放完整变换。需要同时传入 Vector3 位置、Quaternion 旋转和 Vector3 缩放三个参数，整体提交结果支持撤销与重做。

参数类型说明
positionVector3世界坐标
rotationQuaternion旋转四元数
scaleVector3缩放

调用 SetTRS

lua
-- @runtime client
local function demo(spaceUnit)
    if spaceUnit ~= nil then
        local position = Vector3.New(0, 0, 0)  -- Vector3
        local rotation = Quaternion.New(0, 0, 0, 1)  -- Quaternion
        local scale = Vector3.New(0, 0, 0)  -- Vector3
        spaceUnit:SetTRS(position, rotation, scale)
        print("已调用 SetTRS", position)
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local spaceUnit = createdUnits and createdUnits[1]
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end