工坊手册

主题

RenderTriggerUnit ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • SpaceUnit（2 属性 / 9 函数）
      • BasePart（24 属性 / 9 函数）
        • TriggerUnit（8 属性 / 7 函数 / 4 事件）
          • [RenderTriggerUnit]（18 属性 / 1 函数）

继承成员 ​

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

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

适用场景 ​

用于需要同时展示模型和检测单位进入、离开的场景区域。可通过 RenderMeshId 指定可见模型，通过物理与碰撞属性设置触发范围，并监听 OnTriggerEnter、OnTriggerExit 处理交互。

使用要点 ​

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

注意事项 ​

运行时外观使用 RenderMeshId，DisplayModelId 是 editOnly 的编辑器预览字段，不影响运行时渲染。作者可见脚本可用 SkinId 与 ModelColor1~4 配置单皮肤外观，也可用公开的 UseSkinList 与 SkinSlots 配置多槽位外观；Color 使用 0-255 RGBA 四参数构造。

代码示例 ​

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

lua
-- @runtime client
local world = game:GetService("World")
-- 不指定 RenderMeshId 时使用 Meta 声明的默认模型，避免硬编码资源 ID
local renderTrigger = world:CreateUnit("RenderTriggerUnit", {})
if renderTrigger == nil then return end
renderTrigger.ModelColor1 = Color.New(255, 0, 0, 255)
renderTrigger.ModelVisible = true
renderTrigger.OnTriggerEnter:Once(function(otherUnit)
    print("进入触发区域:", otherUnit.Name)
    renderTrigger:Destroy()  -- 完成一次交互后释放自有区域
end)
-- 若未发生进入事件，请在业务结束时调用 renderTrigger:Destroy()

属性 (18) ​

Name类型默认值说明
RenderMeshIdStringofficial://mesh/59268RenderMeshId 是 RenderTriggerUnit 的模型资源 ID 属性，类型为字符串，用于指定该渲染触发单元当前显示的模型资源。
ModelAlphaFloat1控制模型的整体透明度，0 为完全透明，1 为完全不透明
LocalTransparencyModifierFloat1该单元的本地透明度乘数，用于在本地客户端进一步调整模型透明度。
ModelVisibleBooltrue控制模型是否可见，隐藏后仍参与物理碰撞
CastShadowBooltrueCastShadow 是 RenderTriggerUnit 的布尔属性，用于控制该单元是否投射阴影。
ModelBindParentBoolfalse启用后，当父节点为 WorldUnit、RenderUnit、TriggerUnit、PhysicsUnit 等支持父子带动的场景单位时，当前模型渲染表现将跟随父节点的变换自动同步。运行时可通过脚本设置 .ModelBindParent = true/false 动态切换该行为。
PhysicsMeshIdStringofficial://mesh/59268物理资源 ID，字符串类型，属性面板标题为“物理资源ID”。该属性用于为 RenderTriggerUnit 指定物理资源，属于可编辑的公开属性。
DisplayModelIdString""用于在编辑器中预览的模型资源 ID，不影响运行时实际渲染的模型。
ModelColor1ColorColor.New(255, 255, 255, 255)ModelColor1 是 RenderTriggerUnit 的染色区域 1 颜色属性，类型为 Color，用于设置模型上第 1 个染色区域的颜色。
ModelColor2ColorColor.New(255, 255, 255, 255)ModelColor2 是 RenderTriggerUnit 的染色区域 2 颜色属性，类型为 Color，用于设置模型上第 2 个染色区域的颜色。
ModelColor3ColorColor.New(255, 255, 255, 255)ModelColor3 是 RenderTriggerUnit 的染色区域 3 颜色属性，类型为 Color，用于设置模型上第 3 个染色区域的颜色。
ModelColor4ColorColor.New(255, 255, 255, 255)ModelColor4 是 RenderTriggerUnit 的染色区域 4 颜色属性，类型为 Color，用于设置模型上第 4 个染色区域的颜色。
SkinIdString""SkinId 是 RenderTriggerUnit 的皮肤属性，类型为字符串，用于指定该单元使用的皮肤资源。
UseSkinListBoolfalse多槽位皮肤开关；启用后按各子网格的 SkinSlots 配置皮肤与染色。
SkinSlotsArray<SkinSlot>[]各子网格的皮肤与染色配置列表；元素包含 SkinId 和 ModelColor1~4。
UseCustomAppearanceBoolfalse是否启用自定义外观。
CustomAppearanceIdString""自定义外观 ID，字符串类型，属性面板标题为“自定义外观ID”。该属性用于为 RenderTriggerUnit 指定自定义外观资源，属于可编辑的公开属性。
OcclusionTypeInt3 (不处理)OcclusionType 属性用于设置该渲染触发单位在遮挡玩家视角时所采用的规则，影响其被相机遮挡时的表现方式。该属性为整数类型，具体取值对应不同的遮挡处理规则。

关联类型 ​

函数 (1) ​

SetRenderMeshWithDefaultSkin ​

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

SetRenderMeshWithDefaultSkin 是 RenderTriggerUnit 的成员函数，用于切换该单元使用的模型，并为新模型应用默认皮肤。参数 renderMeshId 为必填的字符串，表示目标模型资源 ID。

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

返回值 void

示例代码

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

lua
-- @runtime client
local world = game:GetService("World")
local renderTrigger = world:CreateUnit("RenderTriggerUnit", {})
if renderTrigger == nil then return end
-- 用单位自身的 RenderMeshId（Meta 默认值）演示，不硬编码资源 ID
renderTrigger:SetRenderMeshWithDefaultSkin(renderTrigger.RenderMeshId)
print("已切换模型:", renderTrigger.RenderMeshId)
renderTrigger:Destroy()