工坊手册

主题

SpaceUnit ​

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

概览 ​

继承 Unit，具有位置、旋转、缩放的空间单位。通过 World 服务返回的 SpaceUnit 对象访问；提供空间变换和内置属性的读取、设置接口。设置位置、旋转、缩放、内置属性及完整变换支持撤销、重做。

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

代码示例 ​

设置并读回空间变换

lua
-- @runtime editor
local world = editor:GetService("World")
local unit = world:CreateUnit("WorldUnit", {Name = "DocumentationSpaceUnitExample"})
assert(unit ~= nil, "未能创建示例空间单位")
local ok, err = pcall(function()
    unit:SetPosition(Vector3.New(0, 5, 0))
    local position = unit:GetPosition()
    assert(type(position) == "table" and #position == 3, "位置应为三个 Float 的数组")
    assert(math.abs(position[1]) < 0.0001 and math.abs(position[2] - 5) < 0.0001 and math.abs(position[3]) < 0.0001, "位置读回与设置值不一致")
    print("Position", position[1], position[2], position[3])
    unit:SetScale(Vector3.New(1.5, 1.5, 1.5))
    local scale = unit:GetScale()
    assert(type(scale) == "table" and #scale == 3, "缩放应为三个 Float 的数组")
    assert(math.abs(scale[1] - 1.5) < 0.0001 and math.abs(scale[2] - 1.5) < 0.0001 and math.abs(scale[3] - 1.5) < 0.0001, "缩放读回与设置值不一致")
    print("Scale", scale[1], scale[2], scale[3])
end)
unit:Destroy()
if not ok then error(err) end

函数 ​

GetPosition ​

签名：GetPosition() -> Array

获取该单位当前的世界坐标，调用时不需要传入参数。

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

调用 GetPosition

lua
-- @runtime editor
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 spaceUnit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

SetPosition ​

签名：SetPosition(position: Vector3)

设置世界坐标（支持撤销/重做）。

参数类型说明
positionVector3世界坐标

调用 SetPosition

lua
-- @runtime editor
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 spaceUnit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

GetRotation ​

签名：GetRotation() -> Quaternion

获取该单位当前的旋转，调用时不需要传入参数。

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

调用 GetRotation

lua
-- @runtime editor
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 spaceUnit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

SetRotation ​

签名：SetRotation(rotation: Quaternion)

设置旋转（支持撤销/重做）。

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

调用 SetRotation

lua
-- @runtime editor
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 spaceUnit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

GetScale ​

签名：GetScale() -> Array

获取该单位当前的缩放，调用时不需要传入参数。

返回值 Array — 单位的缩放

调用 GetScale

lua
-- @runtime editor
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 spaceUnit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

SetScale ​

签名：SetScale(scale: Vector3)

设置缩放（支持撤销/重做）。

参数类型说明
scaleVector3缩放

调用 SetScale

lua
-- @runtime editor
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 spaceUnit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

GetProperty ​

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

按名称读取该单位的任意内置属性，调用时传入属性名字符串。

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

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

调用 GetProperty

lua
-- @runtime editor
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 spaceUnit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end

SetProperty ​

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

设置任意内置属性（支持撤销/重做）。

注意： 本例使用 editor 本地 World 服务创建并只操作自有 WorldUnit；按公开内置属性 Name 写入字符串并读回。成功或失败后均清理创建的示例单位，不操作地图已有单位。静态阅读不证明目标编辑器已经执行成功。

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

修改自有单位名称并读回

lua
-- @runtime editor
local world = editor:GetService("World")
local unit = world:CreateUnit("WorldUnit", { Name = "DocumentationPropertyExample" })
assert(unit ~= nil, "未能创建示例单位")
local ok, err = pcall(function()
    local newName = "DocumentationPropertyUpdated"
    unit:SetProperty("Name", newName)
    local actualName = unit:GetProperty("Name")
    assert(actualName == newName, "名称读回与写入值不一致")
    print("当前名称:", actualName)
end)
unit:Destroy()
if not ok then error(err) end

SetTRS ​

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

设置完整变换（位置、旋转、缩放一次提交，支持撤销/重做）。

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

调用 SetTRS

lua
-- @runtime editor
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 spaceUnit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if spaceUnit ~= nil then
    demo(spaceUnit)
    spaceUnit:Destroy()
end