lecodes-sdk 0.20.2 → 1.1.0

package/dist/types/gl/vehicle/Wheel.d.ts

@@ -0,0 +1,147 @@
+import { Aspect } from "../../core/Aspect";
+import type { FieldMeta } from "../../core/fields";
+import { Vec3 } from "../../math/vec";
+import { Node } from "../Node";
+/** Floats `vehicleGetState` writes before the per-wheel block: speed, rpm, contacts, vx, vy, vz, wx, wy, wz,
+ *  steerDeg, steerTorque. */
+export declare const STATE_HEADER = 11;
+/** Floats per wheel: contact, slip, slipAngle, suspensionLength, steerDeg, spin, fLat, fLong, vLat, vSlip, load. */
+export declare const WHEEL_STATE = 11;
+/** Fully compressed = this fraction of `travel` (the engine's one suspension constant, mirrored here
+ *  so `compression` and the resting-height maths read the same number). */
+export declare const SUSPENSION_MIN_FRACTION = 0.4;
+/** A point on a curve — a tire's friction over slip, an engine's torque over rpm. */
+export type Point = {
+    x: number;
+    y: number;
+};
+export interface WheelSuspension {
+    /** Total travel in metres, full droop to fully compressed (default 0.4). */
+    travel?: number;
+    /** Spring frequency in Hz — bigger is stiffer (default 1.4; a race car ~2.5, a truck ~1). It also
+     *  sets the ride-height sag, and the sag is how far the wheel can still extend DOWN. */
+    stiffness?: number;
+    /** Damping ratio 0..1 (default 0.5). Low values pogo. */
+    damping?: number;
+}
+/**
+ * A tire, as the engine takes it: two friction curves and two numbers. `Tire.road()` and the other
+ * presets are starting points — copy one and edit, or `Tire.scale()` it.
+ */
+export interface Tire {
+    /** Lateral friction over slip ANGLE: `{ x: degrees, y: friction }`, x ascending. Friction is the
+     *  coefficient the tire's load is multiplied by; the last value holds to 90°. The grip a wheel
+     *  actually gets is combined with the ground it stands on as `sqrt(tire × groundFriction)`, and a
+     *  body's friction defaults to 0.6 — a road a car should really corner on wants `Physics { friction: 1 }`. */
+    side: Point[];
+    /** Longitudinal friction over slip RATIO: `{ x: ratio, y: friction }` (0 = rolling in sync, 1 =
+     *  locked or spinning freely). */
+    forward: Point[];
+    /** The longitudinal impulse clamp as a multiple of `friction × load` — for DRIVE only; a braking
+     *  wheel is always clamped at the physical limit (or a locked rear would stop the car at a full g
+     *  and kill every handbrake turn). `1` is the physical tire; `road`'s 10 is Jolt's own sample
+     *  value (it keeps a driven wheel from ever spinning up). Anything a friction circle should bite
+     *  on wants this near 1. */
+    traction?: number;
+    /** Friction circle, 0..1: how much of the lateral capacity the longitudinal impulse in use takes
+     *  away. `0` = the two axes independent (a spinning wheel corners as well as a rolling one);
+     *  `1` = the full circle — wheelspin or a locked wheel lets go sideways. */
+    circle?: number;
+}
+/**
+ * Tire presets — fresh point lists every call (editing one never touches another), and `scale`.
+ *
+ *  - `road` — Jolt's stock tire: lateral peak 1.2 at 3° falling to 1.0 by 20° and flat after, the
+ *    two axes independent, and the longitudinal clamp ×10 (Jolt's own sample runs this; it means a
+ *    driven wheel practically never spins up). Grippy, glued, hard to unsettle.
+ *  - `arcade` — the peak held all the way out on both axes: the car does not let go at all.
+ *  - `drift` — a tire that can be held sideways: lateral grip falls to 0.7 past 25°, the longitudinal
+ *    clamp is near the physical one (`traction: 2` — a launch at exactly 1 is a 0.4 g crawl; 2 keeps
+ *    it punchy) so the rear can be spun up, and a friction circle (`circle: 0.85` — most of it, so a
+ *    spinning rear loses most but not all of its lateral grip and the slide stays progressive):
+ *    power oversteer, and a slide the throttle keeps alive. A 600 N·m car lights its tires off the
+ *    line on it; that is the tire, and a traction control is the game's.
+ */
+export declare const Tire: {
+    road: () => Tire;
+    arcade: () => Tire;
+    drift: () => Tire;
+    /** Both curves multiplied by `k` — a grip slider, a cold tire, a wet road. A new tire; `t` is untouched. */
+    scale: (t: Tire, k: number) => Tire;
+};
+export declare function resolveTire(tire: Tire): ResolvedTire;
+export declare class Wheel extends Aspect<"wheel", Node> {
+    static readonly aspect = "wheel";
+    /** Wheel radius in metres. Default: measured from the node's rendered bounds, else 0.35. Too small
+     *  and the car scrapes, too large and it floats. */
+    radius?: number;
+    /** Wheel width in metres. Default: measured, else 0.25. */
+    width?: number;
+    /** Axle group, front to back. Default: derived from Z. Set it for a car whose wheels are not in neat
+     *  left/right pairs — an axle's wheels are paired for the differential and the anti-roll bar. */
+    axle?: number;
+    /** Does this wheel steer? Default: the wheels on the front axle. */
+    steer?: boolean;
+    /** This wheel's SHARE of the engine's torque, 0 = not driven. Default: from the vehicle's
+     *  `driveAxle` (1 on that axle). An axle's share is the sum of its two wheels', the left/right
+     *  split their ratio, so `0.6` / `0.4` front-to-rear is `driven: 0.3` on each front wheel and
+     *  `0.2` on each rear. Structural: baked at attach. */
+    driven?: number;
+    suspension: WheelSuspension;
+    /** The tire (default `Tire.road()`). Live: re-assign it or re-configure the aspect and the car
+     *  retunes in place — a grip slider, a tire that heats up. */
+    tire: Tire;
+    /** INPUT: brake torque on this wheel THIS frame, N·m (default 0). Sticky, like `Vehicle.throttle`:
+     *  write it every frame from a driver system's `updateBefore` — the foot brake's share, the
+     *  handbrake's 4500 on a rear wheel, an ABS's pulses — and the same physics step applies it. A
+     *  braking wheel is clamped at the physical tire limit (the `traction` boost is for drive only). */
+    brake: number;
+    /** Scene-editor inspector. `steer` / `driven` are deliberately absent: they are tri-state
+     *  (undefined = derive it from the axle), which a slider cannot express. */
+    static fields: FieldMeta<Wheel>;
+    static editor: {
+        rebuild: boolean;
+    };
+    onDetach(): void;
+    /** Re-configuring a wheel on a live car retunes the car: the tire is live; size, suspension, the
+     *  driven share and the axle are structural (re-attach the Vehicle). */
+    onReconfigure(): void;
+    private _state;
+    /** Touching the ground this step. */
+    get contact(): boolean;
+    /** Longitudinal slip RATIO, signed: 0 = rolling in sync with the ground, towards +1 = spinning up
+     *  (wheelspin), towards −1 = locking under braking — whichever way the car travels. Smoke, tire
+     *  marks, wheelspin sound and traction control key off this. */
+    get slip(): number;
+    /** Slip ANGLE in degrees, signed: how far the tire's travel direction is off from where it points,
+     *  positive when the contact patch slides to the tire's RIGHT. Past the curve's peak (~3°) the tire
+     *  is letting go sideways. */
+    get slipAngle(): number;
+    /** This wheel's steer angle in degrees, right-positive. */
+    get steerAngle(): number;
+    /** Wheel spin in rad/s (× radius ≈ the speed the tire is laying down). Forward-positive; a model
+     *  turns about the right-hand axle by MINUS the integrated angle. */
+    get spin(): number;
+    /** The tire's lateral force this step, N, positive toward the tire's right — the road pushing the
+     *  patch back against its slide. */
+    get sideForce(): number;
+    /** The tire's longitudinal force this step, N, positive pushing the car forward. */
+    get forwardForce(): number;
+    /** How fast the contact patch slides sideways, m/s, positive to the tire's right. */
+    get sideSlipSpeed(): number;
+    /** How fast the tread runs over the road, m/s, positive spinning up, negative locking. Force ×
+     *  sliding speed (`|sideForce × sideSlipSpeed| + |forwardForce × slipSpeed|`) is the friction's
+     *  heat into the tread, W — a tire-temperature model integrates it. */
+    get slipSpeed(): number;
+    /** The suspension's force on the wheel this step, N — the tire's LOAD (0 in the air). What a
+     *  friction budget divides by: `hypot(sideForce, forwardForce) / (load × μ)`. */
+    get load(): number;
+    /** Suspension compression, 0 = fully extended (drooping) … 1 = fully compressed. */
+    get compression(): number;
+    /** Where the wheel's centre is right now, in CHASSIS space: the suspension's attachment point,
+     *  down by however far it hangs this step. Put a wheel model here (see the file header). */
+    get position(): Vec3;
+    /** Edit mode: this wheel's own circle at its resting height, its travel range, and a mark when the
+     *  engine drives it — enough to place a wheel without running the game. */
+    rebuild(): void;
+}

