Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

7.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { CppRegistry } from '../wasm';
import type { EngineApi } from '../ecs/bridge/engineApi';
import type { Entity } from '../types';
import { defineResource } from '../ecs/resource';
import { ParticleCollisionBridge, type ParticleQueryResolver } from './ParticleCollisionBridge';
import type { ParticleCollisionBudget, ParticleCollisionEventPayload, ParticleCollisionStats } from './collision';

/**
 * Per-app particle API. Wraps the C++ registry-scoped particle system
 * so two App instances (e.g. editor tabs previewing different scenes)
 * can drive independent simulations without cross-talk.
 *
 * Consumed as a resource: declare `Res(Particle)` as a system param, or
 * grab it with `app.getResource(Particle)` outside ECS code.
 */
export class ParticleAPI {
    private readonly module_: NonNullable<EngineApi>;
    private readonly registry_: CppRegistry;
    private readonly collisions_: ParticleCollisionBridge;

    /** @param module whichever engine core is present — the wasm module on the web,
     *  the native host's bindings on a device (see ecs/engineApi.ts). */
    constructor(module: NonNullable<EngineApi>, registry: CppRegistry, resolve?: ParticleQueryResolver) {
        this.module_ = module;
        this.registry_ = registry;
        this.collisions_ = new ParticleCollisionBridge(module,registry,resolve);
    }

    update(dt: number): void {
        this.collisions_.update(dt);
    }

    /** Contacts published by the last completed update, in project world units. */
    get collisionEvents(): readonly ParticleCollisionEventPayload[] { return this.collisions_.events; }
    /** Per-emitter counters from the last update, including fallback reasons. */
    get collisionStats(): readonly ParticleCollisionStats[] { return this.collisions_.stats; }
    /** Provider errors are visible alongside the unavailable/fallback counters. */
    get collisionError(): string | null { return this.collisions_.error; }
    /** Global App caps, independent of each emitter's smaller limits. */
    setCollisionBudget(budget: Partial<ParticleCollisionBudget>): void {
        for (const key of ['queries','events'] as const) {
            const value=budget[key];
            if (value!==undefined) this.collisions_.budget[key]=Number.isFinite(value)?Math.max(0,Math.min(key==='queries'?65536:16384,Math.floor(value))):0;
        }
    }
    /** Draw bounded hit normals without enabling gameplay collision events. */
    get debugNormals(): boolean { return this.collisions_.debug; }
    set debugNormals(enabled: boolean) { this.collisions_.debug=enabled; }
    /** @internal */
    get collisionContacts(): readonly ParticleCollisionEventPayload[] { return this.collisions_.contacts; }

    play(entity: Entity): void {
        this.module_.particle_play?.(this.registry_, entity as number);
    }

    stop(entity: Entity): void {
        this.module_.particle_stop?.(this.registry_, entity as number);
    }

    reset(entity: Entity): void {
        this.module_.particle_reset?.(this.registry_, entity as number);
    }

    /**
     * Spawn `count` of `entity`'s particles at a world point, now — an impact's sparks, a muzzle's flash — without moving
     * the emitter or replaying it (Unity's `ParticleSystem.Emit`). The emitter's own settings make them; its shape's +Y (a
     * cone's or hemisphere's axis) points along `options.normal` when given, else as the entity is turned, and
     * `options.velocity` is added to each. CPU-simulated emitters only. Returns how many were spawned.
     */
    emitAt(entity: Entity, count: number, position: { x: number; y: number; z: number },
           options: { normal?: { x: number; y: number; z: number }; velocity?: { x: number; y: number; z: number } } = {}): number {
        const n = options.normal ?? { x: 0, y: 0, z: 0 }, v = options.velocity ?? { x: 0, y: 0, z: 0 };
        return this.module_.particle_emitAt?.(this.registry_, entity as number, Math.max(0, Math.floor(count)),
            position.x, position.y, position.z, n.x, n.y, n.z, v.x, v.y, v.z) ?? 0;
    }

    getAliveCount(entity: Entity): number {
        return this.module_.particle_getAliveCount?.(entity as number) ?? 0;
    }

    /**
     * Upload an entity's baked color-over-life LUT (an N×4 RGBA Float32Array) so
     * the sim samples it instead of start/end + easing; pass null to clear. The
     * data is copied into the wasm heap for the call, then freed.
     */
    setColorLut(entity: Entity, lut: Float32Array | null): void {
        this.uploadLut(this.module_.particle_set_color_lut, entity, lut, 4);
    }

    /** Upload an entity's baked size-over-life multiplier LUT (an N-scalar
     *  Float32Array), or null to clear. */
    setSizeLut(entity: Entity, lut: Float32Array | null): void {
        this.uploadLut(this.module_.particle_set_size_lut, entity, lut, 1);
    }

    /**
     * Speed-over-life multiplier. Scales how fast a particle travels along the
     * trajectory it already has — gravity, damping and noise still accumulate
     * into its velocity, so this is not a second force system.
     */
    setSpeedLut(entity: Entity, lut: Float32Array | null): void {
        this.uploadLut(this.module_.particle_set_speed_lut, entity, lut, 1);
    }

    /**
     * Burst schedule: each burst releases `count` particles once the emitter has been emitting for `time` seconds
     * (counted from the end of its start delay). A looping emitter repeats the schedule every duration. Null clears.
     */
    setBursts(entity: Entity, bursts: readonly { time: number; count: number }[] | null): void {
        const lut = bursts && bursts.length > 0 ? Float32Array.from(bursts.flatMap((b) => [b.time, b.count])) : null;
        this.uploadLut(this.module_.particle_set_bursts, entity, lut, 2);
    }

    // Copy a Float32Array into the core's heap and hand its offset + element count
    // (length / `stride`) to the C++ setter, then free; null/empty clears. The heap
    // is wasm linear memory on the web and the host's arena on a device — the same
    // call either way (see ecs/nativeHeap.ts).
    private uploadLut(
        fn: ((entity: number, ptr: number, count: number) => void) | undefined,
        entity: Entity,
        lut: Float32Array | null,
        stride: number,
    ): void {
        if (!fn) return;
        if (!lut || lut.length === 0) {
            fn(entity as number, 0, 0);
            return;
        }
        const { _malloc: malloc, _free: free } = this.module_;
        if (!malloc || !free || !this.module_.HEAPF32) return;   // a core with no heap marshals nothing
        // A caller may borrow the same heap that allocation is about to detach.
        const source = lut.buffer === this.module_.HEAPF32.buffer ? lut.slice() : lut;
        const ptr = malloc(source.length * 4);
        try {
            // Allocation can grow WASM memory and detach the previous heap view.
            this.module_.HEAPF32!.set(source, ptr / 4);
            fn(entity as number, ptr, source.length / stride);
        } finally {
            free(ptr);
        }
    }
}

/** Resource handle for the per-app particle API. */
export const Particle = defineResource<ParticleAPI>(null!, 'Particle');