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.7 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    Tween.ts
 * @brief   Property tween API wrapping C++ TweenSystem
 *
 * `TweenAPI` is per-app — each `App` owns an instance via the `Tween`
 * resource. Consume as `Res(Tween)` in a system or
 * `app.getResource(Tween)` outside ECS code.
 */

import { TweenTarget } from '../wasm/wasm.generated';

import type { Entity } from '../types';
import type { CppRegistry } from '../wasm';
import type { EngineApi } from '../ecs/bridge/engineApi';
import { defineResource } from '../ecs/resource';
import { EasingType } from './Easing';
import { LoopMode, TweenState, type TweenOptions } from './TweenTypes';
import { ValueTweenManager, ValueTweenHandle } from './ValueTween';
import {
    TweenGroup,
    TweenSequence,
    TweenCompositionManager,
    type Completable,
    type TweenFactory,
} from './TweenGroup';

// Re-export so consumers can reach shared types via the Tween entry point
export { EasingType, type BezierPoints } from './Easing';
export { TweenState, LoopMode, type TweenOptions } from './TweenTypes';
export { ValueTweenHandle } from './ValueTween';

// =============================================================================
// Tween Target (wire protocol — generated from
// src/esengine/animation/TweenData.hpp::TweenTarget, whose order and
// numeric values are the boundary contract).
// =============================================================================

/**
 * The 13 properties the C++ TweenSystem can drive directly.
 *
 * NOTE ON THE RELATIONSHIP TO `AnimTargetField`: Timeline uses the
 * wider, code-generated `AnimTargetField` enum (33 entries) because
 * it composes smaller setters on top of `AnimApplicator`. TweenTarget
 * is intentionally narrower — just the common property tweens that
 * have a fast C++ fast-path. Unifying the two would require
 * `anim_createTween` on the WASM boundary to accept AnimTargetField
 * values directly and an extended TWEEN_TO_ANIM_FIELD map in
 * TweenSystem.cpp. That's a larger cross-layer change tracked
 * separately; for now TweenTarget is the stable subset.
 *
 * If you need to tween a field not in this list (e.g. UINode.insetLeft.value),
 * use `tween.value(...)` with a callback that writes the field yourself,
 * or drive it via Timeline.
 */
export { TweenTarget };

// =============================================================================
// Tween Handle (fluent builder)
// =============================================================================

/**
 * Whichever engine core drives the tweens: the wasm module on the web, the native
 * host's bindings on a device (see ecs/engineApi.ts). Every call is optional-chained
 * — a core built without the tween system leaves a tween inert rather than throwing,
 * the same way particles and trails already treat an absent entry point.
 */
export type AnimCore = NonNullable<EngineApi>;

export class TweenHandle {
    private readonly module_: AnimCore;
    private readonly registry_: CppRegistry;
    private readonly valueManager_: ValueTweenManager;
    readonly entity: Entity;

    constructor(
        module: AnimCore,
        registry: CppRegistry,
        valueManager: ValueTweenManager,
        entity: Entity,
    ) {
        this.module_ = module;
        this.registry_ = registry;
        this.valueManager_ = valueManager;
        this.entity = entity;
    }

    get state(): TweenState {
        return (this.module_.anim_getTweenState?.(this.registry_, this.entity)
            ?? TweenState.Completed) as TweenState;
    }

    bezier(p1x: number, p1y: number, p2x: number, p2y: number): this {
        this.module_.anim_setTweenBezier?.(this.registry_, this.entity, p1x, p1y, p2x, p2y);
        return this;
    }

    then(next: TweenHandle | ValueTweenHandle): this {
        if (next instanceof ValueTweenHandle) {
            this.valueManager_.registerCppSequence(this.entity, next.id);
            return this;
        }
        this.module_.anim_setSequenceNext?.(this.registry_, this.entity, next.entity);
        return this;
    }

    pause(): void {
        this.module_.anim_pauseTween?.(this.registry_, this.entity);
    }

    resume(): void {
        this.module_.anim_resumeTween?.(this.registry_, this.entity);
    }

    cancel(): void {
        this.module_.anim_cancelTween?.(this.registry_, this.entity);
    }
}

// =============================================================================
// Per-app Tween API
// =============================================================================

export class TweenAPI {
    private readonly module_: AnimCore;
    private readonly registry_: CppRegistry;
    private readonly valueManager_: ValueTweenManager;
    private readonly compositionManager_: TweenCompositionManager;
    private updating_ = false;

    constructor(module: AnimCore, registry: CppRegistry) {
        this.module_ = module;
        this.registry_ = registry;
        this.valueManager_ = new ValueTweenManager(module, registry);
        this.compositionManager_ = new TweenCompositionManager();
    }

    to(
        entity: Entity,
        target: TweenTarget,
        from: number,
        to: number,
        duration: number,
        options?: TweenOptions,
    ): TweenHandle {
        const easing = options?.easing ?? EasingType.Linear;
        const delay = options?.delay ?? 0;
        const loop = options?.loop ?? LoopMode.None;
        const loopCount = options?.loopCount ?? 0;

        // No tween system in this core → an inert handle (its state reads Completed).
        const tweenEntity = (this.module_.anim_createTween?.(
            this.registry_, entity, target, from, to, duration,
            easing, delay, loop, loopCount,
        ) ?? 0) as Entity;

        return new TweenHandle(this.module_, this.registry_, this.valueManager_, tweenEntity);
    }

    value(
        from: number,
        to: number,
        duration: number,
        callback: (value: number) => void,
        options?: TweenOptions,
    ): ValueTweenHandle {
        const id = this.valueManager_.create(from, to, duration, callback, options);
        return new ValueTweenHandle(this.valueManager_, id);
    }

    cancel(tweenHandle: TweenHandle): void {
        this.module_.anim_cancelTween?.(this.registry_, tweenHandle.entity);
    }

    cancelAll(entity: Entity): void {
        this.module_.anim_cancelAllTweens?.(this.registry_, entity);
    }

    update(deltaTime: number): void {
        if (this.updating_) return;
        this.updating_ = true;
        try {
            this.module_.anim_updateTweens?.(this.registry_, deltaTime);
            this.valueManager_.update(deltaTime);
            this.compositionManager_.update();
        } finally { this.updating_ = false; }
    }

    // ---- Composition builders -------------------------------------------------

    parallel(tweens: Completable[]): TweenGroup {
        const group = new TweenGroup(tweens);
        this.compositionManager_.add(group);
        return group;
    }

    sequence(factories: TweenFactory[]): TweenSequence {
        const seq = new TweenSequence(factories);
        this.compositionManager_.add(seq);
        return seq;
    }

    delay(seconds: number): ValueTweenHandle {
        const id = this.valueManager_.create(0, 0, seconds, () => {});
        return new ValueTweenHandle(this.valueManager_, id);
    }

    /** @internal test hook — how many groups/sequences are still being polled */
    get activeCompositionCount(): number {
        return this.compositionManager_.activeCount;
    }

    /** @internal shutdown hook for plugin cleanup */
    clear(): void {
        this.compositionManager_.clear();
    }
}

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