package/dist/types/inject.d.ts

@@ -58,8 +58,12 @@ export { Presentable } from "./ui/UI";
 export type { PresentOptions, Transition, TransitionName, TransitionSpec, TransitionTransform } from "./ui/UI";
 export type { UINode, UINodeChild } from "./ui/UINode";
 export { theme, type ThemeValues, type ThemeAccessors } from "./ui/theme";
-export { animate, animateMat4, stopAnimation, pauseAnimation, resumeAnimation } from "./animate/animate";
+export { animate, type AnimateOptions, type AnimateValue, type AnimateOut } from "./animate/tween/animateValue";
 export { cubicBezier } from "./animate/bezier";
+export { Timeline, type TimelineOptions, type TimelineAddOptions, type TimelinePosition } from "./animate/tween/Timeline";
+export { type Animation } from "./animate/tween/Animation";
+export { type TweenMeta } from "./animate/tween/spec";
+export { type EasingInput } from "./animate/tween/easing";
 export { easeIn, easeOut, easeInOut } from "./animate/easings";
 export { QRScanner } from "./plugins/qr";
 export { CameraView, type CameraFacing } from "./plugins/camera";
@@ -85,24 +89,24 @@ export { Scene, ARScene, VRScene } from "./gl/Scene";
 export { Node } from "./gl/Node";
 export { Mesh } from "./gl/Mesh";
 export { Model } from "./gl/Model";
