360 Secure SkillHub
360 安全技能中心

msw-sprite-ruid

说明世界与 UI 精灵渲染器如何接收 sprite 或 animationclip RUID，介绍 thumbnail 前缀将 skeleton/avataritem 渲染为静态缩略图，并给出 DataRef 用法、类型限制和常见错误。

MSW-Git
热度 78.07
最近更新 2026-10-19 02:37:49
分类：开发依赖：纯提示词应用场景：代码生成 / 模板

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add msw-git/msw-ai-coding-plugins-official/msw-sprite-ruid
Metadata
name
msw-sprite-ruid
description
SpriteRendererComponent.SpriteRUID (world) and SpriteGUIRendererComponent.ImageRUID (UI) — native RUID type support (sprite / animationclip direct playback), thumbnail:// prefix for rendering avataritem / skeleton / animationclip as static thumbnail image, avatar item icon in inventory / shop / UI slot. Use when: assigning any RUID to a sprite renderer component, displaying an avatar item or resource as a thumbnail or icon, using animationclip directly in a renderer, rendering inventory item icons, displaying a thumbnail image in a world entity. Keywords: SpriteRUID, ImageRUID, thumbnail://, animationclip, RUID apply, RUID assign, thumbnail, item icon, sprite RUID, RUID to renderer

MSW Sprite RUID

Rules for assigning a RUID to SpriteRendererComponent.SpriteRUID (world) or SpriteGUIRendererComponent.ImageRUID (UI).

Native type support

Both components accept a sprite or animationclip RUID directly — no extra animator component required.

Component Property Value form (runtime .mlua) Native RUID types
SpriteRendererComponent (world) SpriteRUID plain string sprite, animationclip
SpriteGUIRendererComponent (UI) ImageRUID DataRef("...") sprite, animationclip

ImageRUID is a DataRef: in runtime .mlua, assign DataRef(ruid). Use { DataId: ruid } only in .ui / .model JSON or builder patch data. SpriteRUID remains a plain string.

-- 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)

A skeleton / avataritem RUID assigned without the thumbnail:// prefix fails silently (no error, nothing renders).

animationclip: single animation vs multi-state

  • Single looping animation (background deco, idle effect, prop): set SpriteRUID or ImageRUID directly to the animationclip RUID.
  • Multi-state (stand / move / attack / hit / die): use StateAnimationComponent + ActionSheet. See msw-general/references/monster.md.

thumbnail:// prefix — static thumbnail from any resource

Prepend thumbnail:// to SpriteRUID or ImageRUID to render a static thumbnail image from any resource — useful for icons, preview images, and item thumbnails.

thumbnail://<32-char hex RUID>

Accepted types: 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)

Primary use case: avataritem icons

avataritem RUIDs cannot render without thumbnail://. With the prefix they become item icons for inventory slots, shop listings, and equip previews.

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

Search avatar item RUIDs with the msw-search skill (searchAvatarItems).

Common pitfalls

  • skeleton / avataritem directly into SpriteRUID / ImageRUID without prefix → silently invisible.
  • thumbnail:// = static image only. For live animation, assign the animationclip RUID directly (no prefix).
  • Runtime .mlua uses ImageRUID = DataRef("..."); the { "DataId": "..." } object form is .ui / .model JSON only (the prefix goes inside DataId, not a separate field). Do not use the table form in runtime code — the LSP rejects it as a DataRef type mismatch.
  • CostumeManagerComponent.Custom*Equip, StateAnimationComponent.ActionSheet, and SkeletonRendererComponent.SkeletonRUID do not accept thumbnail://.
  • Do not prepend thumbnail:// to a RUID that was already retrieved as a thumbnail or icon image from msw-search. The prefix converts a source resource into its thumbnail — applying it to an already-thumbnail sprite is logically redundant. If the search query targeted an icon / thumbnail image and returned a sprite RUID, assign that RUID directly without any prefix.
  • To search for RUIDs use the msw-search skill — searchAvatarItems for avatar items; searchResources for everything else.