0
# Staging
1

2
Lighting, environment, and scene setup components for realistic rendering. These components provide studio-quality lighting setups, environment mapping, shadow systems, and atmospheric effects.
3

4
## Capabilities
5

6
### Environment
7

8
Environment mapping and HDRI support for realistic lighting and reflections.
9

10
```typescript { .api }
11
/**
12
 * Environment mapping and HDRI support for realistic lighting
13
 * @param props - Environment configuration
14
 * @returns JSX element for environment setup
15
 */
16
function Environment(props: EnvironmentProps): JSX.Element;
17

18
interface EnvironmentProps {
19
  /** Environment preset name */
20
  preset?: PresetsType;
21
  /** Custom environment map files */
22
  files?: string | string[];
23
  /** Environment map path */
24
  path?: string;
25
  /** Skybox rendering, false */
26
  background?: boolean;
27
  /** Ground projection, false */
28
  ground?: boolean;
29
  /** Ground height, 15 */
30
  height?: number;
31
  /** Ground radius, 60 */
32
  radius?: number;
33
  /** Ground scale, 1000 */
34
  scale?: number;
35
  /** Near distance, 1 */
36
  near?: number;
37
  /** Far distance, 1000 */
38
  far?: number;
39
  /** Environment resolution, 256 */
40
  resolution?: number;
41
  /** Blur amount, 0 */
42
  blur?: number;
43
  /** Map projection, 'linear' */
44
  map?: 'linear' | 'cubic';
45
  /** Frames to render, Infinity */
46
  frames?: number;
47
  /** Environment encoding */
48
  encoding?: TextureEncoding;
49
}
50

51
type PresetsType = 
52
  | 'apartment' | 'city' | 'dawn' | 'forest' | 'lobby' 
53
  | 'night' | 'park' | 'studio' | 'sunset' | 'warehouse';
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
import { Environment } from '@react-three/drei';
60

61
// Environment with preset
62
<Environment preset="sunset" background />
63

64
// Custom HDRI environment
65
<Environment
66
  files={'/hdri/studio.hdr'}
67
  background
68
  blur={0.5}
69
  resolution={512}
70
/>
71

72
// Ground-projected environment
73
<Environment
74
  preset="city"
75
  ground={{
76
    height: 15,
77
    radius: 60,
78
    scale: 100
79
  }}
80
/>
81
```
82

83
### ContactShadows
84

85
Contact shadows for grounded objects providing realistic shadow occlusion.
86

87
```typescript { .api }
88
/**
89
 * Contact shadows for grounded objects
90
 * @param props - Contact shadows configuration
91
 * @returns JSX element for contact shadows
92
 */
93
function ContactShadows(props: ContactShadowsProps): JSX.Element;
94

95
interface ContactShadowsProps extends Omit<ThreeElements['group'], 'ref'> {
96
  /** Shadow opacity, 1 */
97
  opacity?: number;
98
  /** Shadow width, 1 */
99
  width?: number;
100
  /** Shadow height, 1 */
101
  height?: number;
102
  /** Shadow blur, 1 */
103
  blur?: number;
104
  /** Shadow far distance, 10 */
105
  far?: number;
106
  /** Shadow smooth factor, 1 */
107
  smooth?: number;
108
  /** Shadow resolution, 512 */
109
  resolution?: number;
110
  /** Shadow frames, Infinity */
111
  frames?: number;
112
  /** Shadow scale [x, y], [10, 10] */
113
  scale?: [number, number] | number;
114
  /** Shadow color, black */
115
  color?: ReactThreeFiber.Color;
116
  /** Depth write, false */
117
  depthWrite?: boolean;
118
  /** Render order */
119
  renderOrder?: number;
120
}
121
```
122

123
**Usage Examples:**
124

125
```typescript
126
import { ContactShadows } from '@react-three/drei';
127

128
// Basic contact shadows
129
<ContactShadows
130
  position={[0, -1, 0]}
131
  opacity={0.4}
132
  scale={10}
133
  blur={1}
134
  far={10}
135
/>
136

137
// Soft contact shadows
138
<ContactShadows
139
  position={[0, -0.5, 0]}
140
  opacity={0.6}
141
  width={20}
142
  height={20}
143
  blur={2.5}
144
  smooth={1}
145
  color="#000000"
146
/>
147
```
148

149
### AccumulativeShadows
150

151
Accumulative shadow mapping for high-quality soft shadows with multiple light samples.
152

