---
id: gh-msw-sprite-ruid
name: "msw-sprite-ruid"
url: https://skills.yangsir.net/skill/gh-msw-sprite-ruid
author: msw-git
domain: game-dev
tags: ["game-development", "sprite-rendering", "asset-management", "ui-rendering", "animation"]
install_count: 2600
rating: 4.40 (120 reviews)
github: https://github.com/msw-git/msw-ai-coding-plugins-official/tree/main/plugins/msw-maker-base-skill/skills/msw-sprite-ruid
---

# msw-sprite-ruid

> 此技能为游戏开发中的 SpriteRendererComponent 和 SpriteGUIRendererComponent 提供 RUID 类型支持，允许直接播放 sprite 和 animationclip，并支持使用 "thumbnail://" 前缀将任意资源渲染为静态缩略图。它简化了游戏内资源（如角色物品图标、动画片段）的显示与管理，提升了开发效率和视觉表现力。

**Stats**: 2,600 installs · 4.4/5 (120 reviews)

## Before / After 对比

### 简化游戏资源渲染与图标生成

**Before**:

在没有此技能之前，开发者需要为不同类型的游戏资源（如骨骼动画、角色物品）编写复杂的渲染逻辑或额外组件，才能将其显示为静态图标或直接播放动画。这导致了开发流程冗长，且容易出错，尤其是在处理库存物品图标时，需要手动转换或管理大量资源。

**After**:

该 Skill 允许开发者直接将 sprite 或 animationclip RUID 赋值给渲染组件，实现动画或静态图的直接播放。通过 "thumbnail://" 前缀，此技能还能将任意资源（包括 skeleton 和 avataritem）一键渲染为静态缩略图，极大地简化了游戏内图标（如物品栏图标）的生成和管理，将开发时间从数小时缩短到几分钟。

| Metric | Before | After | Change |
|---|---|---|---|
| 资源图标生成时间 | 60分钟 | 5分钟 | -91% |

## Readme

# 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 | Native RUID types |
|---|---|---|---|
| `SpriteRendererComponent` (world) | `SpriteRUID` | plain string | `sprite`, `animationclip` |
| `SpriteGUIRendererComponent` (UI) | `ImageRUID` | `{ "DataId": "..." }` | `sprite`, `animationclip` |

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

-- UI: sprite or animationclip RUID both work
self.Entity.SpriteGUIRendererComponent.ImageRUID = { DataId = 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`](../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`

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

-- UI thumbnail (any resource type)
self.Entity.SpriteGUIRendererComponent.ImageRUID = { DataId = "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.

```lua
slotEntity.SpriteGUIRendererComponent.ImageRUID = {
    DataId = "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).
- `ImageRUID` prefix goes **inside** `DataId`: `{ "DataId": "thumbnail://..." }` — not a separate field.
- `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.


---
*Source: https://skills.yangsir.net/skill/gh-msw-sprite-ruid*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-msw-sprite-ruid/markdown*