msw-sprite-ruid

MSW Sprite RUID

为 SpriteRendererComponent.SpriteRUID（世界）或 SpriteGUIRendererComponent.ImageRUID（UI）分配 RUID 的规则。

---

原生类型支持

这两个组件都可以直接接受 sprite 或 animationclip RUID，无需额外的 animator 组件。

组件	属性	值形式（运行时 .mlua）	原生 RUID 类型
SpriteRendererComponent（世界）	SpriteRUID	纯字符串	sprite、animationclip
SpriteGUIRendererComponent（UI）	ImageRUID	DataRef("...")	sprite、animationclip

ImageRUID 是一个 DataRef：在运行时 .mlua 中，赋值为 DataRef(ruid)。 仅在 .ui / .model JSON 或构建器补丁数据中使用 { DataId: ruid }。 SpriteRUID 仍为纯字符串。

-- World: sprite or animationclip RUID both work
self.Entity.SpriteRendererComponent.SpriteRUID = ruid

-- UI: sprite or animationclip RUID both work
self.Entity.SpriteGUIRendererComponent.ImageRUID = DataRef(ruid)

未加 thumbnail:// 前缀的 skeleton / avataritem RUID 会 静默失败（无报错，也不会渲染任何内容）。

---

animationclip：单个动画与多状态动画

• 单个循环动画（背景装饰、待机效果、道具）：将 SpriteRUID 或 ImageRUID 直接设为 animationclip RUID。
• 多状态动画（站立 / 移动 / 攻击 / 受击 / 死亡）：使用 StateAnimationComponent + ActionSheet。参见 msw-general/references/monster.md。

---

thumbnail:// 前缀——从任意资源获取静态缩略图

在 SpriteRUID 或 ImageRUID 前添加 thumbnail://，即可渲染任意资源的静态 缩略图——适用于图标、预览图和物品缩略图。

thumbnail://<32-char hex RUID>

接受的类型：sprite · animationclip · skeleton · avataritem

-- World thumbnail (any resource type)
self.Entity.SpriteRendererComponent.SpriteRUID = "thumbnail://" .. anyRuid

-- UI thumbnail (any resource type)
self.Entity.SpriteGUIRendererComponent.ImageRUID = DataRef("thumbnail://" .. anyRuid)

主要用途：avataritem 图标

avataritem RUID 不加 thumbnail:// 就无法渲染。添加此前缀后，它们会显示为物品图标，可用于背包栏位、商店列表和装备预览。

slotEntity.SpriteGUIRendererComponent.ImageRUID = DataRef("thumbnail://" .. avatarItemRuid)

使用 msw-search 技能（searchAvatarItems）搜索 avatar item RUID。

---

常见问题

• 将 skeleton / avataritem 直接赋给 SpriteRUID / ImageRUID，不加前缀 → 静默不可见。
• thumbnail:// 仅用于静态图片。要播放实时动画，直接赋值 animationclip RUID（不加前缀）。
• 运行时 .mlua 使用 ImageRUID = DataRef("...")；{ "DataId": "..." } 对象形式仅适用于 .ui / .model JSON（前缀应放在 DataId 内部，而非单独字段中）。运行时代码中不要使用表格形式——LSP 会因 DataRef 类型不匹配而拒绝。
• CostumeManagerComponent.Custom*Equip、StateAnimationComponent.ActionSheet 和 SkeletonRendererComponent.SkeletonRUID 不接受 thumbnail://。
• 不要给从 msw-search 作为缩略图或图标图片获取的 RUID 再加 thumbnail://。此前缀会将源资源转换为缩略图；对已是缩略图的 sprite 使用此前缀在逻辑上是多余的。如果搜索查询针对图标 / 缩略图图片，且返回了 sprite RUID，请直接赋值，不加任何前缀。
• 要搜索 RUID，请使用 msw-search 技能——头像物品使用 searchAvatarItems；其他内容使用 searchResources。