tecs.gfx.particles

function newCurve(keys: {CurveKey}): Curve

function newEffect(options: EffectOptions): Effect

function newGradient(keys: {CurveKey}): Gradient

type Color = string | number | {number}

type Curve = {
    --- Read-only. Provides evenly spaced samples over normalized age from zero
    --- to one.
    samples: {number}
}

type CurveKey = {any}

type Effect = {
    --- Read-only. Reports the effect name and the only property that outlives the
    --- process. Everything a save, a tool or a person identifies an effect by
    --- is this.
    name: string,

    --- Read-only. Reports where its record sits in the assembled effect table, counting
    --- from one. A position in registration order, so it means nothing outside the
    --- process that assigned it and nothing stores one.
    index: integer,

    --- Read-only. Reports how many live particles one emitter can hold.
    capacity: integer,

    --- Read-only. Reports the blend mode the effect resolved to, which is one of
    --- the three `render.blend` names and never nil. The pool reads it to say how
    --- many of its slots may reach the forward pass.
    blend: string,

    --- Read-only. Reports the longest particle lifetime in seconds, which decides when
    --- an emitter that has stopped emitting has finished.
    maxLifetime: number,

    --- Read-only. Reports the mean particle lifetime in seconds, halfway between the
    --- bounds `initial.lifetime` was authored with. This is the window `estimatedCount`
    --- integrates the schedule over, and it is the steady-state live count divided by
    --- the emission rate.
    meanLifetime: number,

    --- Read-only. Reports seconds from `play` to the last emission, or -1 for an effect
    --- that never stops emitting.
    emitFor: number,

    --- Read-only. Reports the continuous emission rate used by `finished` and
    --- `estimatedCount`.
    rate: number,

    --- Read-only. Reports the emission delay in seconds.
    delay: number,

    --- Read-only. Reports the emission duration in seconds.
    duration: number,

    --- Read-only. Reports whether the emission cycle repeats.
    looping: boolean,

    --- Read-only. Provides the compiled burst schedule.
    bursts: {number},

    --- Engine-owned. Stores the compiled effect record. Ordinary game code
    --- should ignore this field.
    _record: {number},

    --- Engine-owned. Stores curve and gradient samples. Ordinary game code
    --- should ignore this field.
    _extra: {number},

    --- Engine-owned. Stores the size-curve offset. Ordinary game code should
    --- ignore this field.
    _sizeCurveAt: integer,

    --- Engine-owned. Stores the color-gradient offset. Ordinary game code
    --- should ignore this field.
    _colorGradientAt: integer,

    --- Engine-owned. Keeps the authored image and clipping sources for reloads.
    _render: RenderOptions
}

type EffectOptions = {
    --- Caller-writable. Sets the required process-wide unique effect name.
    --- Snapshots use this name to identify the effect.
    name: string,

    --- Caller-writable. Sets how many live particles one emitter can hold.
    --- Defaults to 256, and under one raises. A steady-state emitter needs at
    --- least `rate * maxLifetime`; a smaller capacity registers, drops the
    --- emissions that find no slot, and logs a warning saying so, because a
    --- spray thinner than the one authored is otherwise found by eye.
    capacity: integer?,

    --- Caller-writable. Selects `"drop"` or `"replace"` when an emission arrives
    --- with no free slot: give way, or take the oldest live particle's. Defaults
    --- to `"replace"`, and anything else raises.
    overflow: string?,

    --- Caller-writable. Configures when the effect emits particles. An absent
    --- section takes every default below it.
    schedule: ScheduleOptions?,

    --- Caller-writable. Configures where the effect spawns particles. An absent
    --- section takes every default below it.
    spawn: SpawnOptions?,

    --- Caller-writable. Configures each particle's initial properties. An absent
    --- section takes every default below it.
    initial: InitialOptions?,

    --- Caller-writable. Configures how particles change over their lifetime. An
    --- absent section leaves a particle on its launch velocity.
    update: UpdateOptions?,

    --- Caller-writable. Configures how particles draw. An absent section draws
    --- white quads on layer one.
    render: RenderOptions?
}

record Emitter
    effect: Effect
    state: string = "playing"
    seed: number = 1
    rateScale: number = 1
    sizeScale: number = 1
    timeScale: number = 1
    tint: Color? = nil
    play: function(exclusive self: Emitter): nil
    stop: function(exclusive self: Emitter): nil
    pause: function(exclusive self: Emitter): nil
    clear: function(exclusive self: Emitter): nil
    restart: function(exclusive self: Emitter): nil
    burst: function(exclusive self: Emitter, count: integer): nil
    finished: function(borrows self: Emitter): boolean
    estimatedCount: function(borrows self: Emitter): integer
end

