RenderTriggerUnit

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • SpaceUnit（3 属性 / 9 函数）
    • BasePart（23 属性 / 9 函数）
      • TriggerUnit（8 属性 / 7 函数 / 4 事件）
        • [RenderTriggerUnit]（16 属性）

继承成员

4 个来源 / 38 属性 / 50 函数 / 10 事件

• 来自 TriggerUnit（8 属性 / 7 函数 / 4 事件）
  • 属性：CFrame、Scale、PhysicsMeshId、DisplayModelId、PhysicsActive、ModelBindParent、CollisionGroup、CanTouch
  • 函数：AddCollisionWithGroup、RemoveCollisionWithGroup、GetCollisionWithGroups、AddNoCollisionPairWithUnit、RemoveNoCollisionPairWithUnit、RemoveAllNoCollisionPairWithUnit、GetNoCollisionPairUnitList
  • 事件：OnTriggerEnter、OnTriggerExit、OnLocalTriggerEnter、OnLocalTriggerExit
• 来自 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

RenderTriggerUnit 是兼具运行时模型渲染与触发检测能力的场景单位；RenderMeshId 指定实际渲染网格，DisplayModelId 只用于编辑器预览。

适用场景

在需要制作可交互区域（如触发器、危险地带、事件区域）时，通过创建触发区域单位并配置其外观与物理属性，再配合其他逻辑实现区域检测与反馈。

使用要点

通过 World:CreateUnit 创建实例，在 config 中把 RenderMeshId 设置为项目提供的有效网格资源 URI，并监听 OnTriggerEnter/OnTriggerExit 处理进入和离开。

注意事项

运行时外观使用 RenderMeshId，DisplayModelId 是 editOnly 的编辑器预览字段，不影响运行时渲染。当前公开 Surface 只提供 ModelColor1~ModelColor4 等外观属性，不应调用未发布的染色接口。Color 使用 0-255 RGBA 四参数构造。

代码示例

创建可见触发区域并监听进入事件

-- @runtime client
local function createRenderTrigger(meshId)
    local world = game:GetService("World")
    local renderTrigger = world:CreateUnit("RenderTriggerUnit", {
        RenderMeshId = meshId,
        ModelColor1 = Color.New(255, 0, 0, 255),
        ModelVisible = true,
    })
    renderTrigger.OnTriggerEnter:Once(function(otherUnit)
        print("进入触发区域:", otherUnit.Name)
    end)
    return renderTrigger
end

属性 (16)

Name	类型	默认值	说明
RenderMeshId	String	official://mesh/59268	指定该单元使用的模型资源ID。
ModelAlpha	Float	1	控制模型的整体透明度，0 为完全透明，1 为完全不透明
LocalTransparencyModifier	Float	1	该单元的本地透明度乘数，用于在本地客户端进一步调整模型透明度。
ModelVisible	Bool	true	控制模型是否可见，隐藏后仍参与物理碰撞
CastShadow	Bool	true	控制该单元是否投射阴影。
ModelBindParent	Bool	false	启用后，当父节点为 WorldUnit、RenderUnit、TriggerUnit、PhysicsUnit 等支持父子带动的场景单位时，当前模型渲染表现将跟随父节点的变换自动同步。运行时可通过脚本设置 .ModelBindParent = true/false 动态切换该行为。
PhysicsMeshId	String	official://mesh/59268	物理网格资源ID。缺省时，若初始创建时传入了 RenderMeshId，则默认使用该 RenderMeshId 作为物理资源；后续修改 .RenderMeshId 不会影响 PhysicsMeshId
DisplayModelId	String	""	用于在编辑器中预览的模型资源 ID，不影响运行时实际渲染的模型。
ModelColor1	Color	Color.New(255, 255, 255, 255)	模型的染色区域1颜色，用于控制模型指定区域的颜色表现。
ModelColor2	Color	Color.New(255, 255, 255, 255)	模型的染色区域2颜色，用于控制模型指定区域的颜色表现。
ModelColor3	Color	Color.New(255, 255, 255, 255)	模型的染色区域3颜色，用于控制模型指定区域的颜色表现。
ModelColor4	Color	Color.New(255, 255, 255, 255)	模型的染色区域4颜色，用于控制模型指定区域的颜色表现。
SkinId	String	""	应用于 RenderTriggerUnit 的皮肤资源 ID。
UseCustomAppearance	Bool	false	是否启用自定义外观。
CustomAppearanceId	String	""	自定义外观的资源 ID，用于覆盖默认外观。
OcclusionType	Int	3 (不处理)	OcclusionType 属性用于设置该渲染触发单位在遮挡玩家视角时所采用的规则，影响其被相机遮挡时的表现方式。该属性为整数类型，具体取值对应不同的遮挡处理规则。

关联类型

• TriggerUnit
• Color