Labs.lightLinking ​

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 Labs · labs · since 2.0.0 · called as session.labs.lightLinking

lightLinking(light: Part, except: Query, options?: {
  signal?: AbortSignal;
}): () => void;

The light stops reaching the parts except matches; every other part stays lit by it. light is a part of kind 'light': a collection item of kind 'light' (collection.part(key)) or a light authored in a loaded GLB. The stage's own lights are not parts and can't be linked. Point and spot lights only; direct light only; at most info().renderer.limits.linkedLights lights at once, which on every tier is at least the floor in spec section 5.15. A link past the limit links nothing, records 'unsupported-spec' and returns a no-op unlink, so that light reaches every part: compare the limit with your light count before linking. Immediate; returns the unlink. Link before the light first shows: in the transaction that creates it, on tx.collection(name).part(key) (a light staged there is linked before the commit is shown), or create it at intensity 0, link it, then raise the intensity. A light linked after it showed lights the excluded parts for at least one frame, and the link may recompile their shaders. The link holds until its unlink, its signal or the disposal of the light's collection. except is matched again at every commit, as a rule's query is (spec section 6.10, Q2), so parts a commit rebuilds, replaces or restores (a wall edit, a finish change, undo, redo, a reload) are excluded before they first show, and a render recovery keeps every link. light is a Part address: a light changed in place or replaced under the same key stays linked, and while no part has that address (its node removed, say) the link waits. No undo or rollback restores an unlink.

Default: options.signal undefined

Options ​

Through Session:

Through Tx:

Abort (signal) ​

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

A creator (collection for a new name, materials.create, on, onFrame, beforeCommit, follow, input.drag, labs.lightLinking) given a signal already aborted returns at once, already ended: a Collection or Material reading disposed: true that holds no content and no live name, or a registration that never runs and whose disposer does nothing.

It records no Problem for the abort and throws only what it would throw anyway, as the DOM's addEventListener with an aborted signal adds nothing (spec section 6.5).

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/20-Labs.lightLinking.ts):

import type { CollectionSpec, Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
declare const roomId: string;                              // the room shell's nodeId
const shelf = session.collection('shelf-lights', { role: 'scenery', signal });
const spot = (intensity: number): CollectionSpec => ({ items: [{
  key: 'spot-1', kind: 'light', at: { position: { x: 0, y: 1.9, z: 0.3 } },
  light: { kind: 'spot', target: { x: 0, y: -1, z: 0 }, coneDeg: 30, intensity },
}] });
await shelf.set(spot(0));                                  // created dark
// the spot lights the shelf, never the room's walls and floor; `signal` unlinks it
session.labs.lightLinking(shelf.part('spot-1'), { node: roomId }, { signal });
await shelf.set(spot(8));                                  // linked before it shows

Generic-API test (spec 3.1) ​