RenderUnit

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • SpaceUnit（3 属性 / 9 函数）
    • BasePart（23 属性 / 9 函数）
      • [RenderUnit]（15 属性）

继承成员

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

• 来自 BasePart（23 属性 / 9 函数）
  • 属性：CFrame、PivotOffset、Position、Rotation、Scale、Size、ModelAlpha、ModelVisible、CastShadow、ModelColor1、ModelColor2、ModelColor3、ModelColor4、SkinId、UseCustomAppearance、CustomAppearanceId、OcclusionType、AssemblyRootPriority、AssemblyLinearVelocity、AssemblyAngularVelocity、AssemblyMass、AssemblyCenterOfMass、IsStaticOptimization
  • 函数：IsNetworkOwnerSide、GetNetworkOwner、SetNetworkOwner、IsWeldConstraintRoot、IsWeldConstraintChild、GetWeldConstraintRootId、GetWeldConstraintId、GetConnectedUnits、SyncRenderToPhysics
• 来自 SpaceUnit（3 属性 / 9 函数）
  • 属性：Tags、EcaPath、Owner
  • 函数：HasTag、AddTag、RemoveTag、GetPivot、PivotTo、ApplyPivotDelta、TranslateBy、IsTopLevel、FindTopLevel
• 来自 Unit（4 属性 / 25 函数 / 6 事件）
  • 属性：AssetId、Name、Desc、Parent
  • 函数：ClearAllChildren、GetChildren、GetDescendants、IsAncestorOf、IsDescendantOf、FindFirstAncestor、FindFirstAncestorWhichIsA、FindFirstAncestorOfClass、FindFirstChild、FindFirstChildWhichIsA、FindFirstChildOfClass、HasChildren、GetChildCount、GetChildAtIndex、SetAttribute、GetAttribute、GetAllProps、Clone、IsA、Destroy、GetPropertyChangedSignal、GetAttributeChangedSignal、FindFromPath、GetFullPath、GetDebugId
  • 事件：ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying

RenderUnit 是一种可在三维场景中创建的渲染组件，负责承载并展示模型资源。它提供了模型资源绑定、透明度与可见性控制、阴影投射、多区域染色、皮肤以及自定义外观等表现能力，适合用来搭建场景中的装饰物或需要独立控制渲染效果的物件。

适用场景

在搭建地图场景时，常通过创建 RenderUnit 来摆放静态模型，例如建筑、植被、道具等装饰元素，并利用其属性动态控制模型的显隐、透明度和染色效果。

使用要点

通过 game:CreateUnit("RenderUnit", config) 或 World:CreateUnit("RenderUnit", config) 创建实例，在配置中指定 RenderMeshId 等初始属性。创建后可直接读写 ModelVisible、ModelAlpha、ModelColor 系列属性来调整表现，也可以设置 CastShadow、SkinId、UseCustomAppearance 等属性丰富渲染细节。

注意事项

创建后必须设置 RenderMeshId 指定模型资源才能在场景中显示。TweenService 对 RenderUnit 属性的支持有限，建议直接修改属性而非 Tween 驱动。Color 类型必须用 0-255 RGBA 四参数构造（如 Color.New(255, 0, 0, 255)），不能用 0-1 归一化值。

代码示例

创建并显示渲染单位

-- @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)

属性 (15)

Name	类型	默认值	说明
RenderMeshId	String	official://mesh/59268	RenderUnit 使用的模型资源 ID。
ModelAlpha	Float	1	控制模型的整体透明度，0 为完全透明，1 为完全不透明
LocalTransparencyModifier	Float	1	本地透明度乘数，影响 RenderUnit 的最终透明度。
ModelVisible	Bool	true	控制 RenderUnit 模型的可见性。
CastShadow	Bool	true	控制 RenderUnit 是否投射阴影。
TransparentRenderBias	Int	0	控制 RenderUnit 的半透明渲染偏置值，用于调整渲染顺序，解决半透明物体之间的渲染遮挡问题。
ModelBindParent	Bool	false	是否让 RenderUnit 的模型跟随其父节点的变换。
ModelColor1	Color	Color.New(255, 255, 255, 255)	模型染色区域1的颜色，使用 Color 类型表示。
ModelColor2	Color	Color.New(255, 255, 255, 255)	模型染色区域2的颜色，使用 Color 类型表示。
ModelColor3	Color	Color.New(255, 255, 255, 255)	模型染色区域3的颜色，使用 Color 类型表示。
ModelColor4	Color	Color.New(255, 255, 255, 255)	模型染色区域4的颜色，使用 Color 类型表示。
SkinId	String	""	RenderUnit 使用的皮肤资源 ID。
UseCustomAppearance	Bool	false	是否启用自定义外观。
CustomAppearanceId	String	""	当 UseCustomAppearance 为 true 时，指定自定义外观资源的 ID。
OcclusionType	Int	3 (不处理)	RenderUnit 的 OcclusionType 属性用于设置该渲染单元在遮挡玩家时采用的规则。

关联类型

• BasePart
• Color