incanto 0.1.0

package/dist/env.d.ts

@@ -0,0 +1,430 @@
+import { a as Rng, i as SceneJson, n as NodeJson, s as JsonObject } from "./schema-CcoWb32N.js";
+
+//#region src/env/arena.d.ts
+/** Valid `generateArena` themes — drives the catalog options AND validation. */
+declare const ARENA_THEMES: readonly ["boxes", "ruins", "garden"];
+type ArenaTheme = (typeof ARENA_THEMES)[number];
+interface ArenaOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /** Floor extent along x, meters (default 30). */
+  width?: number;
+  /** Floor extent along z, meters (default 30). */
+  depth?: number;
+  /** Perimeter wall height, meters (default 3). */
+  wallHeight?: number;
+  /** Box obstacles strewn inside the walls (default 8). */
+  obstacles?: number;
+  /**
+  * Visual theme over the same floor/walls/obstacles skeleton:
+  * 'boxes' (default, colorful crates), 'ruins' (stone palette, broken
+  * colonnade rows), 'garden' (hedge walls, grass patches, a center pool).
+  */
+  theme?: ArenaTheme;
+}
+/**
+* A 3D FPS stage: floor + 4 perimeter walls + N obstacles (every body a
+* StaticBody3D box collider with a MeshInstance3D 'Skin' child — the
+* canonical visible+collidable composition) + sun/fill/lamp lighting, dressed
+* by `theme`: 'boxes' strews colorful crates, 'ruins' lays broken stone
+* colonnade rows, 'garden' grows hedge blocks plus Foliage3D grass patches
+* and a Water3D pool at the center.
+*/
+declare function generateArena(opts: ArenaOptions): NodeJson;
+//#endregion
+//#region src/env/catalog.d.ts
+interface GeneratorParamMeta {
+  type: "number" | "string" | "boolean";
+  default: number | string | boolean;
+  min?: number;
+  max?: number;
+  options?: string[];
+}
+interface GeneratorMeta {
+  description: string;
+  dimension: "2d" | "3d";
+  params: Record<string, GeneratorParamMeta>;
+}
+/**
+* The generator catalog: name → description, dimension and CLI-typed params.
+* Drives the `incanto-env` CLI (`--list`, generic `--<param>` flags) and any
+* editor UI, so help text can never drift from the code. `seed` is implicit
+* — every generator requires it.
+*
+* The 3D set is EXACTLY arena/terrain/maze — themes do the heavy lifting
+* (the old meadow/forest/island/rocks/clouds generators became terrain/arena
+* themes; their functions live on in the library, deprecated). Tuple-typed
+* library options (scatter items, platforms2d ranges) and the voxel-world
+* `generateVoxelTerrain` stay library-only and are not listed.
+*/
+declare const GENERATORS: Record<string, GeneratorMeta>;
+type GeneratorOpts = Record<string, unknown> & {
+  seed: number;
+};
+/**
+* Invoke any catalog generator uniformly by name (what the CLI and editor
+* call). Unknown names are a hard error listing the valid ones; option
+* validation stays with each generator.
+*/
+declare function runGenerator(name: string, opts: GeneratorOpts): NodeJson;
+//#endregion
+//#region src/env/clouds.d.ts
+interface CloudsOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /** Clouds (puff groups) in the sky (default 8). */
+  count?: number;
+  /** Sky area centered on the origin — a number is square, or [x, z] meters (default [60, 60]). */
+  area?: number | [number, number];
+  /** Base altitude, meters — each cloud floats ±3 around it (default 18). */
+  altitude?: number;
+}
+/**
+* Soft sky clouds: each a Node3D group of 3–5 overlapping white sphere puffs
+* stretched wide and squashed flat, floating around `altitude`. Pure visuals
+* — no colliders, no physics.
+*
+* @deprecated The island terrain theme ships its own cloud layer — use
+* `runGenerator('terrain', { seed, theme: 'island' })` for whole worlds.
+* Kept for custom library compositions (other themes, custom skies).
+*/
+declare function generateClouds(opts: CloudsOptions): NodeJson;
+//#endregion
+//#region src/env/dungeon-2d.d.ts
+interface Dungeon2DOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /** Rooms to place — fewer land if the map is crowded (default 5). */
+  rooms?: number;
+  /** Map extent in px — a number is square, or [width, height] (default [960, 720]). */
+  size?: number | [number, number];
+}
+/**
+* A roguelike 2D dungeon: rectangular rooms connected by 1-tile L-corridors
+* (horizontal leg, then vertical), rasterized onto a 32px tile grid. Floors
+* are ColorRect2D rects ('Room1'…, 'Corridor1H'/'Corridor1V'…); every
+* non-floor tile touching a floor tile becomes a StaticBody2D wall segment
+* (merged into runs along x) with a ColorRect2D skin. Centered on the origin.
+*/
+declare function generateDungeon2D(opts: Dungeon2DOptions): NodeJson;
+//#endregion
+//#region src/env/forest.d.ts
+interface ForestOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /** Square ground extent, meters (default 48). */
+  size?: number;
+  /** Trees to plant — fewer land when the clearing rejects spots (default 40). */
+  trees?: number;
+  /** Radius of the tree-free central clearing, meters; 0 disables (default 6). */
+  clearing?: number;
+}
+/**
+* A primitive-tree forest: a ground slab planted with StaticBody3D
+* trunk+canopy trees whose density falls off into an optional central
+* clearing (hard-empty inside `clearing`, ramping to full density at 1.5×),
+* softened by a few Foliage3D grass patches, lit by sun/fill.
+*
+* @deprecated Use `runGenerator('terrain', { seed, theme: 'forest' })` — the
+* Terrain3D forest (dense mixed Tree3D groves, central clearing, grass
+* patches, heightfield collider) replaced this flat-slab version in the
+* catalog.
+*/
+declare function generateForest(opts: ForestOptions): NodeJson;
+//#endregion
+//#region src/env/insert.d.ts
+/**
+* PURE insertion: a NEW scene JSON with `node` appended under the node at
+* `at` (default: the scene root). Neither input is mutated.
+*
+* `at` is the '/'-joined chain of node NAMES from the root, ROOT INCLUDED —
+* 'Root/Level' targets the root's child 'Level' (NodePath semantics applied
+* to the JSON tree). A missing path is a hard NODE_NOT_FOUND listing what IS
+* there. Sibling name clashes are fine — the loader uniquifies on load.
+*/
+declare function insertIntoScene(scene: SceneJson, node: NodeJson, at?: string): SceneJson;
+//#endregion
+//#region src/env/island.d.ts
+interface IslandOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /** Island radius in blocks (default 16). */
+  radius?: number;
+  /** Peak height in blocks (default 8). */
+  height?: number;
+  /** Surround the shore with a Water3D ring (default true). */
+  water?: boolean;
+}
+/**
+* A voxel island: the terrain value noise shaped by a radial dome falloff —
+* tall grassy center, sandy shore where columns dip to the waterline, bedrock
+* base — with an optional Water3D ring lapping the beach and sun/fill lights.
+* Colliders stay the game's job (chunk trimeshes near the player — see the
+* minecraft template).
+*
+* @deprecated Use `runGenerator('terrain', { seed, theme: 'island' })` — the
+* Terrain3D island (smooth heightfield, splatted beach/cliffs/snow, computed
+* drownable sea level, heightfield collider) replaced this in the catalog.
+* Kept for voxel-world library users.
+*/
+declare function generateIsland(opts: IslandOptions): NodeJson;
+//#endregion
+//#region src/env/maze.d.ts
+/** Valid `generateMaze` themes — drives the catalog options AND validation. */
+declare const MAZE_THEMES: readonly ["stone", "hedge", "canyon"];
+type MazeTheme = (typeof MAZE_THEMES)[number];
+interface MazeOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /** Corridor cells along x (default 8). */
+  width?: number;
+  /** Corridor cells along z (default 8). */
+  depth?: number;
+  /** Tile size, meters — corridors and walls are one tile wide (default 2). */
+  cellSize?: number;
+  /** Wall height, meters (default 2.5). */
+  wallHeight?: number;
+  /**
+  * Visual theme over the same carved layout: 'stone' (default, brick walls +
+  * stone floor + coping caps), 'hedge' (foliage walls with grass tops +
+  * lawn floor), 'canyon' (sandstone walls + sand floor + rim boulders).
+  */
+  theme?: MazeTheme;
+}
+/**
+* The environment header that matches a maze theme — the terrainEnvironment
+* contract (spread into the scene's `environment`; scene keys layer on top),
+* tuned MOODY at corridor level: low hazy sun, sub-1 exposure, dim ambient
+* and a fog window that closes in on the walls. 'stone' is the coolest and
+* foggiest (dungeon courtyard), 'hedge' an overcast garden, 'canyon' a warm
+* dusk. `span` is the maze's world extent ((2·width+1)·cellSize, default 34).
+*/
+declare function mazeEnvironment(theme: MazeTheme, span?: number): JsonObject;
+/**
+* A 3D maze: recursive-backtracker corridors (entrance on the west edge,
+* exit on the east) as chunky one-tile-thick StaticBody3D walls over a
+* textured floor slab, plus sun/fill lights. Consecutive wall tiles merge
+* into single boxes along x to keep the node count down. Same algorithm as
+* `generateMaze2D`; `theme` swaps the materials and dressing over the
+* IDENTICAL carved layout — every theme gets textured walls/floor (worldspace
+* brick/grass/sandstone tiling), junction pillars, and a pillar-framed
+* entrance/exit with a tinted path tile; 'stone' adds coping caps on every
+* run, 'hedge' grows grass strips along the wall tops + corridor patches,
+* 'canyon' perches boulders on the rim. Deterministic from `seed`.
+*/
+declare function generateMaze(opts: MazeOptions): NodeJson;
+//#endregion
+//#region src/env/maze-2d.d.ts
+interface Maze2DOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /** Corridor cells along x (default 10). */
+  cols?: number;
+  /** Corridor cells along y (default 8). */
+  rows?: number;
+  /** Tile size in px — corridors and walls are one tile wide (default 64). */
+  cellPx?: number;
+}
+/**
+* The 2D twin of `generateMaze` — the SAME recursive-backtracker grid
+* (entrance west, exit east) emitted as a ColorRect2D floor backdrop plus
+* StaticBody2D wall bodies with ColorRect2D skins (px, y-down, centered on
+* the origin). Consecutive wall tiles merge into single bodies along x.
+*/
+declare function generateMaze2D(opts: Maze2DOptions): NodeJson;
+//#endregion
+//#region src/env/maze-grid.d.ts
+interface MazeGrid {
+  /** Corridor cells per axis. */
+  cols: number;
+  rows: number;
+  /** (2·rows+1) × (2·cols+1) booleans indexed [z][x] — true = passage. */
+  cells: boolean[][];
+}
+/**
+* Recursive-backtracker maze (the classic): carve from cell (0,0), always
+* advancing to a random unvisited neighbor and knocking down the wall
+* between, backtracking when stuck — every cell ends up reachable. Then the
+* entrance (west wall of the first cell) and exit (east wall of the last)
+* are opened. Shared by `generateMaze` (3D) and `generateMaze2D`; games can
+* BFS over `cells` for pathing or item placement.
+*/
+declare function carveMaze(rng: Rng, cols: number, rows: number): MazeGrid;
+//#endregion
+//#region src/env/meadow.d.ts
+interface MeadowOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /** Square ground extent, meters (default 40). */
+  size?: number;
+  /** Field mix — 'grass' (default), 'flowers', or 'mixed' (grass + a flower patch). */
+  foliage?: "grass" | "flowers" | "mixed";
+  /** Boulders strewn across the ground (default 6). */
+  rocks?: number;
+  /** Primitive trees around the field (default 4). */
+  trees?: number;
+}
+/**
+* A grass field (잔디밭): a StaticBody3D ground slab carpeted with an
+* instanced Foliage3D field, plus scattered boulders, primitive trees and
+* sun/fill lighting. 'mixed' lays the full grass field with a smaller flower
+* patch on top.
+*
+* @deprecated Use `runGenerator('terrain', { seed, theme: 'meadow' })` — the
+* rolling Terrain3D meadow (blade carpets, broadleaf groves, rocks, a real
+* heightfield collider) replaced this flat-slab version in the catalog.
+*/
+declare function generateMeadow(opts: MeadowOptions): NodeJson;
+//#endregion
+//#region src/env/platforms-2d.d.ts
+interface Platforms2DOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /** Platforms in the course (default 10). */
+  count?: number;
+  /** Platform width range in px (default [80, 160]). */
+  width?: [number, number];
+  /** Edge-to-edge horizontal gap range in px (default [40, 120]). */
+  gapX?: [number, number];
+  /** Vertical step range in px, y-DOWN: negative climbs (default [-80, 40]). */
+  stepY?: [number, number];
+  /** First platform center [x, y] in px (default [0, 300]). */
+  start?: [number, number];
+}
+/**
+* A left-to-right 2D platform course: StaticBody2D rect colliders with
+* ColorRect2D 'Skin' children. Spacing is caller-tunable — keep `gapX` and
+* `stepY` inside your character's jump arc for a reachable course (px,
+* y-down: world gravity pulls +y, so negative `stepY` steps UP).
+*/
+declare function generatePlatforms2D(opts: Platforms2DOptions): NodeJson;
+//#endregion
+//#region src/env/rocks.d.ts
+interface RocksOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /** Boulders to place (default 12). */
+  count?: number;
+  /** Ground area centered on the origin — a number is square, or [x, z] meters (default [24, 24]). */
+  area?: number | [number, number];
+  /** Boulder radius range, meters (default [0.4, 1.6]). */
+  sizeRange?: [number, number];
+}
+/**
+* Clustered boulders: a few cluster anchors with rocks scattered tightly
+* around them — squashed, gray-jittered MeshInstance3D spheres (visual props,
+* no colliders; wrap one in a StaticBody3D yourself if it must block).
+*
+* @deprecated The terrain themes scatter their own rocks (alpine snow-band
+* boulders, desert/plains/meadow clusters) — use `runGenerator('terrain',
+* { seed, theme })` for whole worlds. Kept for custom library compositions.
+*/
+declare function generateRocks(opts: RocksOptions): NodeJson;
+//#endregion
+//#region src/env/scatter.d.ts
+interface ScatterItem {
+  /** Registered node type of the template ('MeshInstance3D', 'ModelInstance3D', …). */
+  type: string;
+  /** Template props — position x/z, rotation and scale are overwritten per instance. */
+  props?: JsonObject;
+  /** Relative pick probability (default 1). */
+  weight?: number;
+}
+interface ScatterOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /** Instances to place (default 20). */
+  count?: number;
+  /** Ground area [x extent, z extent] centered on the origin (default [20, 20]). */
+  area?: [number, number];
+  /** WHAT to scatter — weighted node JSON templates (at least one). */
+  items: ScatterItem[];
+}
+/**
+* Scatter N instances of caller-provided node templates over an XZ area:
+* random position, y-rotation, and uniform scale jitter (multiplied onto the
+* template's own scale). The template's `position[1]` survives as the ground
+* offset. Library-only — the items make it too open-ended for CLI flags.
+*/
+declare function generateScatter(opts: ScatterOptions): NodeJson;
+//#endregion
+//#region src/env/terrain.d.ts
+/** Valid `generateTerrain` themes — drives the catalog options AND validation. */
+declare const TERRAIN_GENERATOR_THEMES: readonly ["island", "alpine", "plains", "desert", "meadow", "forest", "savanna", "snow", "wetland", "volcanic"];
+/** A `generateTerrain` theme (the GENERATOR'S knob — Terrain3D has its own). */
+type TerrainTheme = (typeof TERRAIN_GENERATOR_THEMES)[number];
+interface TerrainOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /**
+  * One knob, big payoff: which world to dress the heightfield as.
+  * 'island' (default) | 'alpine' | 'plains' | 'desert' | 'meadow' | 'forest'
+  * | 'savanna' | 'snow' | 'wetland' | 'volcanic'.
+  */
+  theme?: TerrainTheme;
+  /** Square extent in meters (default 200). */
+  size?: number;
+  /**
+  * Terrain3D height SCALE (realized heights land at ~2–8× this).
+  * 0 or undefined = the theme's default — island 4.5, alpine 8, plains 4,
+  * desert 5, meadow 1.2, forest 2.5. Islands additionally auto-fit DOWN so
+  * a drownable sea level always exists (see the two-sided rim constraint).
+  */
+  maxHeight?: number;
+  /**
+  * Add a calm valley lake to non-island themes (default false). The island
+  * theme ALWAYS ships its sea — without it the edge-wrap skirt is bare cliff.
+  */
+  water?: boolean;
+}
+/**
+* The environment header that matches a generator theme — sky, horizon fog
+* and shadows composed for the same world `generateTerrain` emits (fog
+* distances scale with `size`). Spread it into the scene's `environment`;
+* scene-specific keys (ambient, background fallback) layer on top.
+*/
+declare function terrainEnvironment(theme: TerrainTheme, size?: number): JsonObject;
+/**
+* A complete heightfield world from one seed + one theme: the canonical
+* physics recipe (`StaticBody3D{heightfield}` with a `Terrain3D` child) plus
+* theme dressing placed ON the surface via the same heightmap the node will
+* build at runtime — trees probe `heightAt` and reject steep/sand/snow cells,
+* the island sea level is COMPUTED from border probes (two-sided constraint:
+* above every rim cliff top, inside the sand band), rocks/foliage sit at
+* their sampled ground height. Sun/fill lights round out every theme.
+*
+* Replaces the old voxel terrain in the catalog — that lives on as the
+* library-only `generateVoxelTerrain` for minecraft-style block worlds.
+*/
+declare function generateTerrain(opts: TerrainOptions): NodeJson;
+//#endregion
+//#region src/env/voxel-terrain.d.ts
+interface VoxelTerrainOptions {
+  /** Determinism seed — the same seed always emits the same JSON. */
+  seed: number;
+  /** Square extent in blocks (default 32). */
+  size?: number;
+  /** Max column height in blocks (default 8). */
+  height?: number;
+  /** Add a Water3D plane at ~35% of the max height (default false). */
+  water?: boolean;
+}
+/**
+* A voxel heightfield for minecraft-style worlds: smooth-ish value noise (a
+* seeded lattice, bilinearly interpolated with a smoothstep fade) baked into
+* a VoxelGrid3D `voxels` prop as [x,y,z,tile] tuples — solid columns of
+* bedrock/dirt/grass centered on the origin. Colliders stay the game's job
+* (chunk trimeshes near the player — see the minecraft template).
+*
+* Library-only by design: the `terrain` catalog generator emits a smooth
+* Terrain3D heightfield instead — reach for THIS when blocks are the point
+* (digging, building, VoxelGrid3D worlds).
+*/
+declare function generateVoxelTerrain(opts: VoxelTerrainOptions): NodeJson;
+/**
+* Value noise over [0,size)² in [0,1] — random lattice + smooth interpolation.
+* Shared with `generateIsland` (which shapes it with a radial falloff).
+*/
+declare function makeValueNoise(rng: Rng, size: number): (x: number, z: number) => number;
+//#endregion
+export { ARENA_THEMES, type ArenaOptions, type ArenaTheme, type CloudsOptions, type Dungeon2DOptions, type ForestOptions, GENERATORS, type GeneratorMeta, type GeneratorParamMeta, type IslandOptions, MAZE_THEMES, type Maze2DOptions, type MazeGrid, type MazeOptions, type MazeTheme, type MeadowOptions, type Platforms2DOptions, type RocksOptions, type ScatterItem, type ScatterOptions, TERRAIN_GENERATOR_THEMES, type TerrainOptions, type TerrainTheme, type VoxelTerrainOptions, carveMaze, generateArena, generateClouds, generateDungeon2D, generateForest, generateIsland, generateMaze, generateMaze2D, generateMeadow, generatePlatforms2D, generateRocks, generateScatter, generateTerrain, generateVoxelTerrain, insertIntoScene, makeValueNoise, mazeEnvironment, runGenerator, terrainEnvironment };