type EmitterOptions = {
    --- Caller-writable. Selects the registered immutable effect.
    effect: Effect,

    --- Caller-writable. Starts playing, paused, or stopped and defaults to playing.
    state: string?,

    --- Caller-writable. Seeds deterministic emission with an integer from zero through
    --- 16777215.
    seed: number?,

    --- Caller-writable. Scales the scheduled emission rate and defaults to one.
    rateScale: number?,

    --- Caller-writable. Scales particle size and defaults to one.
    sizeScale: number?,

    --- Caller-writable. Scales simulation seconds and defaults to one.
    timeScale: number?,

    --- Caller-writable. Multiplies particle RGBA and defaults to white.
    tint: Color?
}

type Gradient = {
    --- Read-only. Provides evenly spaced RGBA samples over normalized age,
    --- with four floats per sample.
    samples: {number}
}

type InitialOptions = {
    --- Caller-writable. Sets particle lifetime in seconds. Defaults to one, and
    --- its upper bound is the effect's `maxLifetime`.
    lifetime: Value?,

    --- Caller-writable. Sets initial speed in world units per second. Defaults to
    --- zero.
    speed: Value?,

    --- Caller-writable. Sets initial size in world units. Defaults to one.
    size: Value?,

    --- Caller-writable. Sets initial rotation in radians. Defaults to zero.
    rotation: Value?,

    --- Caller-writable. Sets initial angular velocity in radians per second.
    --- Defaults to zero.
    angularVelocity: Value?,

    --- Caller-writable. Sets constant horizontal acceleration. Independent axes
    --- make a plume drift apart instead of translating as a block. Defaults to
    --- zero.
    accelerationX: Value?,

    --- Caller-writable. Sets constant vertical acceleration. Defaults to zero.
    accelerationY: Value?,

    --- Caller-writable. Sets the color every particle starts with, multiplied by
    --- the gradient and by the emitter's tint. Defaults to opaque white.
    color: Color?
}

record Pool
    capacity: integer
    maxEmitters: integer
end

type PoolOptions = {
    --- Caller-writable. Reserves 1 to 4000000 slots and defaults to 16384.
    capacity: integer?,

    --- Caller-writable. Reserves emitter records and defaults to 256.
    maxEmitters: integer?
}

type Range = {
    --- Caller-writable. Sets the inclusive lower bound.
    min: number,

    --- Caller-writable. Sets the inclusive upper bound.
    max: number
}

type RenderOptions = {
    --- Caller-writable. Selects the material that shades the quad by name. An
    --- absent value samples the image array and covers the whole quad.
    material: string?,

    --- Caller-writable. Passes one number to the material, clamped to zero
    --- through `0.999` and ignored unless `material` names one. The instance
    --- carries the material as `id + param` in one float, and the vertex shader
    --- reads the integer part as the selector and the fraction as the
    --- parameter, so `1.0` would arrive as the next material's id with a
    --- parameter of zero. Defaults to zero.
    materialParam: number?,

    --- Caller-writable. Selects a registered image from `renderer.sprites:sprite`. An
    --- absent value draws a white quad.
    sprite: rendercomponents.Sprite?,

    --- Caller-writable. Selects a sheet to animate instead of a still region.
    --- The cycle is played exactly once over each particle's own life and clamps
    --- at the end, so a randomized lifetime randomizes the playback speed.
    ---
    --- Uses the same frame table an animated entity does, so per-frame
    --- durations, reverse and pingpong all arrive already spent.
    sheet: sheet.Sheet?,

    --- Caller-writable. Selects the sheet tag to animate. An absent value
    --- animates the whole sheet. A name the sheet does not carry animates the
    --- whole sheet too, and the sheet reports it at error level under the
    --- `tecs.gfx` logger, naming the tags it does carry. Defining the effect
    --- still succeeds, so a sheet re-exported without a tag keeps drawing.
    tag: string?,

    --- Caller-writable. Selects the render layer from one to `layers.MAX`.
    --- Defaults to one, and anything outside the range raises.
    layer: integer?,

    --- Caller-writable. Sets the horizontal pivot as a fraction of the
    --- frame from its top left. Defaults to `0.5`, the middle.
    pivotX: number?,

    --- Caller-writable. Sets the vertical pivot as a fraction of the frame
    --- from its top edge. Defaults to `0.5`, the middle.
    pivotY: number?,

    --- Caller-writable. Selects `"fixed"` or `"velocity"` alignment. Velocity
    --- alignment adds the path's angle to the particle's own rotation, so a
    --- spinning spark aligned to its path still spins. Defaults to `"fixed"`,
    --- and anything else raises.
    alignment: string?,

    --- Caller-writable. Multiplies the along-path axis when aligned to
    --- velocity. Defaults to one.
    stretch: number?,

    --- Caller-writable. Selects `"alpha"`, `"additive"`, or `"opaque"`. Defaults
    --- to `"alpha"`, and anything else raises.
    ---
    --- `"alpha"` and `"additive"` draw in the forward pass over the composited
    --- image, depth tested and not written, so a particle is still hidden by
    --- geometry in front of it. `"alpha"` keeps that much less of what is behind
    --- it and `"additive"` adds to it, so a dark additive particle changes
    --- nothing and overlapping ones brighten.
    ---
    --- `"opaque"` draws into the G-buffer instead. What it gives up is alpha,
    --- which the G-buffer is written with replace and has nowhere to put: a fade
    --- to transparent writes opaque over what was behind it, and the only fade
    --- left is a size curve reaching zero. What it buys is everything that reads
    --- the G-buffer, which is the occluder mask and being shadowed by one.
    blend: string?,

    --- Caller-writable. Selects the clip region that contains the fragments.
    --- Defaults to zero, which is no clipping.
    clip: integer?
}

