すべての素材を、ひとつの名前で扱う。

紙芝居DSL 4.0集約ランタイム

集約されたブロックも、このリファレンスを使います。

DSL 4.0ランタイムのパレットでAsset Managerの見出しを探し、その直下の ドキュメントボタンを押すと、このガイドが開きます。集約後もブロックの意味と名前は同じで、 ランタイムが拡張機能別の名前空間とアイコンを加えます。

クイックスタート

読み込む、登録する、使う。

Asset Manager は TurboWarp のレンダラー、音声機能、プロジェクト内リソースを利用するため、 サンドボックスを無効にして実行する必要があります。

1. 拡張機能を読み込む

   TurboWarp で 拡張機能を追加 → カスタム拡張機能を選び、次の URL を貼り付けます。

   https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.13.0/dist/asset-manager.js

   サンドボックスなしで実行を有効にします。

2. リソースを登録する

   プロジェクトのほかの場所で使う短い名前を付けます。

   リソース [https://example.com/hero.png] を
     アセット [Hero] として登録する

3. 名前でアセットを使う

   種類が合う表示・音声・アニメーションの各ブロックで同じ名前を使えます。

   このスプライトにアセット [Hero] を表示する

動作の仕組み

ひとつの登録簿が、素材と出力先をつなぎます。

登録時に、選んだ名前と素材の種類・場所を記録します。その後のブロックは名前から種類を調べ、 画像、音声、テキストのうち適切な処理へ自動的に振り分けます。

どのリソース識別子を使えばよいですか？

Web 素材とキャッシュの仕組み

URL を指定すると必ず新しいデータを取得し、同名のキャッシュを更新します。 リソース識別子を空欄にすると通信せず、同じ名前のデータを IndexedDB から読み込みます。 名前ごとの世代を確認してから IndexedDB とメモリーを更新するため、先に開始した古い通信が 遅れて完了しても、最後に開始した有効な登録を上書きしません。

Compositionホスト向けの正確なプロジェクト素材locator

バージョン0.8.0では、compositionホストがコスチューム、背景、音をstructured locatorで登録できます。前後の空白、.、/、:、 制御文字を含むScratch名をそのまま照合します。structured locatorでは、登録に使う論理名も 既定でliteralに保持します。

await assets.registerProjectAsset({
  name: 'Costume.1 / presentation',
  locator: {
    kind: 'costume',
    target: 'Actor / presenter',
    name: 'Costume.1 / source'
  }
});

音のlocatorでtargetを省略するとStageを選びます。既存の文字列 resourceId形式には互換性があり、従来のtrimとcolon grammarを維持します。 embedded assetで論理名をliteralにする場合はnameMode: 'literal'を指定します。

Composition ホスト向け検証済みリモートキャッシュ

バージョン 0.6.0 では、app shell や複合拡張機能からブロックを追加せずに使える cache-first の経路を追加しました。これは上記の従来型「アセット名キー」のキャッシュとは別です。 ホストがネットワーク loader と、期待する SHA-256・バイト数・Content-Type を渡します。 IndexedDB の内容が正しければ通信せず返し、なければダウンロード後に検証を通ったデータだけを 保存します。取得元 URL や認証情報は保存しません。

import {
  createAssetManagerComposition,
  createVerifiedRemoteCacheDatabaseName
} from '@kubohiroya/turbowarp-asset-manager/composition';

const databaseName = createVerifiedRemoteCacheDatabaseName({
  id: story.cacheId,
  label: story.fileName
});
const assets = createAssetManagerComposition(undefined, {
  verifiedRemoteCache: {
    cacheIdentity: {id: story.cacheId, label: story.fileName, databaseName}
  }
});
const result = await assets.resolveVerifiedRemoteBinary(model, {
  load: async ({url}, {signal}) => {
    const response = await fetch(url, {signal});
    return {
      bytes: await response.arrayBuffer(),
      contentType: response.headers.get('content-type'),
      transferOwnership: true
    };
  }
});

台本 DB は tw-kamishibai-assets-v1--opening-yaml--story-0001 のような名前です。 小さな共通 catalog には、理解可能な識別情報、サイズ、日時、実行時 lease だけを記録し、 アセット本体は入れません。app shell はこれを使って台本別キャッシュを一覧・掃除・削除できます。 有効な lease がある DB は掃除しません。既定の上限は 256 MiB と、ブラウザーが報告する origin 容量の 20% のうち小さい方で、未使用の台本 DB、次に LRU のレコードから削除します。30 日間使われていない レコードは削除対象です。IndexedDB の失敗や、他の実行中台本が容量を占有して保存できない場合は、 機械判読可能な warning を返しつつ、検証済み bytes 自体はメモリーで利用できます。

app のストレージ管理には listVerifiedRemoteStoryCaches、 pruneVerifiedRemoteStoryCaches、 deleteVerifiedRemoteStoryCache を使います。実行中の所有権には renewVerifiedRemoteStoryCacheLease と releaseVerifiedRemoteStoryCacheLease を使います。DSL の retention: scene と retention: story はホスト側のメモリー保持方針です。 Asset Manager は YAML を解釈せず、これらを IndexedDB の TTL として扱いません。

複数ファイルを一括保存するtransactional bundle

バージョン 0.7.0 では、Teachable Machine Pose modelのようなself-contained assetを扱う block非公開のbinary bundle storeを追加しました。composition subpathをimportし、台本専用DBを 指定した上で、台本／source namespace、asset名、manifestのbundle integrityをすべての操作へ 結び付けます。

const assets = createAssetManagerComposition(undefined, {
  binaryBundleStore: {
    databaseName: `${story.cacheDatabaseName}--bundles-v1`
  }
});

await assets.putBinaryBundle({
  namespace: `${story.id}/${story.sourceIntegrity}`,
  name: 'RescuePose',
  integrity: pose.bundleIntegrity,
  files: [
    {path: 'model.json', size: model.size, integrity: model.integrity, bytes: model.bytes},
    {path: 'metadata.json', size: metadata.size, integrity: metadata.integrity, bytes: metadata.bytes},
    {path: 'weights.bin', size: weights.size, integrity: weights.integrity, bytes: weights.bytes}
  ]
});

const stored = await assets.getBinaryBundle({
  namespace: `${story.id}/${story.sourceIntegrity}`,
  name: 'RescuePose',
  integrity: pose.bundleIntegrity
});

putBinaryBundle は IDBTransaction.oncomplete 後にだけ完了し、入力bytesを defensive copyします。getBinaryBundle はfile path、size、canonical SHA-256を再検証して 返します。deleteBinaryBundle はdataとmetadataをatomicに削除し、 releaseBinaryStore は永続recordを消さずにstore instanceの処理を中止します。 TTL、LRU、bundle数、byte数の制限は、verified remote cacheやStandalone asset DBとは独立です。 失敗はpayload bytesを含めず、安定した ASSET_BINARY_BUNDLE_* codeで通知します。

埋め込みpackage用のsession限定backing

バージョン0.10.0では、現在のapplication package内にすでに含まれる大容量binary向けに、 別のcomposition契約を追加しました。上のpersistent bundle storeとは異なり、次回起動時に recordを再利用しません。1つの共有versioned DBを使い、全compound keyへ起動ごとのsession IDを 含め、正常disposeではそのsessionだけを削除します。verified remote cacheは変更しません。

const backing = await assets.createSessionBinaryBacking({
  policy: 'prefer',
  sessionId: crypto.randomUUID(),
  assets: embeddedManifest.assets,
  source: embeddedPackageSource,
  onFatalError(error) {
    stopRuntimeAndShowDiagnostic(error);
  }
});

const pose = await backing.get(poseAssetKey);
await backing.dispose();

disabledはIndexedDBを一度も開きません。requiredはbackingを確立できなければ 起動失敗にします。preferがwarning付きdirect readへ移れるのは、確立前にIndexedDBが unavailable、blocked、quota不足、abortとなり、partial recordを削除できた場合だけです。 descriptor、size、SHA-256の不一致は常にfail closedです。session modeでは全assetのcommitと read-back成功後にだけsourceを解放します。その後のmissing、corrupt、integrity、abort、connection closeはfatalとなり、source再読込、暗黙再書込み、mode途中変更は行いません。短いheartbeat leaseと bounded startup cleanupにより、未期限の別tabを残してcrash sessionを回収します。renderer、audio decoder、model loaderの失敗はmaterialize診断としてstorage／source errorと分離します。

同名アセットを安全に置き換える仕組み

置換機能は、起動時に固定される 2 つのフラグで段階導入します。どちらも既定値は false です。利用するプロジェクトでは、拡張機能の読み込み前に次の設定を行います。

globalThis.__TW_ASSET_MANAGER_FEATURE_FLAGS__ = {
  ENABLE_LIVE_ASSET_REPLACEMENT: true,
  ENABLE_STRICT_ASSET_KIND_REPLACEMENT: true
};

画像とテキストはすぐに更新されます。テキストは最新の本文と全スタイルを読み直し、指定された アニメーションを先頭から開始します。再生中の音声は中断せず、次回再生から新しい登録を使います。 同名の確定処理は直列に実行されるため、開始済みの確定処理は一貫した状態まで完了し、最後に開始された 成功済み登録が残ります。後から開始した無効な試行は、先行する有効な登録を取り消しません。画像では 再適用前に Asset Manager が設定した renderer skin が現在も使われているか確認します。別の衣装変更や renderer 更新があった対象は古い表示管理から外し、その新しい表示を上書きしません。strict kind を 有効にすると、公開種別 external、costume、 backdrop、sound、text 間の変更と、external の画像・音声間の 変更を拒否します。意図的に種類を変える場合だけ、先に古い登録を削除してください。

診断エラーコード

0.3.0から更新する場合: 従来の小文字種別トークンと asset registration error typeを比較しているスクリプトを更新してください。 0.4.0では、以下の大文字診断コードを返します。

利用者向けエラーは [Asset Manager][CODE] で始まり、操作名、asset/resource/actor 名、 修正ヒント、近い候補、元の例外を保持します。登録エラーの Reporter は最新のコードと関連名を返します。 同期失敗は同じ内容を二重ログせず throw し、バックグラウンドの再生・アニメーション失敗だけを 文脈付きで 1 回 console.error します。

アクターのアニメーションが進む仕組み

ASSETS と DURATIONS が時間軸を表します。画像ならアクターの見た目を変え、 音声なら再生を開始します。長さが 0 のとき、次の素材も同じ時点で開始します。

動的テキストがスプライトに届く仕組み

テキストアセットでは、サンドボックスなしの補助拡張機能を 2 つ使います。 Temporary Variables が本文とスタイルを保持し、Animated Text がスプライトやクローンに描画します。

実践的な使用例

よく使う操作

リソース [https://example.com/card.png] を
  アセット [Card] として登録する
このスプライトにアセット [Card] を表示する

リソース [costume:Hero:running] を
  アセット [HeroRunning] として登録する
このスプライトにアセット [HeroRunning] を表示する

リソース [sound:@stage:opening] を
  アセット [Opening] として登録する
アセット [Opening] を終わるまで再生する

リソース [text:Narration] を
  アセット [Narration] として登録する
テキストアセット [Narration] を [むかしむかし…] にする
[Narration] のスタイル [animation] を [typing] にする
このスプライトにアセット [Narration] を表示する

ブロックガイド

やりたいことからブロックを選ぶ

トラブルシューティング

表示・再生されないとき