Staging

/**
 * Environment mapping and HDRI support for realistic lighting
 * @param props - Environment configuration
 * @returns JSX element for environment setup
 */
function Environment(props: EnvironmentProps): JSX.Element;

interface EnvironmentProps {
  /** Environment preset name */
  preset?: PresetsType;
  /** Custom environment map files */
  files?: string | string[];
  /** Environment map path */
  path?: string;
  /** Skybox rendering, false */
  background?: boolean;
  /** Ground projection, false */
  ground?: boolean;
  /** Ground height, 15 */
  height?: number;
  /** Ground radius, 60 */
  radius?: number;
  /** Ground scale, 1000 */
  scale?: number;
  /** Near distance, 1 */
  near?: number;
  /** Far distance, 1000 */
  far?: number;
  /** Environment resolution, 256 */
  resolution?: number;
  /** Blur amount, 0 */
  blur?: number;
  /** Map projection, 'linear' */
  map?: 'linear' | 'cubic';
  /** Frames to render, Infinity */
  frames?: number;
  /** Environment encoding */
  encoding?: TextureEncoding;
}

type PresetsType = 
  | 'apartment' | 'city' | 'dawn' | 'forest' | 'lobby' 
  | 'night' | 'park' | 'studio' | 'sunset' | 'warehouse';

import { Environment } from '@react-three/drei';

// Environment with preset
<Environment preset="sunset" background />

// Custom HDRI environment
<Environment
  files={'/hdri/studio.hdr'}
  background
  blur={0.5}
  resolution={512}
/>

// Ground-projected environment
<Environment
  preset="city"
  ground={{
    height: 15,
    radius: 60,
    scale: 100
  }}
/>

/**
 * Contact shadows for grounded objects
 * @param props - Contact shadows configuration
 * @returns JSX element for contact shadows
 */
function ContactShadows(props: ContactShadowsProps): JSX.Element;

interface ContactShadowsProps extends Omit<ThreeElements['group'], 'ref'> {
  /** Shadow opacity, 1 */
  opacity?: number;
  /** Shadow width, 1 */
  width?: number;
  /** Shadow height, 1 */
  height?: number;
  /** Shadow blur, 1 */
  blur?: number;
  /** Shadow far distance, 10 */
  far?: number;
  /** Shadow smooth factor, 1 */
  smooth?: number;
  /** Shadow resolution, 512 */
  resolution?: number;
  /** Shadow frames, Infinity */
  frames?: number;
  /** Shadow scale [x, y], [10, 10] */
  scale?: [number, number] | number;
  /** Shadow color, black */
  color?: ReactThreeFiber.Color;
  /** Depth write, false */
  depthWrite?: boolean;
  /** Render order */
  renderOrder?: number;
}

import { ContactShadows } from '@react-three/drei';

// Basic contact shadows
<ContactShadows
  position={[0, -1, 0]}
  opacity={0.4}
  scale={10}
  blur={1}
  far={10}
/>

// Soft contact shadows
<ContactShadows
  position={[0, -0.5, 0]}
  opacity={0.6}
  width={20}
  height={20}
  blur={2.5}
  smooth={1}
  color="#000000"
/>

/**
 * Accumulative shadow mapping for high-quality soft shadows
 * @param props - Accumulative shadows configuration
 * @returns JSX element for accumulative shadows
 */
function AccumulativeShadows(props: AccumulativeShadowsProps): JSX.Element;

/**
 * Randomized light component for accumulative shadows
 * @param props - Randomized light configuration
 * @returns JSX element for randomized light
 */
function RandomizedLight(props: RandomizedLightProps): JSX.Element;

interface AccumulativeShadowsProps extends Omit<ThreeElements['group'], 'ref'> {
  /** Shadow temporal frames, 40 */
  temporal?: boolean;
  /** Shadow frames to accumulate, 40 */
  frames?: number;
  /** Shadow blend mode, 2 */
  blend?: number;
  /** Shadow limit, 20 */
  limit?: number;
  /** Shadow scale [x, y], [10, 10] */
  scale?: [number, number] | number;
  /** Shadow opacity, 1 */
  opacity?: number;
  /** Shadow alpha test, 0.65 */
  alphaTest?: number;
  /** Shadow color, black */
  color?: ReactThreeFiber.Color;
  /** Shadow color blend, 2 */
  colorBlend?: number;
  /** Shadow resolution, 1024 */
  resolution?: number;
  /** Shadow tone mapping, NoToneMapping */
  toneMapped?: boolean;
}

