@moku-labs/game 0.4.2 → 0.4.4

package/dist/types-w646dMeA.d.mts

@@ -0,0 +1,648 @@
+import { D as Point, E as FilterSlot, L as ComponentHandle, V as Entity, _ as PixiModule, g as PixiFilter, k as Api$1, m as Api$2, o as Events, t as Api$3, ut as Api, v as PixiSprite, vn as Require, y as PixiTexture, z as ComponentType } from "./types-Dy1xB68L.mjs";
+import { g as AnimApi } from "./types-C-4f2jD_.mjs";
+import { Log } from "@moku-labs/common/browser";
+import { PluginCtx } from "@moku-labs/core";
+
+//#region src/plugins/effects/filters/types.d.ts
+/**
+ * One uniform of a custom filter, as declared: a number is an `f32` (`float` in GLSL), `{ color }`
+ * a `0xrrggbb` hex sent as a `vec3<f32>` (`vec3`), a tuple of 2 to 4 numbers a `vecN<f32>`
+ * (`vecN`).
+ *
+ * @example
+ * ```ts
+ * const uniforms: Record<string, UniformDeclaration> = { amount: 0.5, color: { color: 0xffd700 }, offset: [2, 2] };
+ * ```
+ */
+type UniformDeclaration = number | {
+  readonly color: number;
+} | readonly [number, number] | readonly [number, number, number] | readonly [number, number, number, number];
+/**
+ * The component field a uniform declaration becomes: a number for a number and for a colour, a
+ * list of numbers for a tuple.
+ *
+ * @example
+ * ```ts
+ * type Amount = UniformValue<0.5>; // number
+ * ```
+ */
+type UniformValue<Declaration> = Declaration extends number ? number : Declaration extends {
+  readonly color: number;
+} ? number : readonly number[];
+/**
+ * The value of a filter component made by `defineFilter`: one field per uniform, then `enabled`
+ * and `order`.
+ *
+ * @example
+ * ```ts
+ * type TintValue = FilterValueOf<{ amount: number; color: { color: number } }>;
+ * // { amount: number; color: number; enabled: boolean; order: number }
+ * ```
+ */
+type FilterValueOf<Uniforms extends Record<string, UniformDeclaration>> = { -readonly [Name in keyof Uniforms]: UniformValue<Uniforms[Name]> } & {
+  enabled: boolean;
+  order: number;
+};
+/**
+ * What `defineFilter` takes besides the id. Both bodies are required, so the filter draws on
+ * WebGPU and on the WebGL fallback: `wgsl` is the WGSL fragment body only, the engine prepends the
+ * vertex stage, the input bindings and the `FilterUniforms` struct; `glsl` is its GLSL ES 3.0 twin
+ * over the same uniform names, the engine prepends the version, the inputs, `finalColor` and one
+ * `uniform` per declared uniform.
+ *
+ * @example
+ * ```ts
+ * const spec: FilterSpec<{ amount: number }> = {
+ *   wgsl: "@fragment fn mainFragment(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> { return textureSample(uTexture, uSampler, uv) * fu.amount; }",
+ *   glsl: "void main() { finalColor = texture(uTexture, vTextureCoord) * amount; }",
+ *   uniforms: { amount: 1 }
+ * };
+ * ```
+ */
+type FilterSpec<Uniforms extends Record<string, UniformDeclaration>> = {
+  /** The WGSL fragment body: `fn mainFragment` and its helpers, without the engine's header. */readonly wgsl: string;
+  /**
+   * The GLSL ES 3.0 fragment body: `void main()`, which sets `finalColor`, and its helpers, without
+   * the engine's header. It reads each uniform under its bare name: `amount`, not `fu.amount`.
+   */
+  readonly glsl: string; /** The uniforms in struct order. Default `{}`. */
+  readonly uniforms?: Uniforms; /** Render passes one apply of the filter costs, an integer of at least 1. Default `1`. */
+  readonly passes?: number; /** Pixels around the view's bounds, or the name of a number uniform whose live value they are. Default `0`. */
+  readonly padding?: number | string;
+};
+/**
+ * How one uniform travels to the GPU: its name, its WGSL type and the form it was declared in.
+ *
+ * @example
+ * ```ts
+ * const spec: UniformSpec = { name: "color", type: "vec3<f32>", form: "color", size: 3 };
+ * ```
+ */
+type UniformSpec = {
+  readonly name: string;
+  readonly type: "f32" | "vec2<f32>" | "vec3<f32>" | "vec4<f32>";
+  readonly form: "number" | "color" | "vector";
+  readonly size: number;
+};
+/**
+ * The filter a component made by `defineFilter` carries: the assembled WGSL in `source`, the
+ * assembled GLSL in `glsl`, the uniforms in struct order, the passes one apply costs and the
+ * padding.
+ *
+ * @example
+ * ```ts
+ * Tint.filter.source.includes("fn mainFragment"); // true: the WGSL, drawn on WebGPU
+ * Tint.filter.glsl.startsWith("#version 300 es"); // true: the GLSL, drawn on WebGL
+ * Tint.filter.uniforms.map(uniform => uniform.name); // ["amount", "color"]
+ * ```
+ */
+type FilterDefinition = {
+  readonly id: string; /** The assembled WGSL: the engine's header, the uniform struct, the body. */
+  readonly source: string; /** The assembled GLSL ES 3.0: the engine's header, one `uniform` per uniform, the body. */
+  readonly glsl: string;
+  readonly uniforms: readonly UniformSpec[];
+  readonly passes: number;
+  readonly padding: number | string;
+};
+/**
+ * A filter component type: the `component()` of its id, with the filter definition attached. Its
+ * numeric fields are tweenable like any component.
+ *
+ * @example
+ * ```ts
+ * const Tint: FilterComponent<{ amount: number; enabled: boolean; order: number }> =
+ *   defineFilter("fx.tint", { wgsl: tintWgsl, glsl: tintGlsl, uniforms: { amount: 0 } });
+ * Tint.componentName; // "fx.tint"
+ * ```
+ */
+type FilterComponent<Value extends object> = ComponentType<Value> & {
+  readonly filter: FilterDefinition;
+};
+/**
+ * One field of a stored filter value: a number, a switch, an asset key or a vector.
+ *
+ * @example
+ * ```ts
+ * const field: FilterField = 0.5;
+ * ```
+ */
+type FilterField = number | boolean | string | readonly number[];
+/**
+ * The stored value of any filter component, with the kind erased: the filter sync reads every
+ * kind through it.
+ */
+type FilterFields = {
+  readonly enabled: boolean;
+  readonly order: number;
+  readonly [field: string]: FilterField;
+};
+/**
+ * `Glow`: a soft halo of `color` around the opaque pixels of the view.
+ *
+ * @example
+ * ```ts
+ * const value: GlowValue = { strength: 2, distance: 10, color: 0xffffff, alpha: 1, enabled: true, order: 0 };
+ * ```
+ */
+type GlowValue = {
+  strength: number;
+  distance: number;
+  color: number;
+  alpha: number;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * `Outline`: a ring of `thickness` pixels in `color` around the opaque pixels of the view.
+ *
+ * @example
+ * ```ts
+ * const value: OutlineValue = { thickness: 2, color: 0x000000, alpha: 1, enabled: true, order: 0 };
+ * ```
+ */
+type OutlineValue = {
+  thickness: number;
+  color: number;
+  alpha: number;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * `Blur`: Pixi's blur. `quality: 0` means `config.blur.quality`; `resolution: 0` means
+ * `config.blur.phoneResolution` on a phone, otherwise 1.
+ *
+ * @example
+ * ```ts
+ * const value: BlurValue = { strength: 8, quality: 0, resolution: 0, repeatEdgePixels: true, enabled: true, order: 0 };
+ * ```
+ */
+type BlurValue = {
+  strength: number;
+  quality: number;
+  resolution: number;
+  repeatEdgePixels: boolean;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * `ColorMatrix`: brightness, saturation, contrast, hue and grayscale composed in that order.
+ * Every default is the identity.
+ *
+ * @example
+ * ```ts
+ * const value: ColorMatrixValue = { brightness: 1, saturation: 0, contrast: 0, hue: 0, grayscale: 1, enabled: true, order: 0 };
+ * ```
+ */
+type ColorMatrixValue = {
+  brightness: number;
+  saturation: number;
+  contrast: number;
+  hue: number;
+  grayscale: number;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * `Noise`: Pixi's noise with its seed always given, so two runs draw the same grain.
+ *
+ * @example
+ * ```ts
+ * const value: NoiseValue = { amount: 0.5, seed: 7, enabled: true, order: 0 };
+ * ```
+ */
+type NoiseValue = {
+  amount: number;
+  seed: number;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * `Displacement`: Pixi's displacement over the texture of an asset key.
+ *
+ * @example
+ * ```ts
+ * const value: DisplacementValue = { map: "fx.ripple", scaleX: 20, scaleY: 20, enabled: true, order: 0 };
+ * ```
+ */
+type DisplacementValue = {
+  map: string;
+  scaleX: number;
+  scaleY: number;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * `Alpha`: Pixi's alpha over the whole subtree, as one layer.
+ *
+ * @example
+ * ```ts
+ * const value: AlphaValue = { alpha: 0.5, enabled: true, order: 0 };
+ * ```
+ */
+type AlphaValue = {
+  alpha: number;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * The five built-in kinds drawn by a Pixi core filter.
+ *
+ * @example
+ * ```ts
+ * const kind: CoreKind = "blur";
+ * ```
+ */
+type CoreKind = "blur" | "colorMatrix" | "noise" | "displacement" | "alpha";
+/**
+ * Where a filter kind comes from: our or a game's shaders (`"wgsl"`, with the GLSL twin beside
+ * it), or a Pixi core filter.
+ */
+type KindSource = {
+  readonly source: "wgsl";
+  readonly definition: FilterDefinition;
+} | {
+  readonly source: "core";
+  readonly core: CoreKind;
+};
+/**
+ * A filter kind before it is registered: its id, its component and its source.
+ */
+type KindEntry = KindSource & {
+  readonly id: string;
+  readonly component: ComponentHandle<FilterFields>;
+};
+/**
+ * One registered filter kind. `index` is the registration order: the built-ins first, then the
+ * filters of every feature in feature order.
+ */
+type FilterKind = KindEntry & {
+  readonly index: number;
+};
+/**
+ * The values of the uniform group of one of our filter instances: a number per `f32`, a vector
+ * per colour and tuple. Written every frame.
+ */
+type UniformValues = Record<string, number | Float32Array>;
+/**
+ * The uniform group of one of our filter instances, as the instance writes it.
+ */
+type FilterUniforms = {
+  readonly uniforms: UniformValues;
+};
+/**
+ * The Pixi object of one kind on one view, with the passes one apply of it costs now: what the
+ * builders of `instance.ts` make before the instance gets its sort keys.
+ */
+type FilterBody = {
+  readonly kind: "wgsl";
+  readonly filter: PixiFilter;
+  readonly group: FilterUniforms | undefined;
+  readonly definition: FilterDefinition;
+  passes: number;
+} | {
+  readonly kind: "blur";
+  readonly filter: InstanceType<PixiModule["BlurFilter"]>;
+  passes: number;
+} | {
+  readonly kind: "colorMatrix";
+  readonly filter: InstanceType<PixiModule["ColorMatrixFilter"]>;
+  passes: number;
+} | {
+  readonly kind: "noise";
+  readonly filter: InstanceType<PixiModule["NoiseFilter"]>;
+  passes: number;
+} | {
+  readonly kind: "displacement";
+  readonly filter: InstanceType<PixiModule["DisplacementFilter"]>;
+  readonly sprite: PixiSprite; /** The asset key the map sprite shows now. */
+  map: string;
+  passes: number;
+} | {
+  readonly kind: "alpha";
+  readonly filter: InstanceType<PixiModule["AlphaFilter"]>;
+  passes: number;
+};
+/**
+ * The instance of one kind on one view: its Pixi object, and what it sorts by on the view, the
+ * `order` of its component (written every frame) and the `index` of its kind.
+ */
+type FilterInstance = FilterBody & {
+  order: number;
+  readonly index: number;
+};
+/**
+ * What the filter sync keeps for one entity: the kinds it carries, one instance per kind, the
+ * instances waiting to be destroyed after the next assignment, the slots last handed to
+ * `renderer.sync.filters.set`, the core kinds whose component changed this frame, and the
+ * instances of this frame in their sorted order (one array, reused every frame).
+ */
+type FilteredView = {
+  readonly kinds: Set<string>;
+  readonly instances: Map<string, FilterInstance>;
+  readonly retired: FilterInstance[];
+  assigned: readonly FilterSlot[];
+  readonly changed: Set<string>;
+  readonly placed: FilterInstance[];
+};
+//#endregion
+//#region src/plugins/effects/particles/types.d.ts
+/**
+ * An inclusive `[min, max]` range; every particle draws its own value from it.
+ *
+ * @example
+ * ```ts
+ * const lifeMs: Range = [500, 900];
+ * ```
+ */
+type Range = readonly [min: number, max: number];
+/**
+ * A value over the life of a particle, linear from its birth (`from`) to its death (`to`).
+ *
+ * @example
+ * ```ts
+ * const shrink: Curve = { from: 1, to: 0.2 };
+ * ```
+ */
+type Curve = {
+  readonly from: number;
+  readonly to: number;
+};
+/**
+ * Where a particle is born, around the origin of its emitter, in reference units. `circle` is
+ * uniform over the disc, `ring` uniform between `radius − width / 2` and `radius + width / 2`,
+ * `rect` uniform over the centred box.
+ *
+ * @example
+ * ```ts
+ * const burstRing: Shape = { kind: "ring", radius: 48, width: 16 };
+ * ```
+ */
+type Shape = {
+  readonly kind: "point";
+} | {
+  readonly kind: "circle";
+  readonly radius: number;
+} | {
+  readonly kind: "rect";
+  readonly w: number;
+  readonly h: number;
+} | {
+  readonly kind: "ring";
+  readonly radius: number;
+  readonly width: number;
+};
+/**
+ * A particle effect as data, what `defineEmitter` takes. Every field is optional except
+ * `textures` and exactly one of `burst` and `rate`. Speeds are reference units per second, angles
+ * degrees with 0 to the right and 90 down, spins radians per second.
+ *
+ * @example
+ * ```ts
+ * const stars: EmitterConfig = {
+ *   textures: ["fx.star", "fx.sparkle"], burst: 40, lifeMs: [500, 900], speed: [300, 700],
+ *   gravity: 900, drag: 0.2, shape: { kind: "circle", radius: 24 }, alpha: { from: 1, to: 0 }
+ * };
+ * ```
+ */
+type EmitterConfig = {
+  /** 1 to 16 asset keys of one atlas page; a particle picks one at random. */readonly textures: readonly string[]; /** Particles emitted once, when the component appears or its `effect` changes. */
+  readonly burst?: number; /** Particles per second while `active` is true and the entity lives. */
+  readonly rate?: number; /** Life of a particle in milliseconds. Default `[600, 1000]`. */
+  readonly lifeMs?: Range; /** Start speed in reference units per second. Default `[0, 0]`. */
+  readonly speed?: Range; /** Start direction in degrees, 0 right, 90 down. Default `[0, 360]`. */
+  readonly angle?: Range; /** Downward acceleration in reference units per second². Default `0`. */
+  readonly gravity?: number; /** Velocity lost per second, 0..1: `v *= (1 − drag) ^ seconds`. Default `0`. */
+  readonly drag?: number; /** Spin in radians per second. Default `[0, 0]`. */
+  readonly spin?: Range; /** Where particles are born around the origin. Default `{ kind: "point" }`. */
+  readonly shape?: Shape; /** Scale over life. Default `{ from: 1, to: 1 }`. */
+  readonly scale?: Curve; /** Alpha over life, 0..1. Default `{ from: 1, to: 1 }`. */
+  readonly alpha?: Curve; /** Tint over life, `0xrrggbb`, linear per channel. Default white to white. */
+  readonly tint?: Curve; /** `"world"`: particles outlive the entity. `"local"`: they move and die with it. Default `"world"`. */
+  readonly space?: "world" | "local"; /** Milliseconds simulated before the first frame, for streams, 0..5000. Default `0`. */
+  readonly prewarmMs?: number; /** Hard ceiling of live particles of one instance, 1..5000. Default `256`. */
+  readonly maxParticles?: number; /** Blend mode of the particle container. Default `"normal"`. */
+  readonly blend?: "normal" | "add";
+};
+/**
+ * An `EmitterConfig` with every default filled in. `burst` and `rate` stay as given: exactly one
+ * of them is present.
+ *
+ * @example
+ * ```ts
+ * defineEmitter("fx.steam", { textures: ["fx.puff"], rate: 12 }).config.lifeMs; // [600, 1000]
+ * ```
+ */
+type ResolvedEmitterConfig = Required<Omit<EmitterConfig, "burst" | "rate">> & Pick<EmitterConfig, "burst" | "rate">;
+/**
+ * A particle effect as `defineEmitter` returns it: frozen, registered through the `emitters` key
+ * of a feature and started by an `Emitter` component that names its id.
+ *
+ * @example
+ * ```ts
+ * const steam: EmitterDefinition = defineEmitter("fx.steam", { textures: ["fx.puff"], rate: 12 });
+ * steam.config.rate; // 12
+ * ```
+ */
+type EmitterDefinition = {
+  readonly id: string;
+  readonly config: ResolvedEmitterConfig;
+};
+/**
+ * The value of the `Emitter` component: which effect runs on the entity and whether a stream
+ * emits. `""` draws nothing.
+ *
+ * @example
+ * ```ts
+ * const value: EmitterValue = { effect: "fx.steam", active: true };
+ * ```
+ */
+type EmitterValue = {
+  effect: string;
+  active: boolean;
+};
+/**
+ * The cosmetic random source of one instance: xorshift32 over its own seed, never `Math.random`
+ * and never the model's rng.
+ */
+type Rng = {
+  /** The next number in `[0, 1)`. */next(): number; /** An integer in `[0, count)`. */
+  int(count: number): number; /** A number in `[min, max]`. */
+  between(min: number, max: number): number;
+};
+/**
+ * A Pixi particle container: what one emitter instance draws in.
+ */
+type PixiParticleContainer = InstanceType<PixiModule["ParticleContainer"]>;
+/**
+ * One particle of a container, as the container keeps it.
+ */
+type PixiParticle = PixiParticleContainer["particleChildren"][number];
+/**
+ * What one effect id bakes to on first use: the 64-entry curve tables, the reach rectangle's half
+ * side and the resolved textures. Dropped when a bundle with one of its textures leaves.
+ */
+type BakedEmitter = {
+  readonly id: string;
+  readonly config: ResolvedEmitterConfig; /** Scale per 1/64 of the life. */
+  readonly scaleTable: Float32Array; /** Alpha per 1/64 of the life, 0..1. */
+  readonly alphaTable: Float32Array; /** Tint per 1/64 of the life, packed as Pixi's `0xbbggrr`. */
+  readonly tintTable: Uint32Array; /** Half side of the box no particle leaves, in reference units. */
+  readonly reach: number;
+  readonly textures: readonly PixiTexture[]; /** The texture source of the first texture: every texture of the effect samples it. */
+  readonly source: PixiTexture["source"] | undefined; /** The largest side of the textures, in pixels. */
+  readonly maxSide: number;
+};
+/**
+ * The per-particle numbers a Pixi particle has no field for, one entry per live particle, in the
+ * order of `particleChildren`.
+ */
+type BornFields = {
+  readonly age: Float32Array;
+  readonly life: Float32Array;
+  readonly vx: Float32Array;
+  readonly vy: Float32Array;
+  readonly spin: Float32Array;
+  readonly variant: Float32Array;
+};
+/**
+ * One running effect: its container, the plugin-owned entity that carries it, the particle pool
+ * and the numbers the step needs.
+ */
+type EmitterInstance = {
+  readonly id: string;
+  readonly baked: BakedEmitter; /** The entity whose `Emitter` started it. */
+  readonly host: Entity; /** The plugin-owned entity whose `Display` is the container. */
+  readonly entity: Entity;
+  readonly container: PixiParticleContainer; /** Retired particles, reused before a new one is made. */
+  readonly pool: PixiParticle[];
+  readonly born: BornFields; /** Fraction of a particle owed to the next frame of a stream. */
+  carry: number;
+  readonly rng: Rng; /** The point the container was placed at, in root space (world space only). */
+  readonly origin: Readonly<Point>;
+  readonly space: "world" | "local"; /** Pixi's particle class, from the module the renderer loaded. */
+  readonly particleClass: PixiModule["Particle"];
+};
+declare namespace types_d_exports {
+  export { AlphaValue, BlurValue, BundleUnloaded, ColorMatrixValue, Config, CoreKind, Curve, Deps, DisplacementValue, EffectsApi, EffectsCtx, EffectsStats, EmitterConfig, EmitterDefinition, EmitterValue, FilterComponent, FilterDefinition, FilterSpec, FilterValueOf, GlowValue, KernelSlice, NoiseValue, OutlineValue, Range, ResolvedEmitterConfig, Shape, State, UniformDeclaration, UniformSpec, UniformValue };
+}
+/**
+ * effects plugin config. `maxParticles` here is the global warning line; the `maxParticles` of an
+ * emitter config caps one instance.
+ *
+ * @example
+ * ```ts
+ * createApp({
+ *   plugins: [...screen, effectsPlugin],
+ *   pluginConfigs: { effects: { maxPasses: 16, phone: false } }
+ * });
+ * ```
+ */
+type Config = {
+  /** Live particles over all instances above which one dev warning fires per crossing. */maxParticles: number; /** Render passes per frame above which one dev warning fires per crossing. */
+  maxPasses: number; /** Whether this device is a phone. `"auto"`: a coarse pointer and a short side of at most 820 CSS px, read once in `onStart`. */
+  phone: boolean | "auto";
+  /**
+   * What a `Blur` with `quality: 0` and `resolution: 0` resolves to. Shallow merge: a game that
+   * sets `blur` gives both fields.
+   */
+  blur: {
+    quality: number;
+    phoneResolution: number;
+  };
+};
+/**
+ * effects plugin state: the particle half, the filter half, and what both share.
+ */
+type State = {
+  /** Resolved in `onStart`. */phone: boolean; /** The `emitters` of every feature, read in `onStart`. */
+  emitters: Map<string, EmitterDefinition>; /** Per effect id, built on first use. */
+  baked: Map<string, BakedEmitter>; /** Host entity to its running instance. */
+  instances: Map<Entity, EmitterInstance>; /** World-space instances whose host left, stepped until empty. */
+  orphans: Set<EmitterInstance>; /** Ordinal of the next instance: the cosmetic seed. */
+  seedCounter: number; /** Live particles after the last step. */
+  particles: number; /** Filter kinds whose shader failed the dev check on the running backend. */
+  broken: Set<string>; /** The filter kinds, built-ins first, then the filters of every feature. */
+  kinds: Map<string, FilterKind>; /** The dev shader check per kind; `broken` holds the failed ones. */
+  checks: Map<string, "pending" | "ok">; /** Entity to the filters the sync keeps for it. */
+  views: Map<Entity, FilteredView>; /** Keys of the one-shot warnings: `"emitter:fx.x"`, `"texture:board.cell"`, `"atlas:fx.x"`. */
+  warned: Set<string>; /** Whether each budget warning is in force, so a crossing warns once. */
+  over: {
+    particles: boolean;
+    passes: boolean;
+    fullScreen: boolean;
+  }; /** The teardown closure, the two systems and the world hooks. */
+  removers: Array<() => void>;
+};
+/**
+ * What `app.effects.stats()` answers: live particles, running emitter instances, filter instances
+ * on views, and the render passes of the frame as the renderer counts them.
+ *
+ * @example
+ * ```ts
+ * const stats: EffectsStats = { particles: 120, emitters: 3, filters: 25, renderPasses: 49 };
+ * ```
+ */
+type EffectsStats = {
+  /** Live particles over every instance and orphan after the last step. */particles: number; /** Running instances plus the orphans still flying. */
+  emitters: number; /** Filter instances over every view. */
+  filters: number; /** `renderer.sync.renderPasses()`, read at call time. */
+  renderPasses: number;
+};
+/**
+ * effects plugin API, `app.effects`. Everything a game does with effects is data on entities;
+ * the API only counts.
+ *
+ * @example
+ * ```ts
+ * // A test waits for a merge burst to land before it compares the board.
+ * while (app.effects.stats().particles > 0) app.time.step(16);
+ * app.effects.stats().particles; // 0
+ * ```
+ */
+type EffectsApi = {
+  /**
+   * Counts what runs now. `renderPasses` is the renderer's own number, read at call time; the
+   * others are the plugin's. Headless every number is 0.
+   *
+   * @returns A fresh object: live particles, emitter instances with orphans, filter instances
+   *   and render passes.
+   * @example
+   * ```ts
+   * // After the board rests: one steam stream, 24 enabled glows on 24 views, one disabled blur.
+   * app.effects.stats();
+   * // { particles: 18, emitters: 1, filters: 25, renderPasses: 49 }: 1 + 24 × (1 + 1), the disabled blur costs 0
+   * ```
+   */
+  stats(): EffectsStats;
+};
+/**
+ * Resolved dependency APIs.
+ */
+type Deps = {
+  flow: Api;
+  world: Api$1;
+  renderer: Api$2;
+  assets: Api$3;
+  anim: AnimApi;
+};
+/**
+ * What the kernel context offers before the deps are attached. `effects` owns no event, so
+ * `emit` is the kernel's and never called here.
+ */
+type KernelSlice = PluginCtx<Config, State> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context shared by both modules: the kernel slice plus the resolved deps.
+ */
+type EffectsCtx = KernelSlice & {
+  readonly deps: Deps;
+};
+/**
+ * Payload of the `assets:bundle-unloaded` hook: `keys` names every texture that is gone.
+ */
+type BundleUnloaded = Events["assets:bundle-unloaded"];
+//#endregion
+export { NoiseValue as _, types_d_exports as a, EmitterValue as c, ColorMatrixValue as d, DisplacementValue as f, GlowValue as g, FilterValueOf as h, State as i, AlphaValue as l, FilterSpec as m, EffectsApi as n, EmitterConfig as o, FilterComponent as p, EffectsStats as r, EmitterDefinition as s, Config as t, BlurValue as u, OutlineValue as v, UniformDeclaration as y };

package/llms.txt

@@ -373,7 +373,7 @@ A screen is a projection whose `view` returns JSX. The game's `tsconfig.json` se
 - `tr(key, params?)` returns a frozen `Message` `{ key, params }`; no locale is read at the call site. Strings live in `features/<feature>/strings/<locale>.json` as ICU MessageFormat 1 (`{n, plural, one {# order} other {# orders}}`, `select`, `selectordinal`, `number`, `date`, `time`; no skeletons, no `currency`). `bun run assets:keys` compiles them. `app.i18n`: `locale()`, `setLocale(locale)` (async, emits `i18n:locale-changed`), `format(message, locale?)` returns `Part[]`, `plain(message)` returns a string, `has(key)`, `locales()`. Config: `locale: "en"`, `fallback: "en"`, `locales: {}`.
 - Text: `Text` component, `label({ text, style, at, anchor? })` for board text in a projection view, `defineTextStyles({ "hud.digits": { font, size, fill, bold?, italic?, stroke?, strokeWidth?, letterSpacing?, align?, wrap?, digits? } })` under the feature's `textStyles` key. Tags inside a string: `<b>`, `<i>`, `<color=#rrggbb>`, `<icon=key>`, `\<`, `\n`. Built-in styles `body` and `digits` from config `fonts: { body: "ui.font-body", digits: "ui.font-digits" }`. `app.text.measure(content, style)` gives the same numbers in a browser and in Bun.
 - Animation is data: `defineAnimation(id, { slots: { name: type<Anim.Target>() }, build: (slots, { at }) => Step })`. Steps: `sequence(...)`, `parallel(...)`, `stagger(items, ms, item => Step)`, `tween(target, Component, to, { ms, ease?, delayMs?, additive? })`, `set(target, Component, patch)`, `wait(ms)`, `mark(name)`, `frames(target, { keys, fps, loop? })`, `sfx(key, { bus? })`, `haptic(kind)`, `use(animation, slots, tools?)`, `spawn` (a temporary entity, flying coins, that the timeline despawns when it ends; see the anim README). `Frames({ keys, fps, loop, playing })` is a component that walks a sprite through its textures for the entity's whole life. A target is `{ projection, key }` or an entity. A node plays it with `await fx(play(animation, slots))`; in fast mode it finishes at once. `defineMotion({ states, transition?, on: { enter?, exit?, change? } })` builds the enter, exit and change hooks for a projection or the `motion` prop of a tag. Events `anim:mark` `{ animation, mark }` and `anim:finished` `{ animation }`. Config `maxTracks: 2000`.
-- Audio is opt-in: `plugins: [...screen, audioPlugin]`. `fx(sfx("orders.complete"))` resolves when the sound started. `await fx(music("board.theme"))` cross-fades; `music(null)` fades out; a scene's `music` key switches the track on `scenes:changed`. Buses `master`, `music`, `sfx`. Volumes come from the committed player: config `volumes: player => (player as Player).settings.audio`, applied on every `model:committed`. `app.audio`: `setVolume(bus, value)`, `volume(bus)`, `mute(bus, on)`, `unlocked()`, `journal()` (the last started sounds, empty unless config `journal` is above 0). Config: `buses: { master: 1, music: 0.6, sfx: 1 }`, `musicFadeMs: 600`, `volumes`, `context`, `journal: 0`, `music: "decode" | "stream"` default `"decode"` (gapless buffer; `"stream"` is an `<audio>` element, less memory, a gap at every loop), `session: "ambient" | "playback" | "auto"` default `"ambient"` (iOS only: ambient mixes with other apps and obeys the silent switch). Without `audio` every `sfx` and `music` effect resolves `undefined` at once, so the same node runs in a game with no sound.
+- Audio is opt-in: `plugins: [...screen, audioPlugin]`. `fx(sfx("orders.complete"))` resolves when the sound started. `await fx(music("board.theme"))` cross-fades; `music(null)` fades out; a scene's `music` key switches the track on `scenes:changed`. Buses `master`, `music`, `sfx`. Volumes come from the committed player: config `volumes: player => (player as Player).settings.audio`, applied on every `model:committed`. `app.audio`: `setVolume(bus, value)`, `volume(bus)`, `mute(bus, on)`, `muted(bus)`, `unlocked()`, `journal()` (the last started sounds, empty unless config `journal` is above 0). Config: `buses: { master: 1, music: 0.6, sfx: 1 }`, `musicFadeMs: 600`, `volumes`, `context`, `journal: 0`, `music: "decode" | "stream"` default `"decode"` (gapless buffer; `"stream"` is an `<audio>` element, less memory, a gap at every loop), `session: "ambient" | "playback" | "auto"` default `"ambient"` (iOS only: ambient mixes with other apps and obeys the silent switch). Without `audio` every `sfx` and `music` effect resolves `undefined` at once, so the same node runs in a game with no sound.
 - `app.ui`: `tree()` the live screen as plain data, `find(key)` the entity of a keyed element, `fill(key, value)` types into the text field with that `key`, `lint()` tap targets under `tapTargetPt` (default `44`), text that overflows in some locale, absolute elements without `reason`. Config: `tapTargetPt: 44`, `breakpoints: { tall: 2, wide: 1.5 }`. `ui` emits nothing.
 
 ```tsx
@@ -466,8 +466,8 @@ A plugin that owns a resource stores it in its state and frees it in `onStop: ({
 
 Two subpaths, neither on the root (V4). An editor, MCP tools and e2e scripts reach a running game through them; `docs/doors.md` in the engine repository has the full catalogue.
 
-- `@moku-labs/game/inspect`: `read(app, source, input?)` reads once; `watch(app, source, input, fn)` reads on the `signals` phase when the source changes and returns the stop function; `defineSource`; the frozen catalogue `sources`; the types `Source`, `InputSchema`, `InputOf`. Every source only reads, so the door is safe in a production build. Keys of `sources`: `graph`, `position`, `history`, `tainted`, `cheats`, `model`, `entities`, `projections`, `ui`, `locate`, `render`, `sounds`, `effects`, `assets`, `log`, `explain`, `diff`, `schema`, `at`; their ids are `game.<key>`. `locate` takes `{ key }` (a ui element) or `{ target }` (a view by projection key) and answers its box in CSS px, the numbers Playwright clicks. `at` takes `{ x, y }` in CSS px and lists the views under that point, topmost first. `explain` takes `{ entity }` and answers that entity in full, `undefined` for a stale id. `diff` takes `{ from, to }` frames and answers what changed per entity; it throws in a production build and for a frame outside the last 120. `schema` lists every component and tag type the world met, with the JSON kind of each field. `sounds` throws `[game] The source game.sounds needs audioPlugin.` and `effects` throws `[game] The source game.effects needs effectsPlugin.` when that plugin is not installed; the editor lists such a source as not installed.
-- `@moku-labs/game/control`: `run(app, command, input?)` resolves `{ value, state }`, `state` being `{ path, frame, tainted }`; `defineCommand`; `controlRefused`; the frozen catalogue `commands`; the types `Command`, `Ran`. Keys of `commands`: `answer`, `tap`, `drag`, `key`, `fill`, `walk`, `bookmark`, `restore`, `step`, `pause`, `resume`, `capture`, `debug`, `reducedMotion`, `timeScale`, `trace`. `capture` resolves `{ png }`, and `{ png, legend }` with `legend: true`; `undefined` while the renderer is inert. `timeScale` takes `{ scale }`; 0 freezes game time while the frames keep running. `trace` takes `{ path }`, a list of views by projection key, and answers whether the gate took the answer.
+- `@moku-labs/game/inspect`: `read(app, source, input?)` reads once; `watch(app, source, input, fn)` reads on the `signals` phase when the source changes and returns the stop function; `defineSource`; the frozen catalogue `sources`; the types `Source`, `InputSchema`, `InputOf`. Every source only reads, so the door is safe in a production build. Keys of `sources`: `graph`, `position`, `history`, `tainted`, `cheats`, `model`, `entities`, `projections`, `ui`, `locate`, `render`, `sounds`, `audioMuted`, `effects`, `assets`, `log`, `explain`, `diff`, `schema`, `at`; their ids are `game.<key>`. `locate` takes `{ key }` (a ui element) or `{ target }` (a view by projection key) and answers its box in CSS px, the numbers Playwright clicks. `at` takes `{ x, y }` in CSS px and lists the views under that point, topmost first. `explain` takes `{ entity }` and answers that entity in full, `undefined` for a stale id. `diff` takes `{ from, to }` frames and answers what changed per entity; it throws in a production build and for a frame outside the last 120. `schema` lists every component and tag type the world met, with the JSON kind of each field. `audioMuted` answers whether the master bus is muted. `sounds` throws `[game] The source game.sounds needs audioPlugin.`, `audioMuted` throws `[game] The source game.audioMuted needs audioPlugin.` and `effects` throws `[game] The source game.effects needs effectsPlugin.` when that plugin is not installed; the editor lists such a source as not installed.
+- `@moku-labs/game/control`: `run(app, command, input?)` resolves `{ value, state }`, `state` being `{ path, frame, tainted }`; `defineCommand`; `controlRefused`; the frozen catalogue `commands`; the types `Command`, `Ran`. Keys of `commands`: `answer`, `tap`, `drag`, `key`, `fill`, `walk`, `bookmark`, `restore`, `step`, `pause`, `resume`, `capture`, `debug`, `reducedMotion`, `timeScale`, `mute`, `trace`. `capture` resolves `{ png }`, and `{ png, legend }` with `legend: true`; `undefined` while the renderer is inert. `timeScale` takes `{ scale }`; 0 freezes game time while the frames keep running. `mute` takes `{ muted }`, mutes the master bus and answers the flag. Without `audioPlugin` it throws `[game] The command game.mute needs audioPlugin.` `trace` takes `{ path }`, a list of views by projection key, and answers whether the gate took the answer.
 - Commands run in dev builds only. Only `__MOKU_GAME_DEV__ === true` turns the dev build on: a bundler `define` (`true` in dev, `false` in production), `globalThis.__MOKU_GAME_DEV__ = true` in the dev entry, or `vi.stubGlobal("__MOKU_GAME_DEV__", true)` in a test. Otherwise `run` throws `[game] Control commands run in dev builds only.`
 - A command's effect is `read`, `route`, `cosmetic`, `cheat` or `raw`. A `cheat` or `raw` command taints the session and is journaled; read it with `sources.tainted` and `sources.cheats`. Of the base commands only `restore` is `raw`.
 - A game's own: `defineSource({ id, title, input, changes, read })` with `changes` `"frame"`, `"commit"` or `"edge"`, and `defineCommand({ id, title, input, effect, run })`. The id is camelCase words joined by dots, at least two: `dice.rolls`. An input schema maps field names to `"string"`, `"number"`, `"boolean"` or `"json"`; a trailing `?` makes one optional. A command body starts with `if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();`. Keep them in `.dev` modules that only the dev entry and the tests import.