import type { SkyEnvironmentConfig, WorldBounds } from "../world/features.js";
import type { AvoidZone } from "../world/geometry.js";
import { type ClearanceOptions } from "../world/scatterRegion.js";
import type { TerraformSnapshot } from "../world/terraform.js";
import type { EditorAutoExposure, EditorColorGrading, EditorDocument, EditorEnvironment, EditorLightProbe } from "./types.js";
import { type IrradianceVolume } from "../render/lightProbes.js";
import type { LutCube } from "../render/postProcessing.js";
import type { LightingConfig } from "../game/playableGame.js";
/**
 * World-authoring convergence (#1018, epic #1006 Phase 4): derive the **coordinate/placement**
 * content of an `environment()` world from the scene document, so a game with an authored document
 * needs no coordinate arrays in `world.ts` — the remaining `world.ts` surface is engine tuning
 * (noise, materials, sky preset, physics). Terrain footprint follows the authored objects, ground
 * clearings come from authored spawns/POIs (`clearanceZonesFrom`), and the sculpt snapshot is the
 * document's own terrain overlay. Pure and serializable; consumers pass the result straight to
 * `environment({ terrain: terrain({ bounds }), clearings, sculpt })`.
 */
/** Options controlling how {@link environmentContentFromDocument} sizes and clears the world. */
export interface EnvironmentContentOptions extends ClearanceOptions {
    /** Padding (m) added around the authored objects' extent when sizing the terrain. Default 24. */
    padding?: number;
    /** Minimum terrain footprint so a sparse document still yields a walkable world. Default 64×64. */
    minBounds?: WorldBounds;
}
/** The coordinate/placement content of a world, derived from its scene document. */
export interface EnvironmentContent {
    /** Terrain footprint (origin-centered) sized to cover every authored object plus padding. */
    bounds: WorldBounds;
    /** Ground-flatten discs under authored spawns/plots/POIs — feed `environment({ clearings })`. */
    clearings: AvoidZone[];
    /** The document's authored sculpt snapshot, when it has one — feed `environment({ sculpt })`. */
    sculpt?: TerraformSnapshot;
    /**
     * Scene-document sky/fog/lighting (#1110), when authored. Feed into `environment({ sky: sky(sky) })`
     * so the lighting workspace owns the look without hardcoding coordinates in world.ts.
     */
    sky?: SkyEnvironmentConfig;
}
/**
 * Maps the scene document's serializable environment bag onto the runtime sky config consumed by
 * `sky()` / `environment({ sky })`. Returns `undefined` when the document has no environment field
 * so callers can fall back to a world.ts default without inventing values.
 * @capability editor-environment project document lighting onto the runtime sky descriptor
 */
export declare function skyFromDocument(doc: EditorDocument): SkyEnvironmentConfig | undefined;
/**
 * Projects a validated {@link EditorEnvironment} bag onto {@link SkyEnvironmentConfig}.
 *
 * @internal
 */
export declare function skyConfigFromEnvironment(env: EditorEnvironment): SkyEnvironmentConfig;
/**
 * The baked irradiance volumes a scene document authored, flattened for the renderer.
 * @capability light-probes read the scene document's baked irradiance volumes at runtime
 */
export declare function lightProbesFromDocument(doc: EditorDocument): readonly IrradianceVolume[];
/**
 * Bakes an authored grade into a display-space LUT cube. Contrast and saturation work around
 * luma, then each band pulls its share of the frame toward the authored swatch, scaled to the
 * pixel's own brightness so a swatch tints a band instead of painting over it. Pure and
 * deterministic, so the editor's preview and the runtime produce the same bytes.
 * @capability color-grading bake an authored grade into a display-space LUT cube
 */
export declare function lutCubeFromGrading(grading: EditorColorGrading): LutCube;
/** The renderer-facing result of a document's authored grade. */
export interface DocumentColorGrade {
    /** Display-space LUT baked from the authored bands, saturation and contrast. */
    lut?: LutCube;
    /** Authored clamped auto-exposure range, when the document set one. */
    autoExposure?: EditorAutoExposure;
}
/**
 * The colour grade a scene document authored, baked for the renderer. `undefined` when the document
 * authored no grade at all, so an ungraded game keeps its own post chain untouched. The shell folds
 * this into the post config the same way {@link lightProbesFromDocument} feeds the irradiance
 * volumes, so a game's grade is authored data rather than a pass wired in its config.
 * @capability color-grading read the scene document's authored grade at runtime
 */
export declare function colorGradeFromDocument(doc: EditorDocument): DocumentColorGrade | undefined;
/**
 * The lamps a bake should include: authored light markers plus the environment's point lights.
 * @capability light-probes fold the document's authored lamps into a probe bake
 */
export declare function authoredLightsFromDocument(doc: EditorDocument): readonly {
    position: readonly [number, number, number];
    color?: string;
    intensity?: number;
    distance?: number;
}[];
/**
 * Bakes one authored irradiance volume from its own settings and the document's lamps: sky where
 * the region is open, an authored ceiling/floor fill where it is enclosed, and the authored lamps
 * on top. Pure and deterministic, so the editor's Bake button and a script produce the same samples.
 * @capability light-probes bake a scene document's irradiance volume from its authored lamps
 */
export declare function bakeLightProbe(probe: EditorLightProbe, doc: EditorDocument): EditorLightProbe;
/** Converts authored `light` markers into the runtime lighting contract. */
export declare function lightingFromDocument(doc: EditorDocument): LightingConfig | undefined;
/**
 * The origin-centered terrain footprint that covers every authored object in a document, padded and
 * floored to `minBounds`. An empty document yields exactly `minBounds`. Because `environment()`
 * terrain is centered on the origin, the footprint is sized symmetrically to the farthest object on
 * each axis, so no authored object falls off the ground.
 * @capability world-convergence size terrain to the authored document instead of a hardcoded bounds
 */
export declare function terrainBoundsFromDocument(doc: EditorDocument, options?: EnvironmentContentOptions): WorldBounds;
/**
 * Derives a terrain-depression sculpt snapshot from the document's authored `water` volumes: each
 * water box carves a lake bed that ramps from the shoreline down to below the box's bottom face, so
 * an editor-authored pond/lake sits *in* the ground instead of floating as a sheet on top of it (and
 * ground-sampled vegetation sinks below the surface rather than growing through it). Returns
 * `undefined` when the document has no water volumes.
 * @capability world-convergence carve lake beds under authored water volumes
 */
export declare function lakebedFromWaterVolumes(doc: EditorDocument): TerraformSnapshot | undefined;
/**
 * Derives the coordinate/placement content of an `environment()` world from its scene document:
 * terrain footprint (via {@link terrainBoundsFromDocument}), ground clearings under authored
 * spawns/POIs (via `clearanceZonesFrom`), and the document's sculpt snapshot. This is the seam that
 * lets a game author its world footprint and flatten regions in the editor instead of hardcoding
 * them — the `world.ts` that consumes it carries only engine tuning.
 * @capability world-convergence derive environment coordinate content from the scene document
 */
export declare function environmentContentFromDocument(doc: EditorDocument, options?: EnvironmentContentOptions): EnvironmentContent;