画像読み込み (Image Loading)

画像読み込み機能を使うと、インターネット上の画像をVRChatワールド内に表示できます。ユーザーがワールドを訪れると、インターネットから画像がダウンロードされ、マテリアルのテクスチャとして使用されます。画像読み込みの活用例をいくつか紹介します。

• ワールドを再アップロードすることなく、ワールド内のテクスチャを更新する。
• ワールド内にポスターを作成し、季節のイベントやパーティーに合わせて更新する。
• 同じテクスチャを複数のワールドで再利用し、すべて一括で更新する。

SDKには使いやすい ImageDownload スクリプトが同梱されています。また、新しい VRCImageDownloader オブジェクトを使用して独自のスクリプトを作成することも可能です。

始める前に

Image Loaderには、知っておくべきいくつかの制限とパラメータがあります。

• 最大解像度は 2048 × 2048 ピクセルです。これより大きい画像をダウンロードしようとするとエラーになります。
• 画像は5秒ごとに1つダウンロードできます。
• この制限を超えた場合、画像のダウンロードはキューに入れられ、ランダムな順序でダウンロードされます。
• この制限は、使用されている VRCImageDownload コンポーネントの数に関係なく、シーン全体に適用されます。
• URLは画像ファイルを直接指している必要があります。URLリダイレクトは許可されておらず、エラーになります。
• ダウンロードされた画像は、自動的に RGBA、RGB、または RG として解釈されます。
• 例えば、アルファチャンネル付きのグレースケール画像は RG 画像として解釈されます。
• キューに入れられる要素数には1000個の制限があります。
• Input バッファと Output バッファはどちらも最大32MBに制限されており、これを超える画像はエラーになります。

また、許可されているドメインは特定のドメインのみです。リストにないドメインの場合、ユーザー設定で Allow Untrusted URLs が有効になっていない限り、画像はダウンロードされません。

• DisBridge (*.disbridge.com)
• Dropbox (dl.dropbox.com,dl.dropboxusercontent.com)
• GitHub (*.github.io)
• ImageBam (images4.imagebam.com)
• ImgBB (i.ibb.co)
• imgbox (images2.imgbox.com)
• Imgur (i.imgur.com)
• Postimages (i.postimg.cc)
• Reddit (i.redd.it)
• Twitter (pbs.twimg.com)
• VRCDN (*.vrcdn.cloud)
• VRChat (assets.vrchat.com)
• Ytimg (i.ytimg.com)

メモリ管理

ダウンロードした画像は大量のメモリを消費することがあります。画像の使用が終わったら、Udonを使って破棄することでメモリを解放し、他の用途に利用できるようにしてください。

例えば、新しい画像をダウンロードして、以前にダウンロードした別の画像と置き換えたい場合は、以下に説明する Dispose メソッドを使用して、古い画像をメモリから削除してください。これを行わずに新しい画像のダウンロードを続けると、ワールドの訪問者が長時間滞在した際にメモリ不足が発生し、クラッシュする可能性があります！

UdonGraph ノード

VRCImageDownloader

VRCImageDownloader のコンストラクタを使用して画像ダウンローダーを作成します。これにより、実行中にインターネットから画像をダウンロードできるようになります。

DownloadImage

画像をダウンロードし、成功または失敗を示すイベントを呼び出します（以下の「イベント」を参照）。 ダウンロードの進行状況を追跡するために使用できる IVRCImageDownload を返します。

• Instance: 画像のダウンロードに使用する ImageDownloader コンポーネント。
• Url: ダウンロードするテクスチャの VRCURL。
• Material (任意): ダウンロードした画像をメインテクスチャとして自動的に適用するマテリアル。
• UdonBehavior (任意): VRCImageDownloader イベントの送信先となる Udonbehavior。UdonGraph で udonBehavior が空のままの場合、現在の UdonBehaviour がすべてのイベントを受け取ります。
• UdonSharp では、udonBehavior が指定されていない限りイベントを受け取らない点に注意してください。
• TextureInfo (任意): 新しく作成されるテクスチャの設定を含む TextureInfo オブジェクト。

Dispose

VRCImageDownloader をクリーンアップします。ダウンロードしたテクスチャをメモリから解放します。 VRCImageDownloader に対して Dispose を呼び出すと、そのオブジェクトは無効化され、新しい画像のダウンロードには使用できなくなります。

破棄およびガベージコレクションに関する注記:

• Dispose を呼び出すと、VRCImageDownloader、それに関連するすべての IVRCImageDownload オブジェクト、およびそれらのダウンロードに関連付けられたテクスチャが無効になります。
• 単一のダウンロードのみを破棄したい場合は、代わりに IVRCImageDownload オブジェクトに対して Dispose を呼び出してください。
• VRCImageDownloader への参照を変数として保存し、そのオブジェクト（およびダウンロードされたテクスチャ）が意図せずガベージコレクションされないようにしてください。

TextureInfo

ダウンロードしたテクスチャに適用する設定を含みます。

• GenerateMipMaps: Mipmap 生成を有効にします。（デフォルト: false）
• FilterMode: テクスチャの FilterMode を設定します。（デフォルト: Trilinear）
• WrapModeU: U（水平）軸に沿った TextureWrapMode。（デフォルト: Repeat）
• WrapModeV: V（垂直）軸に沿った TextureWrapMode。（デフォルト: Repeat）
• WrapModeW: W（奥行き、Texture3D のみ関連）軸に沿った TextureWrapMode。（デフォルト: Repeat）
• AnisoLevel: テクスチャの anisoLevel。0はフィルタリング無効、16はフルフィルタリングです。（デフォルト: 9）
• VRChat は強制的に異方性フィルタリングを使用します。anisoLevel の値が1から9の間にある場合、Unity は anisoLevel を9に設定します。値が9より大きい場合、Unity はそれを9から16の間に固定します。
• MaterialProperty: DownloadImage 内で material が指定されている場合に、ダウンロードしたテクスチャを適用する MaterialProperty を上書きします。（デフォルト: _MainTex）

IVRCImageDownload

ダウンロードした画像に関する情報を含みます。VRCImageDownloader の DownloadImage 関数、OnImageLoadSuccess、および OnImageLoadError によって返されます。 これらのフィールドの多くは、ダウンロードが完了または失敗するまで無効であることに注意してください。

• Get Error: イベントに関連付けられた VRCImageDownloadError を取得します。
• Get Errormessage: エラーメッセージを string として取得します。
• Get Material: DownloadImage 関数に送信された Material を取得します。
• Get Progress: 画像ダウンロードの進捗を 0 から 1 の範囲の float として取得します。これは、カスタムの読み込みバーなどでダウンロードの進行状況を追跡する場合に使用してください。
• Get Result: ダウンロードされた画像の Texture2d です。
• Get SizeInMemoryBytes: テクスチャのサイズ（バイト単位）を int として取得します。
• Get State: 画像ダウンロードの状態を示す VRCImageDownloadState を取得します。
• Get TextureInfo: DownloadImage 関数に渡されたテクスチャ情報（TextureInfo）です。
• Get Udonbehavior: 画像ダウンロードのイベントの送信先である指定の UdonBehavior を取得します。
• Get URL: 画像ダウンロードの VRCURL を取得します。

VRChat は、ダウンロードされた画像の texture format を自動的に選択します。

• アルファチャンネルを持つ画像は RGBA32、RGB64 などとして読み込まれます。
• アルファチャンネルを持たない画像は RGB24、RGB48 などとして読み込まれます。
• グレースケール画像は R8、R16 などとして読み込まれます。

Dispose

IVRCImageDownload をクリーンアップします。ダウンロードしたテクスチャをアンロードし、使用していたメモリを解放します。 VRCImageDownloader の Dispose メソッドとは異なり、このメソッドは個別のダウンロードとその関連テクスチャのみを破棄し、他のダウンロードやそのテクスチャには影響を与えません。 IVRCImageDownload を破棄すると、その State が Unloaded に変更されます。

VRCImageDownloadState

IVRCImageDownload における画像ダウンロードの状態を示します。

• Pending: 開始されていない、または現在進行中です。
• Error: ダウンロードが失敗し、エラーが発生しました（VRCImageDownloadError を参照）。
• Complete: ダウンロードが完了し、テクスチャを使用できる状態です。
• Unloaded: IVRCImageDownload に対して Dispose が呼び出された後、ガベージコレクション待ちの状態です。
• Unknown: 不明な状態です。

VRCImageDownloadError

画像ダウンロードが失敗すると、OnImageLoadError が呼び出されます。IVRCImageDownload の Error フィールドには、以下のいずれかのエラー状態が含まれます。

• InvalidURL: DownloadImage で使用されたダウンロードURLが無効です。
• AccessDenied: URLへのアクセスが拒否されました。
• InvalidImage: ダウンロードされた画像が無効です。
• DownloadError: ウェブリクエストエラーが発生しました。
• Unknown: 不明なエラー状態です。

イベント

• OnImageLoadSuccess: IVRCImageDownload を返します。VRCImageDownloader が画像のダウンロードに成功したときに呼び出されます。
• OnImageLoadError: IVRCImageDownload を返します。VRCImageDownloader が画像のダウンロードに失敗したときに呼び出されます。

最終更新: 2026年6月17日