interface RandomizedLightProps {
  /** Light amount, 8 */
  amount?: number;
  /** Light radius, 5 */
  radius?: number;
  /** Light intensity, Math.PI */
  intensity?: number;
  /** Light ambient, 0.2 */
  ambient?: number;
  /** Light position, [5, 5, -10] */
  position?: [number, number, number];
  /** Light bias, 0.001 */
  bias?: number;
  /** Light map size, 512 */
  mapSize?: number;
  /** Light size, 10 */
  size?: number;
  /** Light near, 0.5 */
  near?: number;
  /** Light far, 500 */
  far?: number;
}

import { AccumulativeShadows, RandomizedLight } from '@react-three/drei';

// High-quality soft shadows
<AccumulativeShadows
  position={[0, -1, 0]}
  temporal
  frames={40}
  alphaTest={0.65}
  scale={10}
  limit={20}
>
  <RandomizedLight
    amount={8}
    radius={5}
    intensity={Math.PI}
    ambient={0.2}
    position={[5, 5, -10]}
  />
</AccumulativeShadows>

/**
 * Studio-style lighting setup with presets
 * @param props - Stage configuration
 * @returns JSX element for stage lighting
 */
function Stage(props: StageProps): JSX.Element;

interface StageProps extends Omit<ThreeElements['group'], 'ref'> {
  /** Stage preset, 'rembrandt' */
  preset?: 'rembrandt' | 'portrait' | 'upfront' | 'soft';
  /** Shadow system, 'contact' */
  shadows?: 'contact' | 'accumulative' | false;
  /** Shadow bias, 0.005 */
  shadowBias?: number;
  /** Main light intensity, 1 */
  intensity?: number;
  /** Environment intensity, 0.5 */
  environment?: number | false;
  /** Contact shadow props */
  contactShadow?: Partial<ContactShadowsProps>;
  /** Accumulative shadow props */
  accumulativeShadow?: Partial<AccumulativeShadowsProps>;
}

import { Stage } from '@react-three/drei';

// Studio lighting with contact shadows
<Stage
  preset="rembrandt"
  shadows="contact"
  intensity={1}
  environment={0.5}
>
  <mesh>
    <sphereGeometry />
    <meshStandardMaterial color="orange" />
  </mesh>
</Stage>

// Soft studio lighting
<Stage
  preset="soft"
  shadows="accumulative"
  intensity={0.8}
  environment={0.3}
  contactShadow={{ opacity: 0.2, blur: 2 }}
>
  {/* Your 3D content */}
</Stage>

/**
 * Procedural sky dome with atmospheric scattering
 * @param props - Sky configuration
 * @returns JSX element for sky rendering
 */
function Sky(props: SkyProps): JSX.Element;

interface SkyProps extends Omit<ThreeElements['mesh'], 'ref'> {
  /** Sky distance, 450000 */
  distance?: number;
  /** Sun position, [0, 1, 0] */
  sunPosition?: [number, number, number];
  /** Sun inclination, 0 */
  inclination?: number;
  /** Sun azimuth, 0.25 */
  azimuth?: number;
  /** Rayleigh scattering, 1 */
  rayleigh?: number;
  /** Turbidity, 10 */
  turbidity?: number;
  /** Mie coefficient, 0.005 */
  mieCoefficient?: number;
  /** Mie directional G, 0.8 */
  mieDirectionalG?: number;
}

import { Sky } from '@react-three/drei';

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

// Sunrise sky
<Sky
  distance={450000}
  inclination={0}
  azimuth={0.25}
  rayleigh={1}
  turbidity={10}
  mieCoefficient={0.005}
  mieDirectionalG={0.8}
/>

// Dynamic sun position
function DynamicSky() {
  const [sunPosition, setSunPosition] = useState([1, 1, 0]);
  
  useFrame(({ clock }) => {
    const t = clock.elapsedTime * 0.1;
    setSunPosition([Math.cos(t), Math.sin(t), 0]);
  });
  
  return <Sky sunPosition={sunPosition} />;
}

/**
 * Environment light shapes for custom lighting
 * @param props - Lightformer configuration
 * @returns JSX element for light former
 */
function Lightformer(props: LightProps): JSX.Element;

