PartActions.set ​

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 PartActions · inherited by Query, Parts, Part · stable · since 2.0.0 · called as session.node(nodeId).set

set(patch: PartState, options?: C & PartWriteOptions): Promise<Report>;

Through Parts: a persistent rule in the find() block (through a nested find, one rule per match, see find). It applies to every match now and after reloads, variant switches, undo and redo, until reset with null or its owner is disposed. Rules apply in creation order, which is the order of their first calls, not of their commits; a write to an existing rule (same query and owner) merges into it in place (RFC 7396). Through one Part: a rule bound to that part's address. Outcome: one commit, look-only; not in the write queue. Timing: resolves at the commit point (after textures decode, ≤ readyTimeoutMs), or when durationMs/fadeMs end or a newer write to the rule takes them over (through a tx: 'staged' at once). Two writes to one rule both commit, in call order: the older one shows until the newer commits. For newest wins, give each write its own AbortController and abort the previous one when a new write starts (it rejects AbortError; catch it), as the second example does. No match: matched: 0 and 'target-unmatched', deferred while a scene write called before it is pending (Report.matched; spec section 6.10). Not for: per-frame motion (onFrame with Frame.pose), or a priced or saved change (select, setSceneModel). For the whole look from app state, use apply(). Nor for switching between partial looks laid over the GLB's material: a second write merges, so a field only the old look set stays; use apply({ rules }), whose block is replaced whole, or null that field in the same write (MaterialPatch, spec section 6.10, R10). Errors: rejects HoloInputError on an invalid patch (both rotations: 'rotation-twice'). No match records 'target-unmatched'; a removed part records 'handle-disposed' (a node() handle never does: its write is a rule on the model's address).

Options ​

Through Session:

Through Tx:

Refused here (typed never, so passing one fails to compile): actor, checkpoint, dryRun, expectGroup, expectRevision, origin, supersede, undo.

Abort (signal) ​

This call is a write (SignalOption.signal, the kinds of call).

A write: before the commit point it rolls back and rejects AbortError; after it, no effect, except that a running camera move stops where the last frame drew it (CameraMoveOptions).

Through a tx the commit point is the transaction's: aborting a write still loading rejects AbortError and stages nothing (catch it: unobserved, it rolls the transaction back, spec section 6.1, O6); aborting one already staged unstages it, its paths keeping the latest other write to them as after a failed savepoint (O7), and its Promise stays resolved 'staged'.

Examples ​

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/06-PartActions.set-1.ts):

import type { Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
declare const cabinetId: string;
const fronts = session.find({ node: cabinetId, tag: 'front' });   // every front part of that model
// 'none' is a value: no map at all, whatever the GLB has. The colour then shows plain.
await fronts.set({ material: { baseColor: '#2b2b2b', maps: { baseColor: 'none' } } });
// null removes your value: the GLB's or the scene model's material shows again.
await fronts.set({ material: null });

Compiled under the contract's strict settings (examples/declaration/06-PartActions.set-2.ts):

import type { Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
// newest wins: each preview aborts the one before it, which then never shows
let preview: AbortController | null = null;
export async function previewFabric(url: string): Promise<void> {
  preview?.abort();
  const mine = new AbortController();
  preview = mine;
  try {
    await session.find({ slot: 'fabric' }).set(
      { material: { maps: { baseColor: { url } } } },
      { signal: mine.signal },
    );
  } catch (error) {
    // a newer preview aborted this one
    if (!(error instanceof DOMException && error.name === 'AbortError')) throw error;
  }
}

Generic-API test (spec 3.1) ​