type ScheduleBurst = {
    --- Caller-writable. Sets the burst time in seconds from the cycle start.
    time: number,

    --- Caller-writable. Sets how many particles the burst emits.
    count: number
}

type ScheduleOptions = {
    --- Caller-writable. Sets the continuous emission rate in particles per
    --- second. Defaults to zero, which emits only what `bursts` asks for.
    rate: number?,

    --- Caller-writable. Sets the emission cycle duration in seconds. Defaults to
    --- zero, which leaves the cycle open.
    duration: number?,

    --- Caller-writable. Controls whether the emission cycle repeats. Defaults to
    --- false.
    looping: boolean?,

    --- Caller-writable. Sets the delay before emission starts in seconds.
    --- Defaults to zero.
    delay: number?,

    --- Caller-writable. Defines at most four timed burst counts measured from
    --- the start of the cycle. A muzzle flash is one burst at time zero.
    --- Defaults to none, and a fifth raises.
    bursts: {ScheduleBurst}?
}

type SpawnOptions = {
    --- Caller-writable. Selects `"point"`, `"line"`, `"rectangle"`,
    --- `"rectangleEdge"`, `"disc"`, `"ring"`, or `"cone"`. Defaults to
    --- `"point"`, and anything else raises.
    shape: string?,

    --- Caller-writable. Sets width for a line or rectangle and radius for a
    --- disc, ring, or cone. Defaults to zero.
    width: number?,

    --- Caller-writable. Sets height for a rectangle. Every other shape ignores
    --- it. Defaults to zero.
    height: number?,

    --- Caller-writable. Sets the sampled sector of a disc, ring, or cone in
    --- radians. Defaults to a full turn.
    arc: number?,

    --- Caller-writable. Rotates the sampled area in radians, independently of
    --- launch direction. Defaults to zero.
    rotation: number?,

    --- Caller-writable. Selects `"uniform"` or `"normal"` sampling. A gaussian
    --- spread makes a column read as a column rather than as a slab. Defaults to
    --- `"uniform"`, and anything else raises.
    distribution: string?,

    --- Caller-writable. Sets the launch direction in radians and centers the
    --- full cone on it, so a particle leaves within plus or minus half of
    --- `spread`. Half-angle is the other plausible reading of `spread` and a
    --- mismatch is silent, so it is said here. Defaults to zero.
    direction: number?,

    --- Caller-writable. Sets the full cone width in radians. Defaults to zero,
    --- which launches every particle along `direction`.
    spread: number?,

    --- Caller-writable. Launches along the shape's outward normal rather than
    --- along `direction`. Meaningful for the shapes that have one: disc, ring,
    --- cone and a rectangle's edge. Defaults to false.
    outward: boolean?,

    --- Caller-writable. Selects `"local"` or `"world"` space. Local particles
    --- follow the emitter's transform for their whole life; world particles read
    --- it once, at spawn, and then move independently. Neither is a good
    --- universal default, so it is explicit and defaults to `"world"`. Anything
    --- else raises.
    space: string?,

    --- Caller-writable. Sets how much emitter velocity a particle inherits, from
    --- zero to one. Defaults to zero, and world space is the only space it means
    --- anything in: a local particle is already carried by the emitter, so
    --- inheriting would carry it twice.
    inheritVelocity: number?
}

type UpdateOptions = {
    --- Caller-writable. Sets damping in units of one over seconds, applied as
    --- `velocity = velocity / (1 + drag * dt)`, so it composes with any step.
    --- Defaults to zero.
    drag: number?,

    --- Caller-writable. Sets acceleration away from the emitter. This and
    --- `tangentialAcceleration` are the difference between a fountain and a
    --- vortex. Defaults to zero.
    radialAcceleration: Value?,

    --- Caller-writable. Sets acceleration at right angles to the emitter.
    --- Defaults to zero.
    tangentialAcceleration: Value?,

    --- Caller-writable. Multiplies each particle's size over its life. An absent
    --- curve multiplies by one, so leaving it out costs nothing.
    size: Curve?,

    --- Caller-writable. Multiplies each particle's color over its life. An absent
    --- gradient multiplies by white, so leaving it out costs nothing. Its alpha
    --- fades a blended effect and is ignored by an effect whose `render.blend` is
    --- `"opaque"`.
    color: Gradient?
}

type Value = number | Range

function plugin(exclusive world: ecs.World, options: PoolOptions?): nil

function poolOf(borrows world: ecs.World): Pool?

function section(borrows world: ecs.World): string

const ParticleEmitter