interface LightProps extends Omit<ThreeElements['mesh'], 'ref'> {
  /** Light form: 'circle' | 'ring' | 'rect' */
  form?: 'circle' | 'ring' | 'rect';
  /** Light intensity, 1 */
  intensity?: number;
  /** Light color, white */
  color?: ReactThreeFiber.Color;
  /** Light scale, 1 */
  scale?: number | [number, number, number];
  /** Target position for directional light */
  target?: [number, number, number];
  /** Ring inner radius, 0 */
  innerRadius?: number;
  /** Ring outer radius, 1 */
  outerRadius?: number;
  /** Rectangle args [width, height] */
  args?: [number, number];
}

import { Environment, Lightformer } from '@react-three/drei';

// Environment with custom light shapes
<Environment background>
  <Lightformer
    intensity={2}
    color="orange"
    position={[0, 5, -2]}
    rotation={[0, 0, Math.PI / 3]}
    form="rect"
    scale={[3, 1]}
  />
  <Lightformer
    intensity={4}
    color="red"
    position={[-5, 1, -1]}
    form="circle"
    scale={2}
  />
  <Lightformer
    intensity={1}
    color="blue"
    position={[10, 1, 0]}
    form="ring"
    innerRadius={0}
    outerRadius={1}
    scale={10}
  />
</Environment>

/**
 * Volumetric spot light with shadow support
 * @param props - Spot light configuration
 * @returns JSX element for volumetric spot light
 */
function SpotLight(props: SpotLightProps): JSX.Element;

interface SpotLightProps extends Omit<ThreeElements['spotLight'], 'ref'> {
  /** Light opacity, 1 */
  opacity?: number;
  /** Light color, white */
  color?: ReactThreeFiber.Color;
  /** Light distance, 5 */
  distance?: number;
  /** Light angle, 0.15 */
  angle?: number;
  /** Light attenuation, 5 */
  attenuation?: number;
  /** Light anglePower, 5 */
  anglePower?: number;
  /** Light intensity, 1 */
  intensity?: number;
  /** Volumetric rendering, true */
  volumetric?: boolean;
  /** Debug helper, false */
  debug?: boolean;
}

/**
 * Studio backdrop for photography setups
 * @param props - Backdrop configuration
 * @returns JSX element for backdrop
 */
function Backdrop(props: BackdropProps): JSX.Element;

interface BackdropProps extends Omit<ThreeElements['mesh'], 'ref'> {
  /** Floor props */
  floor?: number;
  /** Backdrop segments, 20 */
  segments?: number;
  /** Backdrop curve, 0.5 */
  curve?: number;
}

/**
 * Starfield background for space scenes
 * @param props - Stars configuration
 * @returns JSX element for star field
 */
function Stars(props: StarsProps): JSX.Element;

interface StarsProps extends Omit<ThreeElements['points'], 'ref'> {
  /** Star radius, 100 */
  radius?: number;
  /** Star depth, 50 */
  depth?: number;
  /** Star count, 5000 */
  count?: number;
  /** Star factor, 4 */
  factor?: number;
  /** Star saturation, 0 */
  saturation?: number;
  /** Star fade, false */
  fade?: boolean;
  /** Star speed, 1 */
  speed?: number;
}

import { Stars } from '@react-three/drei';

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

// Animated starfield
<Stars
  radius={300}
  depth={60}
  count={20000}
  factor={6}
  saturation={0}
  fade
  speed={1}
/>

function StudioScene() {
  return (
    <>
      <Environment preset="studio" background />
      <AccumulativeShadows
        position={[0, -1, 0]}
        temporal
        frames={40}
        alphaTest={0.65}
        scale={12}
      >
        <RandomizedLight amount={8} radius={4} />
      </AccumulativeShadows>
      
      {/* Your 3D content */}
      <mesh position={[0, 1, 0]}>
        <sphereGeometry />
        <meshStandardMaterial color="orange" />
      </mesh>
    </>
  );
}

function DynamicLighting() {
  const [preset, setPreset] = useState('sunset');
  const [intensity, setIntensity] = useState(1);
  
  return (
    <>
      <Environment preset={preset} background />
      <Stage
        intensity={intensity}
        environment={0.5}
        shadows="contact"
      >
        {/* Scene content */}
      </Stage>
      
      <Controls 
        onPresetChange={setPreset}
        onIntensityChange={setIntensity}
      />
    </>
  );
}

// Use lower resolution for mobile
const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);

<Environment
  preset="sunset"
  resolution={isMobile ? 256 : 1024}
  background
/>

<AccumulativeShadows
  temporal
  frames={isMobile ? 20 : 40}
  resolution={isMobile ? 512 : 1024}
>
  <RandomizedLight amount={isMobile ? 4 : 8} />
</AccumulativeShadows>