Skip to content

Lighting

Generated from openspec/specs/lighting/spec.md — edit that file, not this page.

Tinkerspace renders floorplan scenes across several contexts (editor, walkthrough, catalog thumbnails, vendor/staging views), each needing correctly-lit, PBR-plausible output without every view reimplementing a rig. This capability defines the lighting behavior guaranteed in each context: a legacy fixed rig as the universal default, an opt-in physically-based day/night rig driven by real sun/moon positions, a self-contained thumbnail rig for consistent catalog imagery, and per-asset lamp emission.

A plan without an environment configuration SHALL render with the legacy fixed lighting rig (hemisphere + directional sun + ambient lights), and this SHALL be the only rig used for /preview, vendor scenes/stage views, and the sample scene regardless of their plan’s environment field.

Scenario: Plan with no environment meta uses the fixed rig

Section titled “Scenario: Plan with no environment meta uses the fixed rig”
  • WHEN a floorplan’s meta.environment is absent
  • THEN the viewer mounts defaultLightingRig() plus a static drei <Environment preset="apartment" background={false}>, and no time-of-day rig is mounted

Scenario: Vendor/staging and preview views ignore environment settings

Section titled “Scenario: Vendor/staging and preview views ignore environment settings”
  • WHEN the vendor scene/stage view or the /preview route renders a plan
  • THEN the fixed rig is used even if the underlying plan data has an environment configuration set

Requirement: Exactly one lighting rig mounted per view

Section titled “Requirement: Exactly one lighting rig mounted per view”

The system SHALL mount exactly one lighting rig (fixed or dynamic) at a time for a given viewer instance, selected solely by the presence of meta.environment on that plan.

  • WHEN a plan has no environment meta and is opened in the editor or walkthrough
  • THEN rendering output matches the pre-daylight-feature fixed-rig output byte-for-byte, since only the fixed rig is mounted

Scenario: Environment present switches to the dynamic rig

Section titled “Scenario: Environment present switches to the dynamic rig”
  • WHEN a plan’s meta.environment is set and is opened in the editor or walkthrough
  • THEN the viewer mounts <EnvironmentLighting settings={...}> instead of the fixed rig, not both

Requirement: Physically-based sun/moon positions from clock time and location

Section titled “Requirement: Physically-based sun/moon positions from clock time and location”

When a plan opts into daylight mode via FloorplanMeta.environment, the system SHALL compute real sun and moon altitude/azimuth from the configured date, time, latitude/longitude, and north offset, and SHALL drive scene lighting and the sky dome from that computed position.

  • WHEN environment.mode is "auto"
  • THEN the solar/lunar position is recomputed from the current wall-clock time (nowMs) on a periodic tick, so the rig’s lighting drifts with real time while mounted

Scenario: Manual mode uses a fixed local time

Section titled “Scenario: Manual mode uses a fixed local time”
  • WHEN environment.mode is "manual" with a given timeMinutes and dateIso
  • THEN the solar/lunar position is computed for that specific local time and date, not the current wall-clock time

Scenario: North offset reorients the sun for plan orientation

Section titled “Scenario: North offset reorients the sun for plan orientation”
  • WHEN a plan sets a non-zero northOffsetDeg in its environment settings
  • THEN the computed sun/moon direction vectors are rotated by that offset so true-north-relative daylight aligns with the plan’s local orientation

Requirement: Daylight-driven descriptor governs all dynamic lighting parameters

Section titled “Requirement: Daylight-driven descriptor governs all dynamic lighting parameters”

The system SHALL derive sun/moon intensity and color, hemisphere/ambient light palettes, sky/night background choice, star visibility, environment map intensity, and tone-mapping exposure from a single daylight factor ramped across sunrise/sunset transitions, computed by a pure, unit-tested function independent of any rendering component.

Scenario: Twilight blends lighting smoothly

Section titled “Scenario: Twilight blends lighting smoothly”
  • WHEN the sun’s altitude is within the −6°→+6° twilight band
  • THEN sun intensity/color, hemi/ambient palettes, and envMapIntensity are interpolated across that band rather than switching abruptly between day and night values
  • WHEN the sun is below the twilight band (night) and the moon is above the horizon with nonzero illuminated fraction
  • THEN the moon contributes light scaled by elevation and illumination fraction, and stars become visible

Scenario: Manual exposure override is respected

Section titled “Scenario: Manual exposure override is respected”
  • WHEN environment.exposure is explicitly set
  • THEN the descriptor uses that value instead of computing an exposure from the daylight factor

Requirement: Shadow camera fits the plan footprint in dynamic mode

Section titled “Requirement: Shadow camera fits the plan footprint in dynamic mode”

When the dynamic rig is mounted, the shadow-casting ortho camera SHALL be auto-fitted to the current plan’s footprint (corner bounds plus ceiling height) rather than using the legacy fixed extent.

Scenario: Large plan gets a wider shadow frustum

Section titled “Scenario: Large plan gets a wider shadow frustum”
  • WHEN a plan’s footprint bounds exceed the legacy fixed rig’s default shadow extent
  • THEN the dynamic rig’s shadow camera is sized to cover the actual footprint so shadows are not clipped

Requirement: Catalog thumbnails render with consistent IBL regardless of scene lighting

Section titled “Requirement: Catalog thumbnails render with consistent IBL regardless of scene lighting”

Catalog thumbnails SHALL be rendered by a self-contained, off-screen renderer using its own fixed image-based lighting setup, independent of any plan’s environment settings, so thumbnails look uniform across the catalog.

Scenario: Thumbnail ignores plan daylight settings

Section titled “Scenario: Thumbnail ignores plan daylight settings”
  • WHEN a thumbnail is generated for a catalog asset or craft composition
  • THEN the renderer builds its own hemi + directional lights plus a RoomEnvironment-derived PMREM environment map, producing the same lighting regardless of any floorplan’s environment configuration

Scenario: Thumbnail output is a capped JPEG

Section titled “Scenario: Thumbnail output is a capped JPEG”
  • WHEN the off-screen thumbnail renderer produces output
  • THEN it is encoded as JPEG (not PNG) at a quality that stays under the API’s accepted upload size cap

Requirement: Per-asset lamp emission with budgeted shadow casting

Section titled “Requirement: Per-asset lamp emission with budgeted shadow casting”

A placed scene item SHALL be able to opt into emitting its own point light (SceneItem.lightEmission), and the system SHALL cap the number of such lights that cast shadows to protect frame budget.

Scenario: Opted-in item emits a point light

Section titled “Scenario: Opted-in item emits a point light”
  • WHEN a scene item has lightEmission configured with color, intensity, and range
  • THEN a pointLight is rendered at the item’s vertical midpoint with those parameters, converted from millimeters to scene units

Scenario: Only the first four shadow-casting lamps cast shadows

Section titled “Scenario: Only the first four shadow-casting lamps cast shadows”
  • WHEN more than four scene items in a plan have lightEmission.castShadow enabled
  • THEN only the first four (in stable item order) actually render a shadow pass; the remainder emit light without casting shadows