-export { Shape } from "./gl/Shape";
-export { Physics } from "./gl/Physics";
-export { Trigger } from "./gl/Trigger";
-export { AudioSource, type AudioCone } from "./gl/AudioSource";
-export { AudioZone } from "./gl/AudioZone";
-export { SceneAudio } from "./gl/SceneAudio";
-export { CharacterController } from "./gl/CharacterController";
-export { Vehicle } from "./gl/Vehicle";
-export type { DriveLayout, DifferentialMode, EngineConfig, SteeringConfig, AeroConfig } from "./gl/Vehicle";
-export { Wheel } from "./gl/Wheel";
-export { Ragdoll } from "./gl/Ragdoll";
-export type { RagdollPart, RagdollHinge } from "./gl/Ragdoll";
-export type { TireCurve, WheelSuspension, WheelTire, WheelVisual } from "./gl/Wheel";
-export { Gearbox } from "./gl/Gearbox";
+export { Shape } from "./gl/physics/Shape";
+export { Physics } from "./gl/physics/Physics";
+export { Trigger } from "./gl/physics/Trigger";
+export { AudioSource, type AudioCone } from "./gl/audio/AudioSource";
+export { AudioZone } from "./gl/audio/AudioZone";
+export { SceneAudio } from "./gl/audio/SceneAudio";
+export { CharacterController } from "./gl/physics/CharacterController";
+export { Vehicle } from "./gl/vehicle/Vehicle";
+export type { DriveLayout, DifferentialMode, EngineConfig, SteeringConfig, SteeringFeedback, SteeringDriver, AeroConfig } from "./gl/vehicle/Vehicle";
+export { Wheel, Tire, resolveTire } from "./gl/vehicle/Wheel";
+export { Ragdoll } from "./gl/physics/Ragdoll";
+export type { RagdollPart, RagdollHinge, RagdollFacing, RagdollActivateOptions, RagdollDeactivateOptions, RagdollHitOptions } from "./gl/physics/Ragdoll";
+export type { Point, WheelSuspension } from "./gl/vehicle/Wheel";
 export { AnimationClip } from "./gl/animation/AnimationClip";
 export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/animation/AnimationClip";
 export { Animator } from "./gl/animation/Animator";
 export type { LodMode } from "./gl/animation/Animator";
+export type { TrianglePick } from "./gl/Model";
 export { Feet } from "./gl/animation/Feet";
 export type { FeetOptions, FootState } from "./gl/animation/Feet";
 export { Warp } from "./gl/animation/Warp";
