lecodes-sdk 2.4.9 → 2.5.0

package/dist/global.d.ts

@@ -39,6 +39,7 @@ declare global {
   const File: typeof SDK.File
   const Foliage: typeof SDK.Foliage
   const FollowPath: typeof SDK.FollowPath
+  const Font2D: typeof SDK.Font2D
   const FormData: typeof SDK.FormData
   const Geolocation: typeof SDK.Geolocation
   const Geometry: typeof SDK.Geometry
@@ -60,6 +61,7 @@ declare global {
   const MapView: typeof SDK.MapView
   const Mat4: typeof SDK.Mat4
   const Material: typeof SDK.Material
+  const Material2D: typeof SDK.Material2D
   const MaterialHandle: typeof SDK.MaterialHandle
   const Mathf: typeof SDK.Mathf
   const MediaStream: typeof SDK.MediaStream
@@ -80,6 +82,8 @@ declare global {
   const Noise: typeof SDK.Noise
   const OneWay2D: typeof SDK.OneWay2D
   const Particles: typeof SDK.Particles
+  const Particles2D: typeof SDK.Particles2D
+  const Path2D: typeof SDK.Path2D
   const Physics: typeof SDK.Physics
   const Physics2D: typeof SDK.Physics2D
   const PhysicsGroup2D: typeof SDK.PhysicsGroup2D
@@ -126,6 +130,7 @@ declare global {
   const SvgSource: typeof SDK.SvgSource
   const System: typeof SDK.System
   const Terrain: typeof SDK.Terrain
+  const Text2D: typeof SDK.Text2D
   const Texture: typeof SDK.Texture
   const Texture2D: typeof SDK.Texture2D
   const Tilemap: typeof SDK.Tilemap
@@ -176,8 +181,10 @@ declare global {
   const __channel: typeof SDK.__channel
   const __compOp: typeof SDK.__compOp
   const __compWrite: typeof SDK.__compWrite
+  const __localAsset: typeof SDK.__localAsset
   const __pushChannel: typeof SDK.__pushChannel
   const __pushEnable: typeof SDK.__pushEnable
+  const __registerFont: typeof SDK.__registerFont
   const __rpc: typeof SDK.__rpc
   const __serverOnly: typeof SDK.__serverOnly
   const __uiMap: typeof SDK.__uiMap
@@ -206,6 +213,7 @@ declare global {
   const easeOut: typeof SDK.easeOut
   const effect: typeof SDK.effect
   const encodeCells: typeof SDK.encodeCells
+  const env: typeof SDK.env
   const failureOf: typeof SDK.failureOf
   const fetch: typeof SDK.fetch
   const fetchLocal: typeof SDK.fetchLocal
@@ -283,6 +291,7 @@ declare global {
   type AutoPaintRules = SDK.AutoPaintRules
   type Autotile2D = SDK.Autotile2D
   type Bitmap = SDK.Bitmap
+  type Blend2D = SDK.Blend2D
   type BlendMember = SDK.BlendMember
   type BlendPosition = SDK.BlendPosition
   type BlockEntry = SDK.BlockEntry
@@ -351,10 +360,13 @@ declare global {
   type File = SDK.File
   type FileData = SDK.FileData
   type FillBlock = SDK.FillBlock
+  type Filter2D = SDK.Filter2D
   type FitOptions = SDK.FitOptions
   type FoliageOptions = SDK.FoliageOptions
   type FoliageWind = SDK.FoliageWind
   type FollowPath = SDK.FollowPath
+  type Font2D = SDK.Font2D
+  type Font2DOptions = SDK.Font2DOptions
   type FootState = SDK.FootState
   type FormData = SDK.FormData
   type Gait = SDK.Gait
@@ -428,6 +440,8 @@ declare global {
   type MarkerTap = SDK.MarkerTap
   type Mat4 = SDK.Mat4
   type Material = SDK.Material
+  type Material2D = SDK.Material2D
+  type Material2DOptions = SDK.Material2DOptions
   type MaterialData = SDK.MaterialData
   type MaterialDef = SDK.MaterialDef
   type MaterialHandle = SDK.MaterialHandle
@@ -471,10 +485,18 @@ declare global {
   type Noise = SDK.Noise
   type OneWay2D = SDK.OneWay2D
   type OrientationLock = SDK.OrientationLock
+  type ParticleMode2D = SDK.ParticleMode2D
+  type ParticleShape2D = SDK.ParticleShape2D
   type Particles = SDK.Particles
+  type Particles2D = SDK.Particles2D
+  type Particles2DOptions = SDK.Particles2DOptions
+  type Particles2DSourceDef = SDK.Particles2DSourceDef
   type PatchMaterial = SDK.PatchMaterial
   type PatchSlots = SDK.PatchSlots
+  type Path2D = SDK.Path2D
+  type Path2DOptions = SDK.Path2DOptions
   type PathMaterial = SDK.PathMaterial
+  type PathSourceDef = SDK.PathSourceDef
   type PermissionKind = SDK.PermissionKind
   type PermissionState = SDK.PermissionState
   type Physics = SDK.Physics
@@ -589,6 +611,9 @@ declare global {
   type StopOptions = SDK.StopOptions
   type StoredFile = SDK.StoredFile
   type StoredImage = SDK.StoredImage
+  type Stroke2D = SDK.Stroke2D
+  type StrokeCap2D = SDK.StrokeCap2D
+  type StrokeJoin2D = SDK.StrokeJoin2D
   type SvgSource = SDK.SvgSource
   type System<K extends string, S extends SystemHost = Scene, E extends EventMap = {}> = SDK.System<K, S, E>
   type SystemHost = SDK.SystemHost
@@ -600,6 +625,11 @@ declare global {
   type TerrainOptions = SDK.TerrainOptions
   type TerrainRegion = SDK.TerrainRegion
   type TerrainSnapshot = SDK.TerrainSnapshot
+  type Text2D = SDK.Text2D
+  type Text2DOptions = SDK.Text2DOptions
+  type TextAlign2D = SDK.TextAlign2D
+  type TextOutline2D = SDK.TextOutline2D
+  type TextSourceDef = SDK.TextSourceDef
   type Texture = SDK.Texture
   type Texture2D = SDK.Texture2D
   type TextureLoadOptions = SDK.TextureLoadOptions
@@ -676,6 +706,8 @@ declare global {
   type Vec3 = SDK.Vec3
   type Vec3Like = SDK.Vec3Like
   type Vehicle = SDK.Vehicle
+  type VelocityOverLife2D = SDK.VelocityOverLife2D
+  type VelocityValue2D = SDK.VelocityValue2D
   type VideoPlayer = SDK.VideoPlayer
   type Voice = SDK.Voice
   type VoiceEvents = SDK.VoiceEvents
@@ -689,17 +721,20 @@ declare global {
   type WheelSuspension = SDK.WheelSuspension
   type WidgetSet<Owner> = SDK.WidgetSet<Owner>
   type With<N, A extends Aspect<any, any, any>> = SDK.With<N, A>
+  type Wrap2D = SDK.Wrap2D
   // ---- server globals (available in *.server.ts; using them in client code is a build error) ----
   const ApiError: typeof SERVER.ApiError
   const SvgSource: typeof SERVER.SvgSource
   const channel: typeof SERVER.channel
   const defineDb: typeof SERVER.defineDb
+  const env: typeof SERVER.env
   const model: typeof SERVER.model
   const pushChannel: typeof SERVER.pushChannel
   const ref: typeof SERVER.ref
   const request: typeof SERVER.request
   const t: typeof SERVER.t
   type ApiError = SERVER.ApiError
+  type Env = SERVER.Env
   type PushChannel<D extends Record<string, unknown> | undefined = undefined> = SERVER.PushChannel<D>
   type PushMessage<D> = SERVER.PushMessage<D>
   type PushNotification<D> = SERVER.PushNotification<D>

package/dist/types/core/env.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The project's keys as code reads them: `env.NAME` — one word on both sides. Server code
+ * (`*.server.ts`, src/server/env.ts) reads every key; the app (src/runtime/env.ts) only the
+ * `PUBLIC_*` ones, baked into its bundle at compile time — a bundle is public, so a key the app
+ * carries is public by its name, and the compile refuses any other name in app code.
+ *
+ * A key is a `string`, never `string | undefined`: reading one that is not set THROWS `EnvError`,
+ * with the fix in the message. `"NAME" in env` tells without throwing; `Object.keys(env)` lists
+ * what is set. Only a key's shape throws: `then`, symbols, inspection hooks read as undefined, so
+ * `await env`, `console.log(env)` and JSON.stringify behave.
+ */
+export type Env = {
+    readonly [name: string]: string;
+};
+/** How a key is named — in `.env`, in Settings → Keys, in code. */
+export declare const ENV_NAME: RegExp;
+/** A key the app may carry: the only names the client bundle gets. */
+export declare const PUBLIC_ENV_PREFIX = "PUBLIC_";
+export declare const isPublicEnvName: (name: string) => boolean;
+export declare class EnvError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/** The `env` object over a source of values (read on every access: the server's are set by the host). */
+export declare const makeEnv: (read: () => Record<string, string>) => Env;

package/dist/types/core/particlesConfig.d.ts

@@ -0,0 +1,196 @@
+import { type ColorInput } from "./color";
+import { type Vec3Like } from "../math/vec";
+export type Range<T> = T | {
+    min: T;
+    max: T;
+};
+export declare const TAG_SHAPE = 1;
+export declare const TAG_LIFETIME = 2;
+export declare const TAG_RATE = 3;
+export declare const TAG_VELOCITY = 4;
+export declare const TAG_VELOCITY_RND = 5;
+export declare const TAG_ACCELERATION = 6;
+export declare const TAG_DRAG = 7;
+export declare const TAG_NOISE = 8;
+export declare const TAG_SEED = 9;
+export declare const TAG_PARAM_CURVE = 10;
+export declare const TAG_COLOR_CURVE = 11;
+export declare const TAG_SPACE = 12;
+export declare const TAG_INHERIT_VELOCITY = 13;
+export declare const TAG_RATE_DISTANCE = 14;
+export declare const TAG_RENDER_MODE = 15;
+export declare const TAG_MESH_GEOMETRY = 16;
+export declare const TAG_ANGULAR_VELOCITY = 17;
+export declare const TAG_GROUND = 18;
+export declare const TAG_VELOCITY_LIFE = 19;
+export declare const TAG_ORDER = 20;
+export declare const TAG_SMOOTH_PATH = 21;
+export declare const TAG_RIBBON_ORIENT = 22;
+export declare const TAG_LIT = 23;
+/** 0 / 1 — an XY-plane system; the 2D engine sets it itself at creation (CPART_TAG_PLANAR), the SDK never writes it. */
+export declare const TAG_PLANAR = 24;
+/** RENDER_MODE payloads (CPART_MODE_* in creator-particles.h). */
+export declare const MODE_POINTS = 0;
+export declare const MODE_QUADS = 1;
+export declare const MODE_RIBBON = 2;
+export declare const MODE_MESH = 3;
+/** The PARAM_CURVE slots the named params alias (custom[0..3]). */
+export declare const SLOT_SIZE = 0;
+export declare const SLOT_ROTATION = 1;
+export declare const SLOT_OPACITY = 2;
+export declare const SLOT_FRAME = 3;
+export declare class CurveBuilder {
+    private _kind;
+    private _lo;
+    private _hi;
+    private _stops;
+    constructor(base: Range<number>, mode: "multiply" | "add");
+    /** Curve value at birth (t = 0). Must come before any other stop. */
+    from(v: Range<number>): this;
+    /** Curve value at `t` (0..1 of the particle's life). Stops must be added in ascending t order. */
+    via(t: number, v: Range<number>): this;
+    /** Curve value at death (t = 1). */
+    to(v: Range<number>): this;
+    /** The classic opacity envelope: rise over the first `fadeIn`, fall over the last `fadeOut`. */
+    fade(fadeIn?: number, fadeOut?: number): this;
+    /** The PARAM_CURVE record payload (sans slot): [kind, baseLo, baseHi, n, (t, lo, hi)×n]. */
+    get _data(): Float32Array;
+}
+export declare class ColorCurveBuilder {
+    private _lo;
+    private _hi;
+    private _stops;
+    constructor(base: Range<ColorInput>);
+    /** Curve color at birth (t = 0). Must come first. The curve multiplies the base color. */
+    from(c: Range<ColorInput>): this;
+    /** Curve color at `t` (0..1 of the particle's life), in ascending t order. */
+    via(t: number, c: Range<ColorInput>): this;
+    /** Curve color at death (t = 1). */
+    to(c: Range<ColorInput>): this;
+    /** The COLOR_CURVE record payload: [baseLo rgba, baseHi rgba, n, (t, lo rgba, hi rgba)×n]. */
+    get _data(): Float32Array;
+}
+/** A value curve over each particle's lifetime. Default mode `multiply` (the curve scales the
+ *  base); `add` offsets it instead. */
+export declare const curve: (base?: Range<number>, mode?: "multiply" | "add") => CurveBuilder;
+/** A color curve over each particle's lifetime — always multiplies the base color. */
+export declare const colorCurve: (base?: Range<ColorInput>) => ColorCurveBuilder;
+export type ParticleValue = Range<number> | CurveBuilder | {
+    _data: Float32Array;
+};
+export type ParticleColor = ColorInput | {
+    min: ColorInput;
+    max: ColorInput;
+} | ColorCurveBuilder | {
+    _data: Float32Array;
+};
+/** A start velocity by direction + speed (the object form of `startVelocity`). */
+export type VelocityValue = {
+    speed?: Range<number>;
+    /** Cone half-angle in radians — jitter the launch direction uniformly within it. */
+    spread?: number;
+    /** Asymmetric jitter: two angles (u, v — the x/y components) in radians. */
+    randomizeAngle?: {
+        min: Vec3Like;
+        max: Vec3Like;
+    };
+} & ({
+    from: Vec3Like;
+} | {
+    to: Vec3Like;
+} | {
+    dir: Vec3Like;
+} | {});
+/** Where particles are born, in emitter space. Sphere / hemisphere / cone have an axis of +Y (the
+ *  hemisphere is the +Y half, the cone opens along +Y from its base disc at `center`) — aim the
+ *  node with `lookAt(target, 'y')`. `thickness` 0 emits from the surface only, 1 (default) from the
+ *  whole volume. A sphere or cone also sets the LAUNCH DIRECTION (outward / from the cone's apex)
+ *  when `startVelocity` gives a speed but no direction, like Unity's shapes. */
+export type ParticleShape = {
+    type: "point";
+    v: Vec3Like;
+} | {
+    type: "box";
+    min: Vec3Like;
+    max: Vec3Like;
+} | {
+    type: "circle";
+    center: Vec3Like;
+    radius: number;
+} | {
+    type: "sphere";
+    center?: Vec3Like;
+    radius: number;
+    thickness?: number;
+} | {
+    type: "hemisphere";
+    center?: Vec3Like;
+    radius: number;
+    thickness?: number;
+} | {
+    type: "cone";
+    center?: Vec3Like;
+    radius: number; /** half-angle, radians */
+    angle?: number; /** emit this far up the axis too */
+    length?: number;
+    thickness?: number;
+};
+/** Extra velocity over each particle's life — evaluated from the curves every frame and ADDED as a
+ *  displacement (not accumulated like `acceleration`): `radial` pushes outward along the particle's
+ *  birth direction (a burst that decays: `curve(4).to(0)`), `x`/`y`/`z` drift in the simulation
+ *  space (rising smoke: `y: curve(2).from(0).to(1)`). Unity's velocityOverLifetime. */
+export type VelocityOverLife = {
+    radial?: ParticleValue;
+    x?: ParticleValue;
+    y?: ParticleValue;
+    z?: ParticleValue;
+};
+export type ParticleNoise = {
+    strength?: number;
+    frequency?: number;
+    speed?: number;
+    /** How much of the displacement a particle earns with AGE (default 0 = all of it from birth).
+     *  The field is sampled by position, so at 0 every particle born at the same spot is pushed the
+     *  same way and a plume's root wanders off its emitter by up to `strength` metres; at 1 a particle
+     *  is born exactly where the emitter put it and drifts into the field over its life — what you
+     *  want whenever the source is visible (an exhaust pipe, a contact patch, a muzzle). */
+    ramp?: number;
+};
+/** Ground plane for bouncing particles (all render modes). `height` is in the simulation space:
+ *  world y with `space: 'world'`, emitter-local y otherwise. */
+export type ParticleGround = {
+    /** Plane height (default 0). */
+    height?: number;
+    /** Contact radius — particles stop `radius` above the plane (a mesh's half-extent; default 0). */
+    radius?: number;
+    /** Fraction of the vertical speed kept on impact, 0..1 (default 0.3). */
+    bounce?: number;
+    /** Tangential damping while in contact, per second — like `drag` (default 8). */
+    friction?: number;
+};
+/** The mesh a mesh-mode system draws per particle — structurally a `Geometry`. */
+export type ParticleMeshData = {
+    readonly vertices: ArrayLike<number>;
+    readonly normals: ArrayLike<number>;
+    readonly uv: ArrayLike<number>;
+    readonly indices: ArrayLike<number>;
+};
+/** A PARAM_CURVE record: `slot` 0 size / 1 rotation / 2 opacity / 3 frame. */
+export declare const pushParam: (out: number[], slot: number, value: ParticleValue) => void;
+export declare const pushColor: (out: number[], value: ParticleColor) => void;
+export declare const pushMesh: (out: number[], g: ParticleMeshData) => void;
+export declare const pushAngularVelocity: (out: number[], v: Vec3Like | {
+    min: Vec3Like;
+    max: Vec3Like;
+}) => void;
+export declare const pushGround: (out: number[], g: ParticleGround | null) => void;
+export declare const pushShape: (out: number[], shape: ParticleShape) => void;
+export declare const pushVelocityLife: (out: number[], v: VelocityOverLife) => void;
+export declare const pushVelocity: (out: number[], val: Vec3Like | VelocityValue) => void;
+/** A NOISE record; `null` turns the field off. */
+export declare const pushNoise: (out: number[], n: ParticleNoise | null) => void;
+/** A LIFETIME record. */
+export declare const pushLifetime: (out: number[], val: Range<number>) => void;
+/** The default flipbook: with a sheet of more than one frame and no explicit `frame`, one full sheet
+ *  cycle over each particle's lifetime, starting at `startFrame` (`'random'` = desynchronized loops). */
+export declare const pushDefaultFrames: (out: number[], cols: number, rows: number, startFrame?: number | "random") => void;

package/dist/types/g2/Font2D.d.ts

@@ -0,0 +1,19 @@
+import { type FetchResponse, type File } from "../runtime/fetch";
+export type Font2DOptions = {
+    /** For a registered family: the face's weight (default 400; the nearest registered one is used). */
+    weight?: number;
+    /** For a registered family: the italic face (default false). */
+    italic?: boolean;
+};
+export declare class Font2D {
+    /** Native font handle. */
+    readonly id: number;
+    private _key?;
+    /** A registered family name (what `font("inter")` compiles to, e.g. "Inter") picks the ttf of
+     *  (weight ?? 400, italic); anything else is a URL / asset path / response / File fetched as is
+     *  (`asset('./fonts/Brand.ttf')`). Cached per resolved URL: a family loads once. */
+    static load(source: string | FetchResponse | File, options?: Font2DOptions): Promise<Font2D>;
+    /** Free the native font (and its atlas) — for every holder of this cached font; a later load
+     *  parses it again. Texts still using it stop drawing. */
+    destroy(): void;
+}

package/dist/types/g2/Material2D.d.ts

@@ -0,0 +1,24 @@
+export type Blend2D = "alpha" | "additive";
+export type Filter2D = "nearest" | "linear";
+export type Wrap2D = "clamp" | "repeat";
+export type Material2DOptions = {
+    /** `'alpha'` (default) covers what is under it by its alpha; `'additive'` adds its colour. */
+    blend?: Blend2D;
+    /** Texture sampling; unset = the renderer default (the Scene2D `filter`). */
+    filter?: Filter2D;
+    /** `'clamp'` (default) stretches the edge texel past [0,1]; `'repeat'` tiles the texture. */
+    wrap?: Wrap2D;
+};
+export declare class Material2D {
+    readonly blend: Blend2D;
+    /** Undefined = the renderer default (the Scene2D `filter`). */
+    readonly filter?: Filter2D;
+    readonly wrap: Wrap2D;
+    private constructor();
+    /** An alpha-blended material — what every sprite and tilemap has by default. */
+    static sprite(options?: Material2DOptions): Material2D;
+    /** An additive material: glow, fire, sparks, flashes. */
+    static additive(options?: Omit<Material2DOptions, "blend">): Material2D;
+    /** The default material (alpha blend, renderer-default filter, clamp). */
+    static readonly default: Material2D;
+}

package/dist/types/g2/Node2D.d.ts

@@ -47,7 +47,7 @@ export declare class Node2D extends AspectHost<Node2DEvents> implements CompWrit
     protected _rotation: number;
     protected _sx: number;
     protected _sy: number;
-    protected _layer: number;
+    protected _renderPriority: number;
     protected _z: number;
     protected _visible: boolean;
     private _pushXf;
@@ -70,10 +70,11 @@ export declare class Node2D extends AspectHost<Node2DEvents> implements CompWrit
     animateTo(props: Node2DTweenProps & TweenMeta): Animation;
     /** Tween FROM the given values to the node's current transform. */
     animateFrom(props: Node2DTweenProps & TweenMeta): Animation;
-    /** Draw layer (int). Higher layers render on top. */
-    get layer(): number;
-    set layer(v: number);
-    /** Intra-layer depth for non-Y-sorted layers (higher z = on top). */
+    /** Coarse draw order: 0 draws first, 7 last, 4 is the default — the 3D `Mesh.renderPriority`.
+     *  Within one priority `z` orders, then (with `scene.ySort` on) world Y. Rounded and clamped to 0..7. */
+    get renderPriority(): number;
+    set renderPriority(v: number);
+    /** Draw order within a renderPriority (higher = on top); with `scene.ySort` on, equal z sorts by world Y. */
     get z(): number;
     set z(v: number);
     get visible(): boolean;

package/dist/types/g2/Particles2D.d.ts

@@ -0,0 +1,169 @@
+import { type Vec2Like } from "../math/vec";
+import { type ParticleColor, type ParticleGround, type ParticleNoise, type ParticleValue, type Range } from "../core/particlesConfig";
+import { Node2D } from "./Node2D";
+import type { Material2D } from "./Material2D";
+import type { Texture2D } from "./Texture2D";
+export type ParticleMode2D = "quads" | "points" | "trail";
+/** Where particles are born, in the node's local frame.
+ *  - `point` at `v` (default the origin);
+ *  - `box` between `min` and `max` (a spawn line: give it no height);
+ *  - `circle` of `radius` around `center` — a disc, evenly filled; `thickness` 0 = the outline only (a
+ *    ring). Gives the launch direction (outward) when `startVelocity` has a speed and no direction;
+ *  - `cone` opening along +y from its base of half-width `radius` at `center`: `angle` (half-angle,
+ *    radians) flares it, `length` emits that far up the axis too; launches away from the apex.
+ *  `thickness` 0 = the outline only, 1 (default) = the whole area. */
+export type ParticleShape2D = {
+    type: "point";
+    v?: Vec2Like;
+} | {
+    type: "box";
+    min: Vec2Like;
+    max: Vec2Like;
+} | {
+    type: "circle";
+    center?: Vec2Like;
+    radius: number;
+    thickness?: number;
+} | {
+    type: "cone";
+    center?: Vec2Like;
+    radius: number;
+    angle?: number;
+    length?: number;
+    thickness?: number;
+};
+/** A start velocity by direction + speed. `dir` launches along a vector, `from` away from a point,
+ *  `to` toward one; with none, a sphere / cone `shape` gives the direction, else a random one.
+ *  `spread` jitters the direction by up to ± that angle (radians, in the plane). */
+export type VelocityValue2D = {
+    speed?: Range<number>;
+    spread?: number;
+} & ({
+    from: Vec2Like;
+} | {
+    to: Vec2Like;
+} | {
+    dir: Vec2Like;
+} | {});
+/** Extra velocity over each particle's life, ADDED as a displacement: `radial` along its birth
+ *  direction (a burst that decays: `curve(200).to(0)`), `x` / `y` a drift (rising smoke:
+ *  `y: curve(60).from(0).to(1)`). See `VelocityOverLife` (3D). */
+export type VelocityOverLife2D = {
+    radial?: ParticleValue;
+    x?: ParticleValue;
+    y?: ParticleValue;
+};
+export type Particles2DOptions = {
+    /** The particle image — one picture or a flipbook sheet (`sheet`). Omit = solid squares of `color`. */
+    texture?: Texture2D;
+    /** The texture's flipbook grid: `N` = N×N, `[cols, rows]`; frames run left-to-right, top-to-bottom.
+     *  Default 1. With more than one frame and no `frame`, each particle plays the sheet once over its
+     *  life, from `startFrame`. */
+    sheet?: number | [cols: number, rows: number];
+    /** Blend (+ sampling) — `Material2D.additive()` for fire, sparks, glow. Default alpha. */
+    material?: Material2D;
+    /** Pool capacity (default 1000). */
+    maxParticles?: number;
+    /** `'quads'` (default) a rotated square each; `'points'` the same look from a cheaper stream;
+     *  `'trail'` one ribbon strip through the particles in spawn order — `size` is its width (pair it
+     *  with `space: 'world'` and `rateOverDistance` for a trail behind a moving node). */
+    mode?: ParticleMode2D;
+    /** Particles emitted per second. */
+    rate?: number;
+    /** Particles emitted per world unit the emitter MOVES, on top of `rate` (trails; meant for
+     *  `space: 'world'`). */
+    rateOverDistance?: number;
+    /** Lay a frame's distance spawns along a curve through the emitter's path, not the straight chord. */
+    smooth?: boolean;
+    /** `'local'` (default) — particles ride the node; `'world'` — each stays where it was born as the
+     *  emitter moves on. Switching at runtime resets live particles. */
+    space?: "local" | "world";
+    /** Fraction of the emitter's own velocity given to each particle at spawn (`space: 'world'`). */
+    inheritVelocity?: number;
+    shape?: ParticleShape2D;
+    /** A vector (its length is the speed) or a direction + speed. World units / s. */
+    startVelocity?: Vec2Like | VelocityValue2D;
+    velocityOverLife?: VelocityOverLife2D;
+    /** Downward acceleration, world units/s² — positive pulls toward -y (sugar for
+     *  `acceleration: [0, -g]`); negative makes smoke rise. */
+    gravity?: number;
+    /** Constant acceleration (gravity, wind). Wins over `gravity` when both are set. */
+    acceleration?: Vec2Like;
+    drag?: number;
+    /** Seconds each particle lives. */
+    lifetime?: Range<number>;
+    color?: ParticleColor;
+    /** Diameter in WORLD units (custom[0]). Default 1 — a 2D world is usually pixel-scaled, so set it. */
+    size?: ParticleValue;
+    /** The particle's spin, radians (custom[1]) — a curve with mode `add` turns it over its life. */
+    rotation?: ParticleValue;
+    /** 0..1 (custom[2]). Default 1. */
+    opacity?: ParticleValue;
+    /** Flipbook frame index (custom[3]). */
+    frame?: ParticleValue;
+    /** Where the default flipbook cycle begins: `'random'` (default) or a frame index. */
+    startFrame?: number | "random";
+    /** A floor at `height` on the y axis the particles bounce on and rest on; `null` disables it. */
+    ground?: ParticleGround | null;
+    /** Turbulence; `null` turns it off. */
+    noise?: ParticleNoise | null;
+    /** Fixed random seed for deterministic tests. */
+    seed?: number;
+    position?: Vec2Like;
+    /** Draw order within a renderPriority — see {@link Node2D.z}. */
+    z?: number;
+    /** Coarse draw order 0..7, default 4 — see {@link Node2D.renderPriority}. */
+    renderPriority?: number;
+};
+export declare class Particles2D extends Node2D {
+    private _texture?;
+    private _sheet;
+    private _material?;
+    private _mode;
+    private _startFrame;
+    private _frameSet;
+    readonly maxParticles: number;
+    /** Curve-param slots 0..3, live: size / rotation / opacity / frame alias 0..3. The particle
+     *  rotation is `custom[1] = …` (the node's own `rotation` is the emitter's). */
+    readonly custom: ParticleValue[];
+    constructor(options?: Particles2DOptions);
+    private _sendParticles;
+    private _send;
+    /** Emit `count` particles now, where the emitter is (a burst). */
+    spawn(count: number): this;
+    /** Live particles right now. */
+    get alive(): number;
+    /** The particle image; undefined = solid squares of the colour. */
+    get texture(): Texture2D | undefined;
+    set texture(t: Texture2D | undefined);
+    /** The texture's flipbook grid [cols, rows]. Without an explicit `frame` the default cycle follows. */
+    get sheet(): [number, number];
+    set sheet(s: number | [number, number]);
+    /** Blend ({@link Material2D}). Undefined = the default (alpha). */
+    get material(): Material2D | undefined;
+    set material(m: Material2D);
+    /** How particles are drawn — see `Particles2DOptions.mode`. */
+    get mode(): ParticleMode2D;
+    set mode(m: ParticleMode2D);
+    set rate(val: number);
+    /** `'world'` leaves particles behind where they were born (trails). Switching resets live ones. */
+    set space(val: "local" | "world");
+    set inheritVelocity(val: number);
+    set rateOverDistance(val: number);
+    set smooth(val: boolean);
+    set shape(shape: ParticleShape2D);
+    set startVelocity(val: Vec2Like | VelocityValue2D);
+    set velocityOverLife(v: VelocityOverLife2D);
+    /** Positive pulls toward -y — sugar for `acceleration = [0, -g]`. */
+    set gravity(val: number);
+    set acceleration(a: Vec2Like);
+    set drag(val: number);
+    set seed(val: number);
+    set lifetime(val: Range<number>);
+    set size(val: ParticleValue);
+    set opacity(val: ParticleValue);
+    set frame(val: ParticleValue);
+    set color(value: ParticleColor);
+    set ground(g: ParticleGround | null);
+    set noise(n: ParticleNoise | null);
+}