153
```typescript { .api }
154
/**
155
 * Accumulative shadow mapping for high-quality soft shadows
156
 * @param props - Accumulative shadows configuration
157
 * @returns JSX element for accumulative shadows
158
 */
159
function AccumulativeShadows(props: AccumulativeShadowsProps): JSX.Element;
160

161
/**
162
 * Randomized light component for accumulative shadows
163
 * @param props - Randomized light configuration
164
 * @returns JSX element for randomized light
165
 */
166
function RandomizedLight(props: RandomizedLightProps): JSX.Element;
167

168
interface AccumulativeShadowsProps extends Omit<ThreeElements['group'], 'ref'> {
169
  /** Shadow temporal frames, 40 */
170
  temporal?: boolean;
171
  /** Shadow frames to accumulate, 40 */
172
  frames?: number;
173
  /** Shadow blend mode, 2 */
174
  blend?: number;
175
  /** Shadow limit, 20 */
176
  limit?: number;
177
  /** Shadow scale [x, y], [10, 10] */
178
  scale?: [number, number] | number;
179
  /** Shadow opacity, 1 */
180
  opacity?: number;
181
  /** Shadow alpha test, 0.65 */
182
  alphaTest?: number;
183
  /** Shadow color, black */
184
  color?: ReactThreeFiber.Color;
185
  /** Shadow color blend, 2 */
186
  colorBlend?: number;
187
  /** Shadow resolution, 1024 */
188
  resolution?: number;
189
  /** Shadow tone mapping, NoToneMapping */
190
  toneMapped?: boolean;
191
}
192

193
interface RandomizedLightProps {
194
  /** Light amount, 8 */
195
  amount?: number;
196
  /** Light radius, 5 */
197
  radius?: number;
198
  /** Light intensity, Math.PI */
199
  intensity?: number;
200
  /** Light ambient, 0.2 */
201
  ambient?: number;
202
  /** Light position, [5, 5, -10] */
203
  position?: [number, number, number];
204
  /** Light bias, 0.001 */
205
  bias?: number;
206
  /** Light map size, 512 */
207
  mapSize?: number;
208
  /** Light size, 10 */
209
  size?: number;
210
  /** Light near, 0.5 */
211
  near?: number;
212
  /** Light far, 500 */
213
  far?: number;
214
}
215
```
216

217
**Usage Examples:**
218

219
```typescript
220
import { AccumulativeShadows, RandomizedLight } from '@react-three/drei';
221

222
// High-quality soft shadows
223
<AccumulativeShadows
224
  position={[0, -1, 0]}
225
  temporal
226
  frames={40}
227
  alphaTest={0.65}
228
  scale={10}
229
  limit={20}
230
>
231
  <RandomizedLight
232
    amount={8}
233
    radius={5}
234
    intensity={Math.PI}
235
    ambient={0.2}
236
    position={[5, 5, -10]}
237
  />
238
</AccumulativeShadows>
239
```
240

241
### Stage
242

243
Studio-style lighting setup with configurable presets and shadow systems.
244

245
```typescript { .api }
246
/**
247
 * Studio-style lighting setup with presets
248
 * @param props - Stage configuration
249
 * @returns JSX element for stage lighting
250
 */
251
function Stage(props: StageProps): JSX.Element;
252

253
interface StageProps extends Omit<ThreeElements['group'], 'ref'> {
254
  /** Stage preset, 'rembrandt' */
255
  preset?: 'rembrandt' | 'portrait' | 'upfront' | 'soft';
256
  /** Shadow system, 'contact' */
257
  shadows?: 'contact' | 'accumulative' | false;
258
  /** Shadow bias, 0.005 */
259
  shadowBias?: number;
260
  /** Main light intensity, 1 */
261
  intensity?: number;
262
  /** Environment intensity, 0.5 */
263
  environment?: number | false;
264
  /** Contact shadow props */
265
  contactShadow?: Partial<ContactShadowsProps>;
266
  /** Accumulative shadow props */
267
  accumulativeShadow?: Partial<AccumulativeShadowsProps>;
268
}
269
```
270

271
**Usage Examples:**
272

273
```typescript
274
import { Stage } from '@react-three/drei';
275

276
// Studio lighting with contact shadows
277
<Stage
278
  preset="rembrandt"
279
  shadows="contact"
280
  intensity={1}
281
  environment={0.5}
282
>
283
  <mesh>
284
    <sphereGeometry />
285
    <meshStandardMaterial color="orange" />
286
  </mesh>
287
</Stage>
288

289
// Soft studio lighting
290
<Stage
291
  preset="soft"
292
  shadows="accumulative"
293
  intensity={0.8}
294
  environment={0.3}
295
  contactShadow={{ opacity: 0.2, blur: 2 }}
296
>
297
  {/* Your 3D content */}
298
</Stage>
299
```
300

