unity-decal

调用此模块中的任何技能之前： 如果你准备根据技能名称或描述猜测参数来调用技能，请停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已通过 recommend/schema 获取参数定义，则可以直接进行 dryRun。

触发条件

• 在 URP 中添加贴花
• 配置 Decal Projector
• 启用 Decal Renderer Feature
• 在 URP 中添加贴花、配置 Decal Projector、启用 Decal Renderer Feature

Decal 技能

URP Decal Projector 的创建与配置（仅限 URP；此处不涵盖 HDRP 贴花 API）。

运行模式

• 查询技能（decal_get_info、decal_find_all）属于 SkillMode.SemiAuto——在所有三种模式下都无需授权即可运行。
• 修改技能（decal_create、decal_set_properties、decal_set_properties_batch、decal_ensure_renderer_feature）属于 SkillMode.FullAuto——在 Approval 模式下需要用户授权（授权后会触发一次服务端执行并返回结果）；在 Auto / Bypass 模式下会直接执行。
• decal_delete 带有 SkillOperation.Delete 标记，在 Approval / Auto 模式下自动禁止（NeverInSemi）。只有 Bypass 或用户管理的 Allowlist 才能运行。

URP 包存根

此模块基于 com.unity.render-pipelines.universal（URP）编译。未安装 URP 时，每项技能都会返回存根 { error: "Universal Render Pipeline package … is not installed." }（RenderPipelineSkillsCommon.NoURP()）。该存根是诊断负载，而非权限拒绝——无需授权，且不视为 NeverInSemi。

防护措施

路由：

• 通用渲染器功能管理：urp
• DecalProjector 场景操作：此模块

运行时优先规则：

• 在假定当前 URP 渲染器已支持贴花之前，先调用 decal_ensure_renderer_feature
• 编辑之前，使用 decal_get_info / decal_find_all 检查实际投影器状态
• decal_set_properties_batch 要求 items 为 JSON 数组字符串
• 此模块优先面向 URP Decal 工作流；不要假定此处涵盖 HDRP 贴花 API

技能

decal_create

创建 Decal Projector。

参数	类型	必填	默认值	描述
name	字符串	否	"Decal Projector"	新 GameObject 的名称
materialPath	字符串	否	null	贴花材质资源路径；省略时不指定
x	浮点数	否	0	世界位置 X
y	浮点数	否	0	世界位置 Y
z	浮点数	否	0	世界位置 Z

decal_get_info

检查 Decal Projector。

参数	类型	必填	默认值	描述
name	字符串	否*	null	GameObject 名称
instanceId	整数	否*	0	GameObject 实例 ID
path	字符串	否*	null	GameObject 层级路径

* 至少提供一个定位参数——空调用会被直接拒绝，而不会报告为“未找到”。

decal_set_properties

修改 Decal Projector 属性。仅当提供以下属性时才会应用，因此一次调用只会更改你指定的字段；任何无效值都会导致整个调用被拒绝，且不会写入任何内容。

参数	类型	必填	默认值	描述
name	string	否*	null	GameObject 名称
instanceId	int	否*	0	GameObject 实例 ID
path	string	否*	null	GameObject 层级路径
materialPath	string	否	null	Decal 材质资源路径
drawDistance	float	否	null	绘制 Decal 的最大距离
fadeScale	float	否	null	开始淡出的距离占 drawDistance 的比例
fadeFactor	float	否	null	总体不透明度乘数
startAngleFade	float	否	null	基于角度的淡出开始时的角度（度）
endAngleFade	float	否	null	基于角度的淡出完成时的角度（度）
uvScale	string	否	null	UV 平铺，格式为 "x,y"
uvBias	string	否	null	UV 偏移，格式为 "x,y"
size	string	否	null	投影器盒体大小，格式为 "x,y,z"
pivot	string	否	null	投影器枢轴偏移，格式为 "x,y,z"
renderingLayerMask	uint	否	null	渲染层掩码位
scaleMode	string	否	null	ScaleInvariant 或 InheritFromHierarchy（包括纯数字在内的其他值均会被拒绝）

decal_find_all

列出场景中的 Decal Projector。

参数	类型	必填	默认值	描述
limit	int	否	50	返回的最大投影器数量

decal_delete

删除 Decal Projector GameObject。

参数	类型	必填	默认值	描述
name	string	否*	null	GameObject 名称
instanceId	int	否*	0	GameObject 实例 ID
path	string	否*	null	GameObject 层级路径

decal_set_properties_batch

批量编辑 Decal Projector。

参数	类型	必填	默认值	描述
items	json string	是	-	{name, instanceId, path, materialPath, drawDistance, fadeScale, fadeFactor, startAngleFade, endAngleFade, uvScale, uvBias, size, pivot, renderingLayerMask, scaleMode} 的 JSON 数组——每个项目使用与 decal_set_properties 相同的键

decal_ensure_renderer_feature

确保目标 URP 渲染器具有 DecalRendererFeature。

参数	类型	必填	默认值	描述
assetPath	string	否	null	URP 资源路径；省略时使用活动 URP 资源
rendererIndex	int	否	-1	URP 资源中的渲染器索引；-1 表示选择该资源的默认渲染器
rendererDataPath	string	否	null	UniversalRendererData 资源路径——优先于 rendererIndex，且必须属于解析出的 URP 资源

如果该功能已存在，则返回 alreadyExists: true，因此可以安全地重复调用。

---

精确签名

精确名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非本文件。