# `LightSpec`

> 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.

Type · `import type { LightSpec } from '@holostep-configurators/runtime-client/contract';` · stable · since 2.0.0 · section 7. Collections and shapes

Light intensity: KHR_lights_punctual units ×1, relative and not photometric (a sun of 3 lights
white to about 1). A `sky` is on the same scale: a sky of 3 lights a white surface facing up
to about its `sky` colour, and one facing down to about its `ground` colour. At most one light casts shadows, on every quality tier: the low tier keeps
that one shadow at 1024 px with a tighter filter (see [`ShadowSpec`](ShadowSpec.md)). `target` and positions are item-local (the
item's parent space, so they move with `attachTo`). `softnessDeg` is the outer cone half-angle
minus the inner one.
Which light casts: while a shown light item of a 'product' or 'scenery' collection asks for
`shadow`, the 'default' rig's key lights without one. Among such items the first casts,
collections in creation order and items in their spec's order; each other one lights
unshadowed and records 'unsupported-spec' at its item's path, at the commit that leaves it so.
Each commit that adds, removes, hides or changes a shadow request chooses again.

## Declaration

```ts
export type LightSpec = {
  kind: 'sun';
  direction: Point3;
  color?: ColorValue;
  intensity?: number;
  shadow?: ShadowSpec;
} | {
  kind: 'sky';
  sky: ColorValue;
  ground: ColorValue;
  intensity?: number;
} | {
  kind: 'point';
  color?: ColorValue;
  intensity?: number;
  rangeM?: number;
  shadow?: ShadowSpec;
} | {
  kind: 'spot';
  target: Point3;
  coneDeg: number;
  softnessDeg?: number;
  color?: ColorValue;
  intensity?: number;
  rangeM?: number;
  shadow?: ShadowSpec;
};
```

## Generic-API test (spec 3.1)

| Rule | Result |
| --- | --- |
| 1. Neutral name | pass: `LightSpec` names no product |
| 2. A precedent | pass: [glTF KHR_lights_punctual](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_lights_punctual) (row `K26`); [Unity LightType](https://docs.unity3d.com/ScriptReference/LightType.html) (row `K26`) |
| 3. Two apps, or labs | pass: 7 apps (ledger: app-378d190f1b, app-4f16d2f6da, app-510d750508, app-59c5b5751e, app-b362a81c85, app-ceb4eccc72, app-fc07850558) |
| 4. The cheaper fix first | decided per need in Appendix B: rows `K26` at tier stable (a member only where no rule, data, asset or app code serves the need) |