SketchEffect

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • BasePostEffect（1 属性）
    • [SketchEffect]（15 属性）

继承成员

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

• 来自 BasePostEffect（1 属性）
  • 属性：Enabled
• 来自 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

素描效果是一种把整个画面转为手绘铅笔素描风格的后处理单元，通过暗角缩放、去色强度与描边宽度控制整体观感。它还提供笔触颜色、描边强度与笔触密度，并用密集、中度、稀疏三档笔触强度配合对应阈值来塑造线条层次。纸张颜色与纸张亮度、画面不透明度则决定素描底色的呈现。

适用场景

常用来为整张地图切换手绘或素描观感，例如在剧情演出、特殊关卡或氛围切换时，动态修改暗角、去色强度与描边参数来改变画面风格。

使用要点

先通过 game:CreateUnit("SketchEffect", config) 创建实例（也可用 World:CreateUnit），并把它设置到 Parent 上使其进入生效层级；随后按顺序读写 VignetteZoom、DesaturationStrength、OutlineWidth 等属性来调整整体风格。需要进一步刻画线条时，可继续设置 StrokeColor、OutlineStrength、StrokeDensity，以及 DenseStrokeStrength、MediumStrokeStrength、SparseStrokeStrength 与 DenseThreshold、MediumThreshold、SparseThreshold。颜色类属性使用 Color.New(...) 构造的 Color 值赋值，例如把描边颜色设为 Color.New(1.0, 0.0, 0.0, 1.0)，并把纸面观感交给 PaperColor 与 PaperLightness 控制。

注意事项

该单元只能通过 game:CreateUnit("SketchEffect", config) 或 World:CreateUnit("SketchEffect", config) 获取实例，不存在 TypeName.New 这类构造方式，未通过公开返回值或创建接口拿到的对象不可使用。作为画面级后处理，属性一旦写入会立刻影响当前渲染结果，因此同一时间通常只保留一份有效实例，不再需要时应及时销毁。颜色属性必须传入 Color 实例，用 Color.New(...) 构造后再赋值，避免直接写入不匹配的数值类型。

代码示例

创建 SketchEffect 并挂载到光照服务

-- @runtime client
local Lighting = game:GetService('LightingService')
local sketchEffect = game:CreateUnit('SketchEffect', {
    Enabled = true,
})
if sketchEffect == nil then return end
sketchEffect.Parent = Lighting
print('后处理已启用:', sketchEffect.Enabled)

属性 (15)

Name	类型	默认值	说明
VignetteZoom	Float	1.0	VignetteZoom 是 SketchEffect（素描风格后处理效果）单元上的一个可读写 Float 属性，标题为“暗角缩放”，用于设置该素描后处理效果中与暗角相关的缩放参数。
DesaturationStrength	Float	0.0	去色强度，控制画面颜色被去除的程度。数值越大，画面颜色越暗淡，越接近灰度表现。
OutlineWidth	Int	4	描边宽度，控制轮廓描边线条的粗细程度，取值为整数。
StrokeColor	Color	Color.New(0, 0, 0, 255)	笔触颜色，控制素描效果中笔触与描边线条使用的颜色。
OutlineStrength	Float	1.0	描边强度，控制轮廓描边线条的明显程度。数值越大，描边越突出。
StrokeDensity	Float	1.0	笔触密度，控制素描效果中笔触线条的密集程度。数值越大，笔触越密集。
DenseStrokeStrength	Float	1.0	密集笔触强度，控制画面中密集线条区域的笔触强度。
MediumStrokeStrength	Float	1.0	中度笔触强度，控制画面中中等密度线条区域的笔触强度。
SparseStrokeStrength	Float	1.0	稀疏笔触强度，控制画面中稀疏线条区域的笔触强度。
SceneOpacity	Float	1.0	画面不透明度，控制经素描处理后的画面整体的不透明度。
DenseThreshold	Float	0.35	密集线条阈值，控制笔触区域被划分为密集线条的判定界限。
MediumThreshold	Float	0.45	中度线条阈值，控制笔触区域被划分为中等密度线条的判定界限。
SparseThreshold	Float	0.55	稀疏线条阈值，控制笔触区域被划分为稀疏线条的判定界限。
PaperColor	Color	Color.New(0, 0, 0, 255)	纸张颜色，控制素描效果底层的纸张背景颜色。
PaperLightness	Float	1.0	纸张亮度，控制素描效果底层纸张背景的明暗程度。

关联类型

• BasePostEffect
• Color