ParticlesHandle

Reached in a behaviour as ctx.particles.

Signature

export interface ParticlesHandle {
  /**
   * One-shot emit of a preset at a point, with parameter overrides in `@argus/gameplay`'s `ParticleParams`
   * names: `rate`, `burst`, `lifetime` `[min, max]` s, `speed` `[min, max]` m/s, `size` `[start, end]` m,
   * `color` / `colorEnd` hex, `opacity` `[start, end]`, `gravity` (m/s² along -Y: positive falls), `drag`,
   * `spreadDeg`, `direction`, `blend` (`"alpha"` | `"additive"`), `spin` rad/s, `maxParticles`. Each key
   * applies on its own; one the engine does not take is logged once and ignored.
   */
  emit(preset: ParticlePreset, at: Vec3, params?: Record<string, unknown>): void
  /**
   * A one-shot instance of a particle effect (docs/VFX.md) at a point, removed when it has finished.
   * `effect` is a key of `scene.assets` whose kind is `"effect"`, or `"builtin:smoke"` (and the other
   * presets: `fire`, `sparks`, `dust`, `steam`, `drips`, `debris`, `glow`). `params` sets the effect's
   * declared params. An effect the scene did not load is ignored with a `particles-effect-unknown` warning.
   * @since 0.6.1
   */
  play(effect: string, at: Vec3, params?: Record<string, ParticleParamValue>): void
  /**
   * Sets a param of an effect instance: the calling entity's own `particles` component, or `target`'s
   * (an entity id or handle). Takes effect on the next tick. False (with a `particles-param-unknown`
   * warning, once) when there is no such instance, the effect declares no such param, or the value does
   * not fit its type.
   * @since 0.6.1
   */
  setParam(name: string, value: ParticleParamValue, target?: string | EntityHandle): boolean
  /**
   * Spawns `count` extra particles now on every emitter of an effect instance (the calling entity's, or
   * `target`'s), or only on the emitter named `emitter`, on top of its rate and bursts. Capped by each
   * emitter's capacity. False when there is no such instance or emitter.
   * @since 0.6.1
   */
  burst(count: number, target?: string | EntityHandle, emitter?: string): boolean
}

Import: import type { ParticlesHandle } from "@argus/api"

Members

Example

The tested fixture fixtures/recipes/many-entities/scenes/behaviors/beacon.ts.

import type { Behavior } from "@argus/api"

/** A beacon: counts the drones that touch it. Only this beacon hears its touches (`emitTo`). */
interface State {
  touches: number
}

export default {
  init(ctx) {
    ctx.state.touches ??= 0
  },
  onEvent(ctx, ev) {
    if (ev.name === "touched") ctx.state.touches += 1
  },
} satisfies Behavior<State>