301
### Sky
302

303
Procedural sky dome rendering with sun position and atmospheric scattering.
304

305
```typescript { .api }
306
/**
307
 * Procedural sky dome with atmospheric scattering
308
 * @param props - Sky configuration
309
 * @returns JSX element for sky rendering
310
 */
311
function Sky(props: SkyProps): JSX.Element;
312

313
interface SkyProps extends Omit<ThreeElements['mesh'], 'ref'> {
314
  /** Sky distance, 450000 */
315
  distance?: number;
316
  /** Sun position, [0, 1, 0] */
317
  sunPosition?: [number, number, number];
318
  /** Sun inclination, 0 */
319
  inclination?: number;
320
  /** Sun azimuth, 0.25 */
321
  azimuth?: number;
322
  /** Rayleigh scattering, 1 */
323
  rayleigh?: number;
324
  /** Turbidity, 10 */
325
  turbidity?: number;
326
  /** Mie coefficient, 0.005 */
327
  mieCoefficient?: number;
328
  /** Mie directional G, 0.8 */
329
  mieDirectionalG?: number;
330
}
331
```
332

333
**Usage Examples:**
334

335
```typescript
336
import { Sky } from '@react-three/drei';
337

338
// Basic sky
339
<Sky distance={450000} sunPosition={[0, 1, 0]} />
340

341
// Sunrise sky
342
<Sky
343
  distance={450000}
344
  inclination={0}
345
  azimuth={0.25}
346
  rayleigh={1}
347
  turbidity={10}
348
  mieCoefficient={0.005}
349
  mieDirectionalG={0.8}
350
/>
351

352
// Dynamic sun position
353
function DynamicSky() {
354
  const [sunPosition, setSunPosition] = useState([1, 1, 0]);
355
  
356
  useFrame(({ clock }) => {
357
    const t = clock.elapsedTime * 0.1;
358
    setSunPosition([Math.cos(t), Math.sin(t), 0]);
359
  });
360
  
361
  return <Sky sunPosition={sunPosition} />;
362
}
363
```
364

365
### Lightformer
366

367
Environment light shapes for creating custom lighting setups within environments.
368

369
```typescript { .api }
370
/**
371
 * Environment light shapes for custom lighting
372
 * @param props - Lightformer configuration
373
 * @returns JSX element for light former
374
 */
375
function Lightformer(props: LightProps): JSX.Element;
376

377
interface LightProps extends Omit<ThreeElements['mesh'], 'ref'> {
378
  /** Light form: 'circle' | 'ring' | 'rect' */
379
  form?: 'circle' | 'ring' | 'rect';
380
  /** Light intensity, 1 */
381
  intensity?: number;
382
  /** Light color, white */
383
  color?: ReactThreeFiber.Color;
384
  /** Light scale, 1 */
385
  scale?: number | [number, number, number];
386
  /** Target position for directional light */
387
  target?: [number, number, number];
388
  /** Ring inner radius, 0 */
389
  innerRadius?: number;
390
  /** Ring outer radius, 1 */
391
  outerRadius?: number;
392
  /** Rectangle args [width, height] */
393
  args?: [number, number];
394
}
395
```
396

397
**Usage Examples:**
398

399
```typescript
400
import { Environment, Lightformer } from '@react-three/drei';
401

402
// Environment with custom light shapes
403
<Environment background>
404
  <Lightformer
405
    intensity={2}
406
    color="orange"
407
    position={[0, 5, -2]}
408
    rotation={[0, 0, Math.PI / 3]}
409
    form="rect"
410
    scale={[3, 1]}
411
  />
412
  <Lightformer
413
    intensity={4}
414
    color="red"
415
    position={[-5, 1, -1]}
416
    form="circle"
417
    scale={2}
418
  />
419
  <Lightformer
420
    intensity={1}
421
    color="blue"
422
    position={[10, 1, 0]}
423
    form="ring"
424
    innerRadius={0}
425
    outerRadius={1}
426
    scale={10}
427
  />
428
</Environment>
429
```
430

431
### SpotLight
432

433
Volumetric spot light with shadow support and configurable cone parameters.
434

