工坊手册

主题

BasePart ​

BasePart 是具备物理碰撞与渲染表现的立体组件基类，向上承接 SpaceUnit 的层级能力，向下为 WorldUnit、RenderUnit、HumanUnit 等子类提供统一的变换、尺寸、外观与装配体信息。它通过 CFrame、P...

概览 ​

BasePart 是具备物理碰撞与渲染表现的立体组件基类，向上承接 SpaceUnit 的层级能力，向下为 WorldUnit、RenderUnit、HumanUnit 等子类提供统一的变换、尺寸、外观与装配体信息。它通过 CFrame、PivotOffset、Position、Rotation、Scale、Size 描述空间形态，通过 ModelAlpha、ModelVisible、CastShadow、ModelColor1 至 ModelColor4、SkinId 与自定义外观相关属性控制显示效果，并暴露装配体线速度、角速度、质量、质心等装配体状态，以及网络所有权归属和焊接连接关系的判定接口。

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

函数 ​

IsNetworkOwnerSide ​

签名：IsNetworkOwnerSide() -> Bool

判断当前端是否为该单位的物理拥有者端。

返回值 Bool

调用 IsNetworkOwnerSide

lua
-- @runtime client
local function demo(basePart)
    if basePart ~= nil then
        local result = basePart:IsNetworkOwnerSide()  -- 返回 Bool
        if result then
            print("调用结果为 true")
        else
            print("调用结果为 false")
        end
    end
end

GetNetworkOwner ​

签名：GetNetworkOwner() -> Player

获取当前 BasePart 实例的物理拥有者，返回表示该部件的物理拥有者的 Player 对象。

返回值 Player

服务端读取网络所有者

lua
-- @runtime server
local World = game:GetService('World')
local part = World:CreateUnit('WorldUnit', {
    Position = Vector3.New(0, 5, 0),
    PhysicsActive = true,
})

local owner = part:GetNetworkOwner()
if owner ~= nil then
    print('网络所有者:', owner:GetName())
else
    print('当前没有指定网络所有者')
end
part:Destroy()

SetNetworkOwner ​

签名：SetNetworkOwner(player: Player)

将 BasePart 的网络物理拥有者设置为指定的 Player。调用后该部件在网络同步中的物理模拟归属由被传入的玩家承担；传入的 player 参数必须是 Player 类型对象，函数没有返回值。可通过同一类型的 GetNetworkOwner 查询当前拥有者，通过 GetNetworkOwnershipAuto 与 SetNetworkOwnershipAuto 管理是否自动分配拥有权，也可通过 IsNetworkOwnerSide 判断本端是否为拥有方。

参数类型说明
playerPlayer玩家

服务端设置网络所有者

lua
-- @runtime server
local Players = game:GetService('Players')
local World = game:GetService('World')

local player = Players:GetPlayers()[1]
if player ~= nil then
    local part = World:CreateUnit('WorldUnit', {
        Position = Vector3.New(0, 5, 0),
        PhysicsActive = true,
    })
    part:SetNetworkOwner(player)
    print('已设置网络所有者:', player:GetName())
    part:Destroy()
end

GetNetworkOwnershipAuto ​

签名：GetNetworkOwnershipAuto() -> Bool

返回该物体的物理拥有者是否由引擎自动决定。返回 true 表示引擎会在玩家感知/接触时自动分配所有权；返回 false 表示已被手动固定（SetNetworkOwner 会隐式切为手动）

返回值 Bool

服务端查询网络所有权分配模式

lua
-- @runtime server
local World = game:GetService('World')
local part = World:CreateUnit('WorldUnit', { PhysicsActive = true })
if part == nil then return end
print('是否自动分配网络所有者:', part:GetNetworkOwnershipAuto())
part:Destroy()

SetNetworkOwnershipAuto ​

签名：SetNetworkOwnershipAuto()

把该部件的物理拥有者设置为自动分配模式，函数没有返回值。

服务端恢复网络所有权自动分配

lua
-- @runtime server
local World = game:GetService('World')
local part = World:CreateUnit('WorldUnit', { PhysicsActive = true })
if part == nil then return end
print('调用前是否自动分配:', part:GetNetworkOwnershipAuto())
part:SetNetworkOwnershipAuto()
print('恢复自动分配:', part:GetNetworkOwnershipAuto())
part:Destroy()

IsWeldConstraintRoot ​

签名：IsWeldConstraintRoot() -> Bool

判断该单位是否为焊接约束的根单位。

返回值 Bool

查询部件是否为焊接装配体根单位

