API

The runtime surface from @pylinka/core. Hot-path methods (update, set, setEmitterPosition, spawnBurst) allocate nothing.

createPylinka()

Create a project-level runtime from a project document.

function createPylinka(
  project: PylinkaProject,
  opts: CreateOptions,
): Promise<PylinkaRuntime>

CreateOptions

PylinkaRuntime

interface PylinkaRuntime {
  readonly systems: Record<string, ParticleSystemView>;  // keyed by System.name
  readonly params: KnobBus;                               // project-wide fan-out
  update(dtSeconds: number): void;                        // once per rAF tick
  destroy(): void;
}

ParticleSystemView

A PixiJS container. Add view to a static layer (see Core concepts).

interface ParticleSystemView {
  readonly view: Container;
  readonly params: KnobBus;
  update(dtSeconds: number): void;          // no-op if driven via the runtime
  setEmitterPosition(x: number, y: number): void;
  follow(target: Container): void;
  unfollow(): void;
  spawnBurst(count: number): void;
  restart(): void;                          // pool + scheduler reset (+ prewarm)
  readonly stats: { aliveCount: number; overflowCount: number; gpuMs: number | null };
  destroy(): void;
}

stats fields are plain numbers refreshed asynchronously — reading them never triggers a GPU readback.

KnobBus

interface KnobBus {
  set(name: string, x: number, y?: number, z?: number, w?: number): void;  // O(1), alloc-free
  get(name: string): number;   // .x component
}

Single-system helper

When you only need one system, skip the project wrapper:

function createParticleSystem(
  bundle: SystemBundle,
  opts: CreateOptions,
): Promise<ParticleSystemView>

Device loss

WebGPU device loss is routine on mobile. Pylinka re-acquires the device, rebuilds pipelines from retained compiled sources (no graph recompile), resets pools, and fires onDeviceRestored so you can re-trigger ambient effects.