@@ -111,18 +115,22 @@ export { Playback } from "./gl/animation/Playback";
 export { Loop } from "./gl/animation/Loop";
 export { Layer } from "./gl/animation/Layer";
 export type { PlayOptions, StopOptions, LayerOptions, LoopOptions, LoopDef, BlendPosition, BlendMember, ActiveClip, ClipInfo, ClipCycle, ClipAlign, KneeAxisReport, StepHandler, ClipEventHandler } from "./gl/animation/core";
-export { IK } from "./gl/IK";
-export type { IKTwoBone, IKLookAt } from "./gl/IK";
+export { IK } from "./gl/animation/IK";
+export { DynamicBone, DynamicBoneCollider } from "./gl/animation/DynamicBone";
+export type { DynamicBoneCurve, DynamicBoneFloor, DynamicBoneColliders } from "./gl/animation/DynamicBone";
+export type { IKTwoBone, IKLookAt } from "./gl/animation/IK";
 export { Light } from "./gl/Light";
 export { Lightmap } from "./gl/Lightmap";
-export { Terrain } from "./gl/Terrain";
-export type { TerrainOptions, TerrainLayer, TerrainRegion, ConformOptions, RibbonOptions, AutoPaintRules, SculptOptions, TerrainHit, TerrainSnapshot } from "./gl/Terrain";
-export { NavMesh, NavCrowd } from "./gl/NavMesh";
-export type { NavMeshLoadOptions, NavMeshInfo, NavPath, NavQueryOptions, NavRaycastHit, NavAgentSize } from "./gl/NavMesh";
-export { NavAgent } from "./gl/NavAgent";
-export type { NavAgentState, NavAgentAvoidance, NavAgentDrive, NavAgentEvents } from "./gl/NavAgent";
-export { Locomotion } from "./gl/Locomotion";
-export type { LocomotionSet, LocomotionClip, LocomotionTuning, LocomotionState, LocomotionEvents, Displacement, Gait } from "./gl/Locomotion";
+export { Foliage } from "./gl/Foliage";
+export type { FoliageOptions, FoliageWind } from "./gl/Foliage";
+export { Terrain } from "./gl/terrain/Terrain";
+export type { TerrainOptions, TerrainLayer, TerrainRegion, ConformOptions, RibbonOptions, AutoPaintRules, SculptOptions, TerrainHit, TerrainSnapshot } from "./gl/terrain/Terrain";
+export { NavMesh, NavCrowd } from "./gl/nav/NavMesh";
+export type { NavMeshLoadOptions, NavMeshInfo, NavPath, NavQueryOptions, NavRaycastHit, NavAgentSize } from "./gl/nav/NavMesh";
+export { NavAgent } from "./gl/nav/NavAgent";
+export type { NavAgentState, NavAgentAvoidance, NavAgentDrive, NavAgentEvents } from "./gl/nav/NavAgent";
+export { Locomotion } from "./gl/animation/Locomotion";
+export type { LocomotionSet, LocomotionClip, LocomotionTuning, LocomotionState, LocomotionEvents, Displacement, Gait } from "./gl/animation/Locomotion";
 export { Material } from "./gl/Material";
 export { Geometry } from "./gl/Geometry";
 export { InstancedMesh } from "./gl/InstancedMesh";
@@ -134,5 +142,5 @@ export { Ray } from "./gl/Ray";
 export { Plane } from "./gl/Plane";
 export { Noise } from "./gl/Noise";
 export { Particles, Trail, curve, colorCurve } from "./gl/Particles";
-export { DecalSet } from "./gl/DecalSet";
-export type { DecalOptions, DecalSetOptions, DecalSpawnOptions, DecalPlacement } from "./gl/DecalSet";
+export { DecalSet, DecalTrail } from "./gl/DecalSet";
+export type { DecalOptions, DecalSetOptions, DecalSpawnOptions, DecalPlacement, DecalTrailOptions } from "./gl/DecalSet";

package/dist/types/runtime/files.d.ts