lua
-- @runtime client
local World = game:GetService('World')
local part = World:CreateUnit('WorldUnit', {})
if part == nil then return end
print('是否为焊接根单位:', part:IsWeldConstraintRoot())
part:Destroy()

IsWeldConstraintChild ​

签名：IsWeldConstraintChild() -> Bool

判断该单位是否为焊接约束的子单位。

返回值 Bool

查询部件是否为焊接装配体子单位

lua
-- @runtime client
local World = game:GetService('World')
local part = World:CreateUnit('WorldUnit', {})
if part == nil then return end
print('是否为焊接子单位:', part:IsWeldConstraintChild())
part:Destroy()

GetConnectedUnits ​

签名：GetConnectedUnits() -> Map

获取通过约束与该部件连接的所有单位，返回一个键为整型索引、值为 WorldUnit 的映射表。

返回值 Map

调用 GetConnectedUnits

lua
-- @runtime client
local function demo(basePart)
    if basePart ~= nil then
        local result = basePart:GetConnectedUnits()  -- 返回 Map
        if result ~= nil then
            for key, item in pairs(result) do
                print(key, item)
            end
        end
    end
end

SyncRenderToPhysics ​

签名：SyncRenderToPhysics()

将本地渲染位置强制同步到最新的物理模拟位置，消除渲染延迟

属性 ​

名称类型默认值说明
CFrameCFrame[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0]BasePart 的空间变换属性，类型为 CFrame，同时表达该部件的位置与旋转信息。
PivotOffsetCFrame[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0]BasePart 的轴心偏移属性，类型为 CFrame，用于描述部件轴心相对于默认轴心的偏移变换。
PositionVector3[0.0, 0.0, 0.0]单位在世界空间中的位置坐标。该属性为 CFrame 的语法糖：读取等价于 CFrame.Position，写入会保持当前旋转不变、仅重建 CFrame 的位置分量
RotationQuaternion[0.0, 0.0, 0.0, 1.0]单位在世界空间中的旋转，以四元数表示。该属性为 CFrame 的语法糖：读取等价于 CFrame.Rotation，写入会保持当前位置不变、仅重建 CFrame 的旋转分量
ScaleVector3[1.0, 1.0, 1.0]BasePart 的缩放属性，类型为 Vector3，用于描述部件在各轴向上的缩放。
SizeVector3-渲染层尺寸，由 Scale 与模型资源的基础尺寸决定；无模型时为 nil。修改 Scale 或模型可改变渲染尺寸。
ModelAlphaFloat1控制模型的整体透明度，0 为完全透明，1 为完全不透明
ModelVisibleBooltrue控制模型是否可见，隐藏后仍参与物理碰撞
CastShadowBooltrue该单位是否投射阴影，类型为 Bool，默认值为 true。
ModelColor1ColorColor.New(255, 255, 255, 255)染色区域 1 的颜色；实际效果依赖模型资源是否包含对应 color mask，部分资源可能忽略 Color 赋值或表现为白色。启用自定义外观后该属性不生效。
ModelColor2ColorColor.New(255, 255, 255, 255)染色区域 2 的颜色；实际效果依赖模型资源是否包含对应 color mask。启用自定义外观后该属性不生效。
ModelColor3ColorColor.New(255, 255, 255, 255)染色区域 3 的颜色；实际效果依赖模型资源是否包含对应 color mask。启用自定义外观后该属性不生效。
ModelColor4ColorColor.New(255, 255, 255, 255)染色区域 4 的颜色；实际效果依赖模型资源是否包含对应 color mask。启用自定义外观后该属性不生效。
SkinIdString""模型使用的皮肤资源ID，用于切换模型外观；启用自定义外观后该属性不生效
UseCustomAppearanceBoolfalse单位是否使用自定义外观，类型为 Bool，默认值为 false。
CustomAppearanceIdString""自定义外观的资源ID，启用自定义外观后生效
OcclusionTypeInt3该单位遮挡玩家时采用的处理规则；Meta 将类型声明为 Int，默认值为 3（不处理）。
AssemblyRootPriorityInt0在装配体中作为根节点的优先级，数值越大越优先成为装配体根；取值范围 [-127, 127]。
AssemblyLinearVelocityVector3[0, 0, 0]所属装配体的整体线速度（只读）
AssemblyAngularVelocityVector3[0, 0, 0]所属装配体的整体角速度（只读）
AssemblyMassFloat0所属装配体的总质量（只读）
AssemblyCenterOfMassVector3[0, 0, 0]所属装配体的质心世界坐标（只读）
PersistentBoolfalse仅在World开启了AOI功能时此字段生效
IsStaticOptimizationBoolfalse启用后标记为静态物体，引擎可进行批量渲染优化，适用于不会移动的物体