msw-sprite-ruid

SKILL.md

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

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

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 = { 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.

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.