useAssetProgress

useAssetProgress subscribes to the AssetManager's loading progress. It does not suspend — it returns the current snapshot and re-renders when progress changes.

tsx

import { useAssetProgress } from "@carverjs/core/hooks";

Quick Start #

tsx

import { useAssetProgress } from "@carverjs/core/hooks";

function DebugOverlay() {
  const progress = useAssetProgress();

  if (progress.phase === "idle" || progress.phase === "complete") return null;

  return (
    <div style={{ position: "fixed", top: 8, right: 8, color: "#fff", fontSize: 12 }}>
      Loading: {Math.round(progress.progress * 100)}% ({progress.loaded}/{progress.total})
    </div>
  );
}

Return Value #

Returns a Readonly<LoadingProgress> object:

Field	Type	Description
`phase`	`"idle" \| "loading" \| "complete" \| "error"`	Current loading phase
`loaded`	`number`	Number of assets finished loading
`total`	`number`	Total number of assets to load
`progress`	`number`	Fraction complete (0 to 1)
`currentAsset`	`string \| null`	Key of the asset currently loading
`currentGroup`	`string \| null`	Group currently being loaded
`errors`	`AssetLoadError[]`	Errors encountered during loading

When to Use #

Use useAssetProgress when you need progress data outside the AssetLoader fallback — for example, in a persistent HUD or debug overlay that lives above the Canvas.

For progress inside the AssetLoader's fallback, use the render-prop form instead:

tsx

// Inside fallback — use the render prop (simpler)
<AssetLoader fallback={(progress) => <LoadingScreen progress={progress} />}>

// Outside fallback — use the hook
function HUD() {
  const progress = useAssetProgress();
  // ...
}

Type Definitions #

See Types for LoadingProgress and AssetLoadError.