工坊手册

主题

RenderUnit ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • SpaceUnit（2 属性 / 9 函数）
      • BasePart（24 属性 / 9 函数）
        • [RenderUnit]（17 属性 / 1 函数）

继承成员 ​

3 个来源 / 19 属性 / 43 函数 / 6 事件

RenderUnit 是可创建的 3D 渲染组件，用于在场景中显示模型，并控制整体透明度、可见性、阴影与四个染色区域。

适用场景 ​

用于创建装饰物件或独立外观模型；运行时通过 RenderMeshId、SkinId 与 ModelColor1~ModelColor4 配置单皮肤外观。

使用要点 ​

通过 World:CreateUnit("RenderUnit", config) 创建实例，在 config 中设置有效的 RenderMeshId；需要切换模型并恢复默认皮肤时调用 SetRenderMeshWithDefaultSkin。

注意事项 ​

创建后必须设置 RenderMeshId 指定模型资源才能在场景中显示。UseSkinList 与 SkinSlots 是公开的运行时属性；修改槽位列表后应整体赋回 SkinSlots。TweenService 对 RenderUnit 属性的支持有限，建议直接修改属性而非 Tween 驱动。Color 类型必须用 0-255 RGBA 四参数构造（如 Color.New(255, 0, 0, 255)），不能用 0-1 归一化值。

代码示例 ​

创建并显示渲染单位 ​

lua
-- @runtime client
local World = game:GetService("World")
local renderUnit = World:CreateUnit("RenderUnit", {
    Name = "SceneDecoration",
    RenderMeshId = "official://mesh/59268",
    Position = Vector3.New(0, 2, 0),
    ModelVisible = true,
    ModelAlpha = 1.0,
    ModelColor1 = Color.New(255, 255, 255, 255),
})
print("已创建渲染单位:", renderUnit.Name)

属性 (17) ​

Name类型默认值说明
RenderMeshIdStringofficial://mesh/59268String 类型属性，标题为“模型资源ID”，用于标识该渲染单元所使用的模型资源。
ModelAlphaFloat1ModelAlpha 表示 RenderUnit 模型的透明度，类型为 Float。该属性在 Meta 中公开且标记为可编辑，声明的默认值为 1。
LocalTransparencyModifierFloat1LocalTransparencyModifier 表示 RenderUnit 的本地透明度乘数，类型为 Float。该属性在 Meta 中标记为不可编辑（editable 为 false），声明的默认值为 1。
ModelVisibleBooltrueModelVisible 表示 RenderUnit 的模型是否可见，类型为 Bool。该属性可编辑，Meta 声明的默认值为 true。
CastShadowBooltrueBool 类型属性，标题为“启用阴影投射”，用于表示该渲染单元是否启用阴影投射这一开关状态。
TransparentRenderBiasInt0TransparentRenderBias 表示 RenderUnit 半透明渲染的偏置值，类型为 Int。该属性可编辑，Meta 声明的默认值为 0。
ModelBindParentBoolfalseModelBindParent 表示 RenderUnit 的模型是否随父节点绑定，类型为 Bool。该属性可编辑，Meta 声明的默认值为 false。
ModelColor1ColorColor.New(255, 255, 255, 255)Color 类型属性，标题为“染色区域1”，用于描述该渲染单元模型上第一处染色区域的颜色。
ModelColor2ColorColor.New(255, 255, 255, 255)Color 类型属性，标题为“染色区域2”，用于描述该渲染单元模型上第二处染色区域的颜色。
ModelColor3ColorColor.New(255, 255, 255, 255)Color 类型属性，标题为“染色区域3”，用于描述该渲染单元模型上第三处染色区域的颜色。
ModelColor4ColorColor.New(255, 255, 255, 255)Color 类型属性，标题为“染色区域4”，用于描述该渲染单元模型上第四处染色区域的颜色。
SkinIdString""String 类型属性，标题为“皮肤”，用于指定该渲染单元所使用的皮肤资源。
UseSkinListBoolfalse多槽位皮肤开关；启用后按各子网格的 SkinSlots 配置皮肤与染色。
SkinSlotsArray<SkinSlot>[]各子网格的皮肤与染色配置列表；元素包含 SkinId 和 ModelColor1~4。
UseCustomAppearanceBoolfalseUseCustomAppearance 表示 RenderUnit 是否使用自定义外观，类型为 Bool。该属性可编辑，Meta 声明的默认值为 false。
CustomAppearanceIdString""CustomAppearanceId 指定 RenderUnit 所使用的自定义外观标识，类型为 String。该属性可编辑，Meta 声明的默认值为空字符串。
OcclusionTypeInt3 (不处理)该单位遮挡玩家时采用的处理规则；Meta 将类型声明为 Int，默认值为 3（不处理）。

关联类型 ​

函数 (1) ​

SetRenderMeshWithDefaultSkin ​

签名：SetRenderMeshWithDefaultSkin(renderMeshId: String) -> void

RenderUnit 的成员函数，用于把当前渲染单元切换为指定的模型资源，并同时为该模型应用默认皮肤。函数接收一个必填的 String 参数 renderMeshId，Meta 契约中未声明返回值。

参数类型说明
renderMeshIdString模型资源ID

返回值 void

示例代码

切换为项目配置的模型并应用默认皮肤

lua
-- @runtime client
local world = game:GetService("World")
local renderUnit = world:CreateUnit("RenderUnit", {})
if renderUnit == nil then return end
-- renderMeshId 取项目为该单位配置的网格资源，不要凭空编造资源 ID
local renderMeshId = renderUnit.RenderMeshId
renderUnit:SetRenderMeshWithDefaultSkin(renderMeshId)
renderUnit:Destroy()