msw-sprite-ruid

MSW Sprite RUID

SpriteRendererComponent.SpriteRUID（ワールド）または SpriteGUIRendererComponent.ImageRUID（UI）に RUID を割り当てる際のルールです。

---

ネイティブ型のサポート

どちらのコンポーネントも、sprite または animationclip の RUID を直接受け取れます。追加のアニメーターコンポーネントは不要です。

コンポーネント	プロパティ	値の形式（ランタイムの .mlua）	ネイティブの RUID 型
SpriteRendererComponent（ワールド）	SpriteRUID	文字列	sprite、animationclip
SpriteGUIRendererComponent（UI）	ImageRUID	DataRef("...")	sprite、animationclip

ImageRUID は DataRef です。ランタイムの .mlua では、DataRef(ruid) を割り当ててください。 { DataId: ruid } を使うのは、.ui／.model の JSON またはビルダーパッチデータのみです。 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 を使って、アバターアイテムの 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 の RUID が返された場合は、プレフィックスなしでその RUID を直接割り当ててください。
• RUID を検索するには、msw-search スキルを使ってください。アバターアイテムには searchAvatarItems、それ以外には searchResources を使います。