@@ -11,6 +11,19 @@ export declare function openFilePicker(options: OpenFilePickerOptions & {
 /** Anything writable as-is: text, raw bytes, or a buffer the host already holds
  *  (a picked `File`, a `FetchResponse`, a `Canvas.toFile()` snapshot). */
 export type FileData = string | Uint8Array | ArrayBuffer | File | FetchResponse;
+/** One directory entry, as `files.ls` / `files.stat` report it. */
+export type FileEntry = {
+    /** The last path segment. */
+    name: string;
+    /** Relative to the listed directory, `/`-separated — equal to `name` unless the listing was
+     *  recursive. Join it onto the directory you listed to read the file. */
+    path: string;
+    kind: "file" | "dir";
+    /** Bytes; 0 for a directory. */
+    size: number;
+    /** Last modification, ms since the epoch (a `Date` value). */
+    modified: number;
+};
 export declare const files: {
     /** Is there a filesystem here (desktop)? False on web/mobile, where every other call rejects. */
     readonly supported: boolean;
@@ -24,10 +37,20 @@ export declare const files: {
     readBytes(path: string): Promise<Uint8Array | null>;
     /** Delete a file, or a directory (empty, or any directory with `{ recursive: true }`). Deleting
      *  something already gone is success — what's promised is that the path is free afterwards. */
-    delete(path: string, options?: {
+    rm(path: string, options?: {
         recursive?: boolean;
     }): Promise<void>;
     /** Create a directory and any missing parents. An existing directory is fine. */
     mkdir(path: string): Promise<void>;
+    /** The entries of a directory, sorted by path — null when there is no such directory (an empty
+     *  one is `[]`, so `(await files.ls("saves")) ?? []` covers both). `{ recursive: true }` walks
+     *  the subfolders too; each entry's `path` is then relative to the directory listed. A path that
+     *  is a file, not a directory, rejects. Filter in JS — `entries.filter(e => e.name.endsWith(".json"))`. */
+    ls(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<FileEntry[] | null>;
+    /** What is at `path`: a file or a directory entry (`path` equal to `name`), or null when nothing
+     *  is there — `(await files.stat(p)) !== null` is the exists check. */
+    stat(path: string): Promise<FileEntry | null>;
 };
 export {};

package/dist/types/scene/defineScene.d.ts

@@ -5,10 +5,12 @@ import { Scene, type SceneOptions } from "../gl/Scene";
 import { Node } from "../gl/Node";
 import { Mesh } from "../gl/Mesh";
 import { Model } from "../gl/Model";
-import { type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/Terrain";
+import { type LightmapTransmit } from "../gl/Lightmap";
+import { type FoliageOptions } from "../gl/Foliage";
+import { type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/terrain/Terrain";
 import { Light, type SunOptions } from "../gl/Light";
 import { type MaterialDef } from "./material";
-import type { CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry";
+import type { CapsuleOptions, CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry";
 export type MeshDef = {
     kind: "box";
     size?: Vec3Like | number;
@@ -17,6 +19,8 @@ export type MeshDef = {
 } & SphereOptions) | ({
     kind: "cylinder";
 } & CylinderOptions) | ({
+    kind: "capsule";
+} & CapsuleOptions) | ({
     kind: "plane";
 } & PlaneOptions);
 export type LightDef = {
@@ -128,6 +132,12 @@ export type SceneNodeDef = {
      *  Default: static unless a `Physics` aspect moves the node (`dynamic` — Physics' default — or
      *  `kinematic`). Set it only to override that rule; prefab subtrees inherit the verdict. */
     lightmap?: boolean;
+    /** `model` nodes: vegetation — load through the FOLIAGE tier (wind, touch bending, per-copy tint; see
+     *  `Foliage`). `{ fade: [start, end] }` also thins the cards out over that distance range (m) and drops the
+     *  copy past `end` — for ground cover. The fade is per ASSET: every node of the same GLB shares it. */
+    foliage?: boolean | {
+        fade?: [number, number];
+    };
     /** Navigation (a scene with `env.navmesh`, see navmesh.md): every STATIC body is walkable by
      *  default. `false` leaves this one out of the bake; `'unwalkable'` cuts its footprint out
      *  (nobody stands on or crosses it). */
@@ -142,37 +152,44 @@ export type SceneCameraDef = CameraProjectionDef & {
     /** Point the camera looks at. */
     target?: Vec3Like;
 };
-/** `env.lightmap` — the level's baked lighting (see lightmap.md): the two files
- *  `lecodes lightmap bake` writes, plus how the bake is applied. Absent = real-time only. */
+/** `env.lightmap` — the level's baked lighting (packages/creator-bake): the files `lecodes lightmap bake`
+ *  writes. Absent = real-time only. */
 export type SceneLightmapDef = {
-    /** `asset('./assets/lightmap/lightmap.bake')` */
+    /** `asset('./assets/lightmap/level.bake')` */
     data: string;
-    /** `asset('./assets/lightmap/lightmap.ktx2')` — or, for a bake that took more than one atlas PAGE
-     *  (`lecodes lightmap bake --pages`), every page in order: `[asset('x.ktx2'), asset('x_1.ktx2')]`. */
-    texture: string | string[];
-    /** `asset('./assets/lightmap/lightmap-light.ktx2')` (pages like `texture`) — the point lights' baked
-     *  irradiance the bake writes when the level holds point lights; the real-time lights it carries are
-     *  switched off once it applies. Absent = the lamps stay real-time. */
-    light?: string | string[];
-    /** `asset('./assets/lightmap/lightmap.volume')` — the light VOLUME for everything that moves (the
-     *  same bake writes it): dynamic nodes, and every model loaded in code while the level runs, read
-     *  the baked sun/ambient at their own position. Absent = movers stay real-time only. */
+    /** `asset('./assets/lightmap/level-light.ktx2')` — or, for a bake that took more than one atlas PAGE
+     *  (`lecodes lightmap bake --pages`), every page in order: `[asset('x-light.ktx2'), asset('x-light_1.ktx2')]`. */
+    light: string | string[];
+    /** `asset('./assets/lightmap/level-aux.ktx2')` (pages like `light`) — sun / sky visibility + light direction. */
+    aux: string | string[];
+    /** DEBUG: the page sets a `lecodes lightmap bake --split` wrote (`<stem>-direct[_n].ktx2`, `<stem>-indirect[_n].ktx2`),
+     *  pages like `light` — the `Lightmap.debug("direct" | "indirect")` views bind them in place of `light`. */
+    direct?: string | string[];
+    indirect?: string | string[];
+    /** `asset('./assets/lightmap/level-probes.ktx2')` — the bake's reflection probes (one prefiltered cubemap of the level's
+     *  radiance per probe; every static reflects the nearest). Absent = statics reflect the sky's SH alone. */
+    probes?: string;
+    /** FOR THE BAKE: the radiance in cd / m² of emission 1.0 on this level (emissive factor x strength x map) - every lit
+     *  region of an emissive surface bakes as a rectangle lamp. An imported pack's emission is a LOOK (the school's panels
+     *  say 10); this is where the level says what they give: a 1.3 m ceiling panel of ~8000 lm is ~1600 nits. Default: what
+     *  the camera makes of 1.0 (`1.2 x 2^EV100`). 0 = emissive surfaces light nothing. `--emissive-nits` overrides. */
+    emissiveNits?: number;
+    /** `false` = the emissive surfaces light nothing in the bake - the level is lit by its lamps (`Light.point` with a
+     *  `bakeArea` next to every panel, the Unity packs' way) and the panels are decoration; `emissiveNits` then only says how
+     *  bright their glow is DRAWN (scene-referred: nits through the camera's exposure). Default true. */
+    emissiveBake?: boolean;
+    /** FOR THE BAKE: materials that let light THROUGH them, by glTF material name (`"name*"` = every name with that start) →
+     *  the share of a shadow ray that passes, tinted by the material's base colour x map: `{ mat_awning: 0.3 }` puts the
+     *  awning's warm, patterned light on the sand. The surface stays opaque - baked, drawn as before, a shadow caster.
+     *  `{ through, diffuse }` splits it: `through` goes straight (the picture of the map), `diffuse` is scattered by the
+     *  fibres (the underside glows, a soft fill with no picture) - dense canvas: `{ through: 0.08, diffuse: 0.25 }`. */
+    transmit?: Record<string, LightmapTransmit>;
+    /** `asset('./assets/lightmap/level.lgrid')` — THE LIGHT GRID for movers: every node a Physics aspect or a
+     *  CharacterController moves (and what code marks with `Lightmap.track`) takes its ambient light from the bake at the
+     *  place it is at, whatever its shader. Absent = movers keep the scene's IBL. */
     volume?: string;
-    /** 1 = baked sun shadows at full strength, 0 = ambient occlusion only. Default 1. */
-    sunStrength?: number;
-    /** Multiplier on the ambient share in the shadow math (1 = filament's own darkness). Default 1. */
-    ambientScale?: number;
-    /** How much of the baked ambient occlusion applies: 1 = all of it, 0 = none. An interior lit by its
-     *  ambient probe alone can want less than the geometric truth. Default 1. */
-    aoStrength?: number;
-    /** Multiplier on the baked point lights' irradiance (default 1) - dial the lamps up or down
-     *  without a re-bake, since their irradiance lives in the atlas. Scales the light volume with the
-     *  atlas, so movers match the statics. See `LightmapLoadOptions.lightBoost`. */
-    lightBoost?: number;
-    /** Multiplier on the light VOLUME's irradiance alone (default = `lightBoost`). Since the volume is an
-     *  ambient cube (2026-08-31) movers shade like the statics and the default is right; it stays as a
-     *  trim. See `LightmapLoadOptions.volumeBoost`. */
-    volumeBoost?: number;
+    /** A DEBUG multiplier on the atlas' lux (default 1). */
+    lightScale?: number;
 };
 /** `env.navmesh` — the level's navigation mesh (see navmesh.md): the file `lecodes navmesh bake`
  *  writes, the agent size it is built for, and the named areas. Absent = no navigation. */
@@ -193,6 +210,7 @@ export type SceneDef = {
     env?: SceneOptions & {
         lightmap?: SceneLightmapDef;
         navmesh?: SceneNavmeshDef;
+        foliage?: FoliageOptions;
     };
     camera?: SceneCameraDef;
     nodes?: Record<string, SceneNodeDef>;
@@ -256,7 +274,8 @@ export type ModelPartRow = {
  *  not parts, skipped. Filtering BEFORE segment math keeps `name[i]` indices stable no matter
  *  what defs are parented in. */
 export declare const modelPartRows: (root: Node) => ModelPartRow[];
-/** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule). */
+/** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule).
+ *  Children of a mover are movers too — buildNodes carries that down, this is the node's own verdict. */
 export declare const isLightmapStatic: (def: SceneNodeDef) => boolean;
 /** Edit mode: play the preview pose on a model node (`editor: { clip, time }`) — idempotent, the
  *  harness re-applies it on inspector edits. No clip = back to the rest pose. */

package/dist/types/ui/UIButton.d.ts

@@ -1,5 +1,5 @@
 import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType, LongPressEvent as LongPressEventType } from "../runtime/touch";
-import { type ElementStyle, type ContainerStyle, type DrawableStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type BaseStyle, type Color } from "./UINode";
+import { type ElementStyle, type ContainerStyle, type DrawableStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type BaseStyle, type Color, type LayerEasing } from "./UINode";
 export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & {
     rippleColor?: Color | "default";
 };
@@ -8,6 +8,8 @@ export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & {
 export interface UIButton extends UIContainerBase<UIButtonStyle & {
     onPressed?: UIButtonStyle & {
         duration?: number;
+        delay?: number;
+        easing?: LayerEasing;
     };
 }, DrawableStyle & BaseStyle> {
     readonly type: "button";

package/dist/types/ui/UIInput.d.ts

@@ -1,4 +1,4 @@
-import { type ElementStyle, type DrawableStyle, type TextStyle, type Color, type BaseStyle, type UIElementBase } from "./UINode";
+import { type ElementStyle, type DrawableStyle, type TextStyle, type Color, type BaseStyle, type UIElementBase, type LayerEasing } from "./UINode";
 type InputStyle = {
     placeholder?: string;
     placeholderColor?: Color;
@@ -50,6 +50,8 @@ type SubmitStyle = {
 export interface UIInput extends UIElementBase<UIInputStyle & SubmitStyle & {
     onFocused?: UIInputStyle & {
         duration?: number;
+        delay?: number;
+        easing?: LayerEasing;
     };
 }, DrawableStyle & BaseStyle> {
     readonly type: "input";
@@ -77,6 +79,8 @@ export interface UIInput extends UIElementBase<UIInputStyle & SubmitStyle & {
 export interface UITextArea extends UIElementBase<UIInputStyle & {
     onFocused?: UIInputStyle & {
         duration?: number;
+        delay?: number;
+        easing?: LayerEasing;
     };
 }, DrawableStyle & BaseStyle> {
     readonly type: "textarea";

package/dist/types/ui/UINode.d.ts

@@ -1,4 +1,6 @@
 import type { FetchResponse } from "../runtime/fetch";
+import type { Animation } from "../animate/tween/Animation";
+import { type TweenMeta } from "../animate/tween/spec";
 export interface UINode {
     readonly type: string;
     /** Author-given semantic name (a stable selector for tests + AI review feedback). */
@@ -158,8 +160,12 @@ export type TextStyle = {
 export type Reactive<T> = {
     [K in keyof T]: NonNullable<T[K]> extends object ? T[K] : T[K] | (() => T[K]);
 };
+/** The curve of a state block's swap (`$class` / `onPressed` / `onFocused` with a `duration`): a
+ *  curve name (`outCubic`, `inOutSine`, `smoothstep` — the default — …), `cubic-bezier(x1,y1,x2,y2)`
+ *  or `steps(n)`. A function cannot ride a style block; use `animateTo` for those. */
+export type LayerEasing = string;
 /** User-defined style classes: any `$`-prefixed key in `.style()` declares a state block toggled
- *  from code via the `el.class` proxy; `duration`/`delay` animate the swap. Class state INHERITS
+ *  from code via the `el.class` proxy; `duration`/`delay`/`easing` animate the swap. Class state INHERITS
  *  down the tree (CSS-`.dark`-on-body style): a class set on a node also activates same-name `$`
  *  blocks on all descendants within the same root (docs/style-class-cascade-plan.md).
  *  `$pressed`/`$focused` are reserved — hosts toggle them on press/focus (they beat other
@@ -172,6 +178,7 @@ export type ClassStyles<T> = {
     [key: `$${string}`]: T & {
         duration?: number;
         delay?: number;
+        easing?: LayerEasing;
     };
 };
 /** Value accepted by a `el.class` write: a boolean sets the class, a `() => boolean` binds it —
@@ -245,25 +252,15 @@ export type StyleFn<R, T extends object> = ((style: Reactive<T> & OrientationSty
  *  chaining — and per-key readable/writable (`el.style.opacity = 0.5`; a `() => value` write
  *  installs a reactive binding). */
 export type Style<R, T extends object> = StyleFn<R, T> & T & OrientationStyles<T> & ClassStyles<T>;
-/** The `animateTo`/`animateFrom` surface: target style props plus the flat meta keys below
- *  (stripped before the commit into the element's style). */
-export type AnimateStyle<R, T extends object> = ((style: T & {
-    /** Tween length in **milliseconds** (default 225). */
-    duration?: number;
-    /** Wait before starting, in **milliseconds**. A looping animation delays once, not per cycle. */
-    delay?: number;
-    /** Escape hatch: target an internal style layer (the onPressed/orientation mechanism). Not part of the supported surface. */
-    layer?: number;
-    /** `false` = animate without writing the targets into the element's style (e.g. a fade-out right before `.hide()`). */
-    commit?: boolean;
-    /** Repeat the animation: `true` = forever, a number = that many cycles. A looping animation is an
-     *  effect, not a state change — it never commits, and the element ends back at its base style.
-     *  The loop stops when a later `animateTo`/`animateFrom` runs on the element or it leaves the screen. */
-    loop?: boolean | number;
-    /** `"ping-pong"` (default) animates there and back each cycle — no jump. `"restart"` snaps back and
-     *  replays forward — for full-turn spinners (`transform: "rotate(360deg)"`) and shimmers. Only meaningful with `loop`. */
-    loopMode?: "restart" | "ping-pong";
-}) => R);
+/** Style props of an animate bag: a single value (tween from the current value) or an array of
+ *  KEYFRAMES (`opacity: [1, 0.3, 1]`, offsets via `times`). */
+export type AnimateProps<T extends object> = {
+    [K in keyof T]?: T[K] | T[K][];
+};
+/** The `animateTo`/`animateFrom` surface: target style props (single values or keyframe arrays) plus
+ *  the flat meta keys — `duration` / `delay` / `easing` / `times` / `loop` / `loopMode` / `commit` /
+ *  `clock`, see {@link TweenMeta}. Returns the {@link Animation} handle (seek, rate, `finished`). */
+export type AnimateStyle<R, T extends object> = ((style: AnimateProps<T> & TweenMeta) => Animation);
 export type AppearStyle<R, T> = (arg: {
     from: T;
     duration?: number;
@@ -306,10 +303,13 @@ export declare class Element<T extends string> {
     constructor(type: T, style: any);
     get style(): any;
     /** Tween to the target style and commit it (unless `commit: false` or looping — a loop is an
-     *  effect, not a state change). Meta keys: `duration`/`delay`/`loop`/… — see {@link AnimateStyle}. */
-    animateTo(style: any): this;
-    /** Tween FROM the given style to the element's current one (entrance animations). */
-    animateFrom(style: any): this;
+     *  effect, not a state change). A prop value may be an array of keyframes; meta keys
+     *  `duration`/`delay`/`easing`/`times`/`loop`/… — see {@link AnimateStyle}. Returns the
+     *  {@link Animation} handle. */
+    animateTo(style: any): Animation;
+    /** Tween FROM the given style to the element's current one (entrance animations): the element's
+     *  own style is the implicit last keyframe. Never modifies the stored style. */
+    animateFrom(style: any): Animation;
     protected _classProxy?: any;
     /** Style-class control — flips the `$`-class blocks declared in `.style()`. One proxy, same
      *  contract as `el.style`: