Asset Hooks

PlayCanvas React は、さまざまな Asset を読み込み・管理するためのフックを提供します。これらのフックは Asset の読み込みを簡素化し、読み込み中やエラー状態を扱えるようにします。

各フックの一般的なシグネチャは、次のような形です。

const { asset, loading, error } = useModel(src, props);

src は Asset の URL、props は Asset ローダーに渡す追加のプロパティです。

import { useModel } from '@playcanvas/react/hooks';

export function RenderAsset() {
    const { asset, loading, error } = useModel('model.glb');

    if (loading) return <LoadingSpinner />;
    if (error) return <ErrorMessage message={error} />;
    if (!asset) return null;

    return <Render asset={asset} />;
}

読み込み進捗

useAsset フックは、subscribe コールバックで読み込み進捗をサポートします。読み込みインジケーターやプログレスバーを表示したい場合に便利です。すべての Asset タイプが読み込み中に進捗値を返すわけではないため、すべてのタイプで利用できるとは限りません。

import { useSplat } from '@playcanvas/react/hooks';

export function RenderSplat() {
  const [progress, setProgress] = useState(0);
  const { asset, loading, error, subscribe } = useSplat('splat.ply');

  // Subscribe to loading progress
  useEffect(() => {
    const unsubscribe = subscribe(({ progress }) => setProgress(progress));
    return () => unsubscribe();
  }, [subscribe]);

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!asset) return null;

  return (<Entity>
    <GSplat asset={asset} />
  </Entity>);
}

すべてのフック

次のフックが利用できます。

useModel — 3D モデル Asset を読み込む
useSplat — Gaussian Splat Asset を読み込む
useTexture — テクスチャ Asset を読み込む
useEnvAtlas — 環境アトラステクスチャを読み込む
useAsset — 任意のタイプの Asset を読み込む汎用フック

API

Asset フックの完全な戻り値は次のとおりです。

Name	Type	Default
`asset`	`Asset<string> \| null` The loaded asset, or null if not loaded or failed	`null`
`loading`	`boolean` Whether the asset is currently loading, or false if it has loaded or failed	`true`
`error`	`string \| null` Error message if loading failed, or null if successful	`null`
`subscribe`	`(cb: AssetResultCallback) => () => void` Use this to subscribe to loading progress events	`-`

useModel

3D モデル Asset（GLB/GLTF）を読み込むための専用フックです。モデルファイルのソース URL と、Asset ローダーに渡す追加のプロパティを指定し、得られた Asset を <Render/> コンポーネントで使います。

import { useModel } from '@playcanvas/react/hooks';

export function RenderModel() {
  const { asset, loading, error } = useModel('model.glb');

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!asset) return null;

  return <Render asset={asset} />;
}

Draco デコード

useModel フックは、追加設定なしで Draco デコードにも対応しています。@playcanvas/react は最新版の Draco デコーダー（1.5.7）を使用し、Google CDN から遅延読み込みします。

ライブラリを自前でホストする場合は、dracoInitialize を使ってデコーダーを手動で設定できます。

import { dracoInitialize } from 'playcanvas';

dracoInitialize({
  jsUrl: '/draco_decoder.js',
  wasmUrl: '/draco_decoder.wasm',
  lazyInit: true
});

useSplat

Gaussian Splat Asset を読み込むための専用フックです。splat ファイルのソース URL と、Asset ローダーに渡す追加のプロパティを指定し、得られた Asset を <GSplat/> コンポーネントで使います。

import { useSplat } from '@playcanvas/react/hooks';

export function RenderSplat() {
  const { asset, loading, error } = useSplat('splat.ply');
  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!asset) return null;

  return (<Entity>
    <GSplat asset={asset} />
  </Entity>);
}

詳しくは <GSplat/> コンポーネントを参照してください。

useTexture

テクスチャ Asset を読み込むための専用フックです。テクスチャファイルのソース URL と、Asset ローダーに渡す追加のプロパティを指定し、テクスチャを受け取れる任意のコンポーネントで使います。

import { useTexture } from '@playcanvas/react/hooks';
import { useMaterial } from '@playcanvas/react/hooks';

export function RenderTexture() {
  const { asset, loading, error } = useTexture('texture.jpg');
  const material = useMaterial({ diffuseMap: asset?.resource });

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!asset) return null;

  return <Render type="box" material={material} />;
}

詳しくは useMaterial フックと Render コンポーネントを参照してください。

useEnvAtlas

環境アトラステクスチャを読み込むための専用フックです。テクスチャファイルのソース URL と、Asset ローダーに渡す追加のプロパティを指定し、得られた Asset を <Environment/> コンポーネントで使います。

import { useEnvAtlas } from '@playcanvas/react/hooks';
import { Environment } from '@playcanvas/react/components';

export function RenderEnvAtlas() {
  const { asset, loading, error } = useEnvAtlas('env.jpg');

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!asset) return null;

  return <Environment envAtlas={asset} />;
}

詳しくは Environment コンポーネントを参照してください。

useFont

PlayCanvas ではテキストがマルチチャンネル符号付き距離場（MSDF）フォントで描画されるため、TTF や OTF のフォントは、まず .json ファイルと 1 枚以上の .png テクスチャからなるフォントアセットに変換します。font-tools の Web アプリかコマンドラインで作成し、アプリと一緒に配信してください。たとえば Vite プロジェクトなら public フォルダーに置きます。

npx @playcanvas/font-tools Inconsolata.ttf --charset latin -o public/fonts/inconsolata

次に useFont で .json ファイルを読み込み（テクスチャも一緒に読み込まれます）、そのアセットをテキストエレメントに渡します。

import { Entity } from '@playcanvas/react';
import { Element } from '@playcanvas/react/components';
import { useFont } from '@playcanvas/react/hooks';

export function RenderText() {
  const { asset, loading, error } = useFont('fonts/inconsolata.json');

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!asset) return null;

  return (
    <Entity name="label">
      <Element type="text" fontAsset={asset} text="Hello, World!" />
    </Entity>
  );
}

フォントに含める文字の選び方はフォント、スクリーン上へのテキストの描画はテキストエレメントを参照してください。

useAsset

任意のタイプの Asset を読み込む汎用フックです。PlayCanvas がサポートする任意の Asset タイプの読み込みに使え、動的に Asset を読み込む必要がある場合に便利です。

import { useAsset } from '@playcanvas/react/hooks';

const assetTypeToLoadType = {
    'ply': useSplat,
    'jpg': useTexture,
    'png': useTexture,
    'glb': useModel,
    'gltf': useModel,
}

export function useDynamicAsset(src: string, props: Record<string, unknown> = {}) {

  const mimeType = src.split('.').pop();
  const loadType = assetTypeToLoadType[mimeType];

  if (!loadType) {
    throw new Error(`Unsupported asset type: ${mimeType}`);
  }

  return useAsset(src, loadType, props);
}

読み込み進捗​

すべてのフック​

API​

useModel​

Draco デコード​

useSplat​

useTexture​

useEnvAtlas​

useFont​

useAsset​