工坊手册

主题

BasePart ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

继承成员 ​

2 个来源 / 6 属性 / 34 函数 / 6 事件

BasePart 是场景中所有具备碰撞与渲染表现的 3D 部件共享的基类，WorldUnit、PhysicsUnit、RenderUnit 等都从它继承这套公共能力。它同时覆盖三个层面：用 CFrame、Position、Rotation、Size、PivotOffset 描述空间形态，用 ModelAlpha、ModelVisible、ModelColor1 至 ModelColor4、SkinId 控制外观，用 AssemblyLinearVelocity、AssemblyAngularVelocity、AssemblyMass 观察装配体力学状态，并附带网络所有权与焊接关系的查询接口。

适用场景 ​

当需要统一地摆放、隐藏、染色场景部件，或读取某个部件所在装配体的速度与质量时使用。典型做法是拿到 PhysicsUnit、WorldUnit 之类的子类实例后，直接按 BasePart 的属性接口调整位置与外观，并用 IsNetworkOwnerSide 判断当前端是否负责该部件的模拟。

使用要点 ​

通过子类实例（如 WorldUnit）访问 BasePart 的属性和方法。ModelColor1~4 的公开类型是 Color，规范写法为 Color.New(r, g, b, a)，但实际染色还依赖资源 color mask；赋值后变白或无变化时不要反复改 RGBA，应先更换支持染色的资源。少数兼容资源只接受整数色值属于实现差异，不是稳定公开契约。服务端可用 GetNetworkOwner/SetNetworkOwner 管理物理网络所有权。父子层级本身已满足稳定跟随时不要叠加 WeldConstraint；确需显式焊接时，先解除 Parent，再建立约束并在目标运行包验证。

注意事项 ​

BasePart 不可直接创建，必须通过子类实例间接使用。网络所有者的查询与设置通常在服务端处理；客户端可用 IsNetworkOwnerSide 判断当前端是否拥有该部件的网络模拟权。可读取 AssemblyLinearVelocity 等属性观察装配体的物理状态；施加物理作用前需确保对象处于物理模拟激活状态。ModelColor1~ModelColor4 的类型在 Meta 中为 Color，但部分模型资源的染色区域受资源自身 color mask 支持情况影响；若赋值后统一变白或无变化，优先确认模型是否包含对应染色区域。当前版本中个别场景使用整数色值（如 tonumber("ff0000", 16)）更接近编辑器染色表现，脚本示例应标注资源依赖，避免承诺所有模型都可通过 Color 直接染色。当前运行包还会为 BasePart 父子层级建立隐式刚性连接，该连接可能优先于显式 WeldConstraint；已处于父子关系的对象再创建焊接，或事后解除 Parent，不能保证原焊接自动接管。需要显式约束时应先解除父子层级，再创建并验证 WeldConstraint。

代码示例 ​

创建具体物理部件并读取物理状态 ​

lua
-- @runtime client
local World = game:GetService('World')
local part = World:CreateUnit('WorldUnit', {
    Position = Vector3.New(0, 5, 0),
    PhysicsActive = true,
})
print('当前线速度:', part.AssemblyLinearVelocity)
part:Destroy()

属性 (24) ​

Name类型默认值说明
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]BasePart 的位置属性，类型为 Vector3，表示部件在空间中的坐标。
RotationQuaternion[0.0, 0.0, 0.0, 1.0]BasePart 的旋转属性，类型为 Quaternion，用于描述部件的朝向。
ScaleVector3[1.0, 1.0, 1.0]BasePart 的缩放属性，类型为 Vector3，用于描述部件在各轴向上的缩放。
SizeVector3-BasePart 的尺寸属性，类型为 Vector3，用于描述部件在各轴向上的大小。
ModelAlphaFloat1单位模型的整体透明度，类型为 Float，默认值为 1。
ModelVisibleBooltrue单位模型是否可见，类型为 Bool，默认值为 true。
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""BasePart 的皮肤标识，类型为字符串，可读可写，用于指定部件使用的皮肤。
UseCustomAppearanceBoolfalse单位是否使用自定义外观，类型为 Bool，默认值为 false。
CustomAppearanceIdString""单位使用的自定义外观标识，类型为 String，默认值为空字符串。
OcclusionTypeInt3 (不处理)该单位遮挡玩家时采用的处理规则；Meta 将类型声明为 Int，默认值为 3（不处理）。
AssemblyRootPriorityInt0装配根的优先级，类型为 Int，默认值为 0。
AssemblyLinearVelocityVector3[0, 0, 0]BasePart 的装配体线速度属性，类型为 Vector3，描述该部件所属装配体的线速度。
AssemblyAngularVelocityVector3[0, 0, 0]BasePart 的装配体角速度属性，类型为 Vector3，描述该部件所属装配体的角速度。
AssemblyMassFloat0该单位所属装配体的质量，类型为 Float，默认值为 0。
AssemblyCenterOfMassVector3[0, 0, 0]BasePart 的装配体质心属性，类型为 Vector3，描述该部件所属装配体的质心位置。
PersistentBoolfalseStreaming 相关的 Bool 字段，默认 false；当前 Streaming 功能暂未启用，修改该字段没有任何效果。不能据此保证对象常驻、改变 AOI 或跨范围可见性。
IsStaticOptimizationBoolfalse静态优化开关，类型为 Bool，默认值为 false。

关联类型 ​

函数 (9) ​

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

获取当前部件的物理拥有者，返回对应的 Player 对象。该函数不接收任何参数，调用后给出该部件物理模拟当前归属的玩家。

⚙ 在服务端读取当前网络所有者；没有明确所有者时可能返回 nil。

返回值 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) -> void

设置部件的物理拥有者，把该部件的物理模拟归属到指定的 Player。调用时需要传入一个 Player 类型的参数。

⚙ 在服务端把物理部件的网络所有权交给指定 Player。

参数类型说明
playerPlayer要转移权限的玩家对象

返回值 void

示例代码

服务端设置网络所有者

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

查询该部件的物理拥有者当前是否处于自动分配模式，返回一个布尔值。

返回值 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() -> void

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

返回值 void

示例代码

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

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() -> void

将本地渲染强制同步到最新位置。

⚙ 最新 Meta 已公开 SyncRenderToPhysics，且未声明额外前置条件或单独 realm；当前运行包在客户端调用会触发运行时内部错误。在运行时实现与 Meta 对齐前请勿调用。

返回值 void

示例代码

当前版本的接口可用性说明

lua
-- @runtime client
local World = game:GetService('World')
local part = World:FindFirstChild('PhysicsPart', true)
if part ~= nil then
    print('已找到物理部件；当前运行包请勿调用 SyncRenderToPhysics')
end