435
```typescript { .api }
436
/**
437
 * Volumetric spot light with shadow support
438
 * @param props - Spot light configuration
439
 * @returns JSX element for volumetric spot light
440
 */
441
function SpotLight(props: SpotLightProps): JSX.Element;
442

443
interface SpotLightProps extends Omit<ThreeElements['spotLight'], 'ref'> {
444
  /** Light opacity, 1 */
445
  opacity?: number;
446
  /** Light color, white */
447
  color?: ReactThreeFiber.Color;
448
  /** Light distance, 5 */
449
  distance?: number;
450
  /** Light angle, 0.15 */
451
  angle?: number;
452
  /** Light attenuation, 5 */
453
  attenuation?: number;
454
  /** Light anglePower, 5 */
455
  anglePower?: number;
456
  /** Light intensity, 1 */
457
  intensity?: number;
458
  /** Volumetric rendering, true */
459
  volumetric?: boolean;
460
  /** Debug helper, false */
461
  debug?: boolean;
462
}
463
```
464

465
### Backdrop
466

467
Studio backdrop for photography-style lighting setups.
468

469
```typescript { .api }
470
/**
471
 * Studio backdrop for photography setups
472
 * @param props - Backdrop configuration
473
 * @returns JSX element for backdrop
474
 */
475
function Backdrop(props: BackdropProps): JSX.Element;
476

477
interface BackdropProps extends Omit<ThreeElements['mesh'], 'ref'> {
478
  /** Floor props */
479
  floor?: number;
480
  /** Backdrop segments, 20 */
481
  segments?: number;
482
  /** Backdrop curve, 0.5 */
483
  curve?: number;
484
}
485
```
486

487
### Stars
488

489
Starfield background for space scenes and atmospheric effects.
490

491
```typescript { .api }
492
/**
493
 * Starfield background for space scenes
494
 * @param props - Stars configuration
495
 * @returns JSX element for star field
496
 */
497
function Stars(props: StarsProps): JSX.Element;
498

499
interface StarsProps extends Omit<ThreeElements['points'], 'ref'> {
500
  /** Star radius, 100 */
501
  radius?: number;
502
  /** Star depth, 50 */
503
  depth?: number;
504
  /** Star count, 5000 */
505
  count?: number;
506
  /** Star factor, 4 */
507
  factor?: number;
508
  /** Star saturation, 0 */
509
  saturation?: number;
510
  /** Star fade, false */
511
  fade?: boolean;
512
  /** Star speed, 1 */
513
  speed?: number;
514
}
515
```
516

517
**Usage Examples:**
518

519
```typescript
520
import { Stars } from '@react-three/drei';
521

522
// Basic starfield
523
<Stars radius={100} depth={50} count={5000} factor={4} />
524

525
// Animated starfield
526
<Stars
527
  radius={300}
528
  depth={60}
529
  count={20000}
530
  factor={6}
531
  saturation={0}
532
  fade
533
  speed={1}
534
/>
535
```
536

537
## Integration Patterns
538

539
### Complete Scene Setup
540

541
```typescript
542
function StudioScene() {
543
  return (
544
    <>
545
      <Environment preset="studio" background />
546
      <AccumulativeShadows
547
        position={[0, -1, 0]}
548
        temporal
549
        frames={40}
550
        alphaTest={0.65}
551
        scale={12}
552
      >
553
        <RandomizedLight amount={8} radius={4} />
554
      </AccumulativeShadows>
555
      
556
      {/* Your 3D content */}
557
      <mesh position={[0, 1, 0]}>
558
        <sphereGeometry />
559
        <meshStandardMaterial color="orange" />
560
      </mesh>
561
    </>
562
  );
563
}
564
```
565

566
### Dynamic Lighting
567

568
```typescript
569
function DynamicLighting() {
570
  const [preset, setPreset] = useState('sunset');
571
  const [intensity, setIntensity] = useState(1);
572
  
573
  return (
574
    <>
575
      <Environment preset={preset} background />
576
      <Stage
577
        intensity={intensity}
578
        environment={0.5}
579
        shadows="contact"
580
      >
581
        {/* Scene content */}
582
      </Stage>
583
      
584
      <Controls 
585
        onPresetChange={setPreset}
586
        onIntensityChange={setIntensity}
587
      />
588
    </>
589
  );
590
}
591
```
592

593
### Performance Optimization
594

595
```typescript
596
// Use lower resolution for mobile
597
const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);
598

599
<Environment
600
  preset="sunset"
601
  resolution={isMobile ? 256 : 1024}
602
  background
603
/>
604

605
<AccumulativeShadows
606
  temporal
607
  frames={isMobile ? 20 : 40}
608
  resolution={isMobile ? 512 : 1024}
609
>
610
  <RandomizedLight amount={isMobile ? 4 : 8} />
611
</AccumulativeShadows>
612
```