# `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`](Collection.md) · stable · since 2.0.0 · called as `session.collection(name, options).load`

```ts
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`](Placement.parent.md)). Reads at the item's address (the loaded part, `part(key)`, [`find({ collection, key })`](Writer.find.md)) see the loaded item from
the resolve on, inside an open transaction's `work` too, until a later `set()`, or [`apply`](Writer.apply.md) 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`](Problem.path.md)), or HoloInputError when `placement.parent` hangs under the item it replaces ([`Placement.parent`](Placement.parent.md)). 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`](Writer.apply.md) 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`](Writer.apply.md), or a transaction called before it and not
yet open, ends first, so it never removes this item.
A [`key`](Part.key.md) 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](../read-this-first.md#conventions)).

> 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`):

```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)

| Rule | Result |
| --- | --- |
| 1. Neutral name | pass: `load` names no product |
| 2. A precedent | pass: [Unity GameObject.Find](https://docs.unity3d.com/ScriptReference/GameObject.Find.html) (row `K7`); [DOM Document.querySelectorAll](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll) (row `K7`); [Unity Object.Instantiate](https://docs.unity3d.com/ScriptReference/Object.Instantiate.html) (row `K8`); [glTF 2.0 alpha coverage (BLEND)](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#alpha-coverage) (row `K8`) |
| 3. Two apps, or labs | pass: 8 apps (ledger: app-4f16d2f6da, app-59c5b5751e, app-b362a81c85, app-b4ae2fce25, app-ceb4eccc72, app-ddfb017681, app-fc07850558, app-fc306ec3dc; fleet cross-check: app-fc306ec3dc) |
| 4. The cheaper fix first | decided per need in Appendix B: rows `K7`, `K8` at tier labs, stable (a member only where no rule, data, asset or app code serves the need) |