Collection.load ​

Contract 2.0.0 · package sha256 a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e · generated from configurator-runtime.d.ts by services/onsite-scripter/scripts/build-contract-docs.mjs; edit the source, not this file.

Method of Collection · stable · since 2.0.0 · called as session.collection(name, options).load

load(url: string, placement?: Placement & {
  key?: string;
  signal?: AbortSignal;
}): Promise<Part<C>>;

Loads a glTF/GLB as one item. An engine query: resolves once the item is loaded, before its commit point, so work that awaits a load called after its transaction never waits for that transaction (O2b). It resolves with the loaded part (bounds known), hidden until its commit is shown, or a part that reads exists: false when placement.parent has no part left at its commit point (Placement.parent). Reads at the item's address (the loaded part, part(key), find({ collection, key })) see the loaded item from the resolve on, inside an open transaction's work too, until a later set(), or apply listing this collection, that sets or removes the key is called (spec section 6.1, O10). Through session the item commits on its own once loaded and is drawn from the next frame, at its placement in the GLB's look, so a rule or pose you write after the load resolves can miss that frame (one whose textures still decode always does). To show it first with your look, load it through a tx and write the look in the same transaction. Through a tx it is enlisted. Errors: rejects HoloAssetError (its problem.path the item's address, Problem.path), or HoloInputError when placement.parent hangs under the item it replaces (Placement.parent). On a disposed collection it starts nothing, records 'handle-disposed' and rejects AbortError, which fails no transaction (spec section 3.4). Aborting placement.signal before the load resolves stops its download (a download another pending load shares keeps running for that load) and rejects AbortError; after it resolves and before its commit point, the abort drops the item and nothing commits. If its commit through session fails inside the runtime, the item is dropped the same way and 'sync-failed' is recorded with its op and path (spec section 6.4). Not in the write queue (spec section 6.10, R4). A later set(), or a later apply whose collections lists this collection, commits only after this load has committed, failed or been aborted, and reconciles every item by key, so it removes loaded items its spec doesn't list. An earlier pending set() or such apply, or a transaction called before it and not yet open, ends first, so it never removes this item. A key live in this collection (a set() item or an earlier load's) is replaced by this item at its commit, in one frame, as set() changes an item in place: part(key) and rules on { collection, key } then reach the new item. An earlier pending load with that key commits first, then this one replaces it; a load that fails or is aborted leaves the old item. While several such loads have resolved and not committed, reads at the key see the latest-called one not aborted (spec section 6.1, O10). A .holo URL decrypts as in a scene-model load (spec section 8.5): through the key its file names, else the key an input gave for that file name; it never needs the asset placed first. Not for: generated content, which is set().

Default: placement.key a runtime-made key; placement.signal undefined

Abort (signal) ​

This call is neither a write, a registration, a wait nor a creator (SignalOption.signal, the kinds of call).

Cancels this call; the member's JSDoc says what an abort does.

Example ​

Imports: values (has, validate, the Holo*Error classes, the pure helpers) from @holostep-configurators/runtime-client, types from @holostep-configurators/runtime-client/contract, /math and /testing names from those entries; boot from the runtime module the root's loadRuntimeAtFloor resolves to. A type your page defines is your app's: declare it there, never import it from the package.

Compiled under the contract's strict settings (examples/declaration/07-Collection.load.ts):

import { HoloAssetError } from '@holostep-configurators/runtime-client';
import type { Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
declare const vaseUrl: string;
declare const tableTopY: number;                           // metres
try {
  // through a tx, the vase and its pose show in one frame
  await session.transaction(async (tx) => {
    const props = tx.collection('props', { role: 'scenery' });
    const vase = await props.load(vaseUrl, { key: 'vase' }); // hidden until the commit shows
    const b = vase.bounds();                               // known before it is drawn
    // one prop: pose the collection's root (an item's own values win over a rule on it, R1)
    if (b) await props.root.set({ pose: { position: { x: 0, y: tableTopY - b.min.y, z: 0 } } });
  }, { origin: 'props', signal });
} catch (error) {
  if (!(error instanceof HoloAssetError)) throw error;
  console.warn('vase failed:', error.problem.message);
}

Generic-API test (spec 3.1) ​