Use every project asset through one name.

Kamishibai DSL 4.0 bundle

The bundled blocks use this same reference.

In the DSL 4.0 runtime palette, find the Asset Manager member heading and click its documentation button. It opens this guide. The bundled blocks keep Asset Manager's behavior and names; the bundle only adds a member-specific namespace and icon.

Quick start

Load, register, use.

Asset Manager must run without the extension sandbox because it works with TurboWarp's renderer, audio system, and project resources.

1. Load the extension

   In TurboWarp, choose Add Extension → Custom Extension and paste:

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

   Enable Run extension without sandbox.

2. Register a resource

   Give the resource a short name that the rest of the project will use.

   register resource [https://example.com/hero.png]
     as asset [Hero]

3. Use the named asset

   The same name now works in display, sound, and animation blocks when its type fits.

   show asset [Hero] on this sprite

How it works

One registry connects every source to the right output.

Registration records the asset's type and location under the name you choose. Later blocks resolve that name and select the correct renderer, audio, or text path automatically.

Which resource identifier should I use?

How web assets and the cache work

Supplying a URL always fetches fresh data and refreshes the named cache entry. Supplying an empty resource identifier skips the network and reloads that same name from IndexedDB. The per-name generation is checked before a fetched response may update IndexedDB or the in-memory registry, so an older request that finishes late cannot overwrite the latest one.

Exact project asset locators for composition hosts

Version 0.8.0 lets composition hosts register a costume, backdrop, or sound with a structured locator. Scratch names are matched exactly, including leading and trailing spaces, ., /, :, and control characters. Structured locators also preserve the logical registration name literally by default.

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

A sound locator without target selects the Stage. The existing string resourceId form remains compatible and keeps its historical trimming and colon grammar. Embedded assets can request literal logical names with nameMode: 'literal'.

Verified remote cache for composition hosts

Version 0.6.0 adds a block-free, cache-first path for app shells and composite extensions. It is separate from the legacy name-keyed cache above. The host supplies the network loader and an expected SHA-256, byte size, and Content-Type. Asset Manager returns a valid IndexedDB hit without a network request; otherwise it downloads, verifies, and only then stores the bytes. Source URLs and credentials are not persisted.

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
    };
  }
});

Story databases use names such as tw-kamishibai-assets-v1--opening-yaml--story-0001. A small shared catalog stores only understandable identity, size, timestamps, and runtime leases—not asset binaries—and lets an app shell list, prune, or delete caches. Cleanup skips every database with an active lease. The default high-water mark is the smaller of 256 MiB and 20% of the reported origin quota; inactive story databases and least-recently-used records are removed first. Records unused for 30 days are eligible for removal. IndexedDB failures and pinned-origin budget pressure are reported as machine-readable warnings while verified bytes remain usable in memory.

Use listVerifiedRemoteStoryCaches, pruneVerifiedRemoteStoryCaches, and deleteVerifiedRemoteStoryCache for app-level storage management. Use renewVerifiedRemoteStoryCacheLease and releaseVerifiedRemoteStoryCacheLease for runtime ownership. The DSL values retention: scene and retention: story are host lifecycle policy; Asset Manager does not parse YAML or reinterpret them as IndexedDB TTL.

Transactional multi-file bundles

Version 0.7.0 adds a block-free binary bundle store for self-contained assets such as a Teachable Machine Pose model. Import the composition subpath, choose a story-specific database, and bind every operation to the story/source namespace, asset name, and 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 resolves only after IDBTransaction.oncomplete and defensively owns the supplied bytes. getBinaryBundle rechecks file paths, sizes, and canonical SHA-256 values before returning data. deleteBinaryBundle removes data and metadata atomically; releaseBinaryStore aborts that store instance without deleting persistent records. TTL, LRU, bundle-count, and byte limits are enforced independently from the verified remote cache and the Standalone asset database. Failures expose stable ASSET_BINARY_BUNDLE_* codes without payload bytes.

Session-only backing for embedded packages

Version 0.10.0 adds a separate composition contract for large binaries that already ship inside the current application package. Unlike the persistent bundle store above, session backing never reuses records at the next startup. It uses one shared versioned database, includes a fresh session ID in every compound key, and removes only that session on normal disposal. The verified remote cache remains unchanged.

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 never opens IndexedDB. required fails startup when backing cannot be established. prefer reports a warning and keeps the same source for direct reads only when IndexedDB is unavailable, blocked, out of quota, or aborted before establishment; descriptor, size, and SHA-256 failures always fail closed. Session mode releases the source only after every asset commit and read-back succeeds. A later missing, corrupt, integrity-failing, aborted, or closed-connection read is fatal and never triggers a source reread, implicit rewrite, or mode change. Short heartbeat leases and bounded startup cleanup reclaim crashed sessions without deleting an unexpired sibling tab. Renderer, audio-decoder, and model-loader failures remain separate materialization diagnostics.

How safe same-name replacement works

Replacement rollout is controlled by two startup-fixed flags. Both default to false. Define them before loading the extension bundle when a project is ready to opt in:

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

Images and text refresh immediately. Text rereads its latest body and full style, and starts a configured animation again from the beginning. Audio already playing continues; the next playback uses the replacement. Same-name commits run serially, so an active commit finishes atomically and the last-started successful registration remains afterward. A newer invalid attempt does not cancel an earlier valid one. For images, Asset Manager also verifies the renderer skin it applied before refreshing a target. A later costume or renderer change releases that stale display binding instead of being overwritten. With strict-kind replacement enabled, the public kinds external, costume, backdrop, sound, and text cannot replace one another. External image/audio changes are rejected too. Delete the old registration first when a kind change is intentional.

Diagnostic error codes

Upgrading from 0.3.0: update scripts that compare asset registration error type against the previous lowercase type tokens. Version 0.4.0 returns the uppercase diagnostic codes below.

User-facing errors begin with [Asset Manager][CODE] and retain the operation, relevant asset/resource/actor names, a correction hint, nearby candidates, and the original cause. The registration error reporters expose the latest code and its most relevant label. Synchronous failures are thrown without duplicate logging; background playback and animation failures are sent to console.error once.

How an actor animation is scheduled

ASSETS and DURATIONS describe a timeline. Images change the actor's skin; audio starts playing. A zero duration groups the next asset with the current event.

How live text reaches a sprite

Text assets use two supporting unsandboxed extensions: Temporary Variables stores the live value and style; Animated Text draws it on the destination sprite or clone.

Practical recipes

Common tasks

register resource [https://example.com/card.png]
  as asset [Card]
show asset [Card] on this sprite

register resource [costume:Hero:running]
  as asset [HeroRunning]
show asset [HeroRunning] on this sprite

register resource [sound:@stage:opening]
  as asset [Opening]
play asset [Opening] as sound until done

register resource [text:Narration]
  as asset [Narration]
set text asset [Narration] to [Once upon a time…]
set text asset [Narration] style [animation] to [typing]
show asset [Narration] on this sprite

Block guide

Choose a block by intent

Troubleshooting

When something does not appear or play