hzengine-core 0.1.2-dev

package/src/plugins/transform/animation.ts

@@ -0,0 +1,542 @@
+/**
+ * animation.js
+ * @description A library for providing multi-track animations for HZEngine. 一个用于在HZEngine中提供简单动画的库
+ * @date 2024/10/2
+ * @author CuberQAQ
+ */
+
+export class Animation<P extends Profile.PropsType = unknown> {
+  normalizedProfile: Profile.Track<P>;
+  initProps: Partial<P> = {};
+  activeRootTrack: ActiveTrackNode<P> | null = null;
+  lastTime: number = 0;
+  public onFrame: ((props: Partial<P>) => void) | null = null;
+  public onEnd: (() => void) | null = null;
+  customWrappers: Record<string, Wrapper> = {};
+
+  constructor(profile: Profile<P>, options?: Animation.Options<P>) {
+    this.normalizedProfile = Profile.normalize(profile);
+    console.log(`Animation: ${JSON.stringify(profile)}`);
+
+    if (options) {
+      options.initProps && (this.initProps = options.initProps);
+      options.wrappers && (this.customWrappers = options.wrappers);
+    }
+  }
+
+  public onStop: ((animation: Animation<P>) => void) | null = null;
+
+  serialize(): Animation.Serialized {
+    return {
+      normalizedProfile: this.normalizedProfile,
+      initProps: this.initProps,
+      activeRootTrack: this.activeRootTrack?.serialize(),
+      lastTime: this.lastTime,
+    };
+  }
+  static unserialize(
+    serialized: Animation.Serialized,
+    wrappers?: Record<string, Wrapper>
+  ): Animation<unknown> {
+    let profile = serialized.normalizedProfile;
+    let animation = new Animation(profile, {
+      initProps: serialized.initProps,
+      wrappers,
+    });
+    animation.lastTime = serialized.lastTime;
+    serialized.activeRootTrack &&
+      (animation.activeRootTrack = ActiveTrackNode.unserialize(
+        animation,
+        serialized.activeRootTrack
+      ));
+    return animation;
+  }
+
+  timerCb(): void {}
+
+  init(): void {
+    this.activeRootTrack = new ActiveTrackNode(this, {
+      accessKeys: [],
+      index: 0,
+      initProps: this.initProps,
+    });
+  }
+
+  goto(time: number) {
+    if (!this.activeRootTrack) {
+      this.init();
+    }
+    if (time < 0) time = 0;
+    if (time < this.lastTime) {
+      this.init(); // reset the tracknode
+      try {
+        this.activeRootTrack!.step(time);
+      } catch (e) {
+        console.log(e);
+        this.activeRootTrack!.status = ActiveTrackNode.Status.Pause;
+      }
+      if (this.activeRootTrack!.status === ActiveTrackNode.Status.Pause) {
+        if (this.onEnd) this.onEnd();
+      }
+    } else {
+      if (this.activeRootTrack!.status !== ActiveTrackNode.Status.Pause) {
+        try {
+          this.activeRootTrack!.step(time - this.lastTime);
+        } catch (e) {
+          console.log(e);
+          this.activeRootTrack!.status = ActiveTrackNode.Status.Pause;
+        }
+      }
+    }
+    this.lastTime = time;
+
+    if (this.onFrame) {
+      // console.log("on frame", JSON.stringify(this.calcProps()));
+      this.onFrame(this.calcProps());
+    }
+
+    if (this.activeRootTrack!.status === ActiveTrackNode.Status.Pause) {
+      if (this.onEnd) this.onEnd();
+    }
+  }
+
+  step(delta_time: number) {
+    this.goto(this.lastTime + delta_time);
+  }
+
+  calcProps(): Partial<P> {
+    return this.activeRootTrack!.calcProps();
+  }
+
+  reverse(): void {}
+
+  stop(): void {}
+
+  _accessProfile(accessKeys: string[]): unknown {
+    let section: any = this.normalizedProfile;
+    for (let i = 0; i < accessKeys.length; i++) {
+      section = section[accessKeys[i]];
+    }
+    return section;
+  }
+
+  _getWrapper(wrapper: string | Wrapper | undefined): Wrapper {
+    if (typeof wrapper === "string") {
+      return (
+        this.customWrappers[wrapper] ??
+        buildInWrappers[wrapper as keyof typeof buildInWrappers] ??
+        buildInWrappers.none
+      );
+    } else if (wrapper === undefined) {
+      return buildInWrappers.none;
+    } else return wrapper;
+  }
+
+  _calcWrappedProps<P extends Profile.PropsType>(
+    former_props: Partial<P>,
+    props: Partial<P>,
+    wrapper: Wrapper | string | undefined,
+    progress: number
+  ): Partial<P> {
+    let _former_props: any = { ...former_props };
+    let wrapper_func = this._getWrapper(wrapper);
+    let wraped_prog = wrapper_func(progress);
+    let res = { ..._former_props };
+    for (let key in props) {
+      if (typeof props[key] === "number") {
+        if (_former_props[key] == undefined) _former_props[key] = 0;
+        res[key] =
+          _former_props[key] + wraped_prog * (props[key] - _former_props[key]);
+      } else if (typeof props[key] === "boolean") {
+        if (_former_props[key] == undefined) _former_props[key] = false;
+        res[key] = wraped_prog === 1 ? props[key] : _former_props[key];
+      } else if (typeof props[key] === "string") {
+        if (_former_props[key] == undefined) _former_props[key] = "";
+        res[key] = wraped_prog === 1 ? props[key] : _former_props[key];
+      } else {
+        res[key] = props[key];
+      }
+    }
+    return res;
+  }
+}
+
+export namespace Animation {
+  export interface Options<P extends Profile.PropsType> {
+    // @ts-ignore
+    initProps?: Partial<P>;
+    wrappers?: Record<string, Wrapper>;
+  }
+  export interface Serialized {
+    normalizedProfile: Profile.Serialized;
+    initProps?: Partial<unknown>;
+    activeRootTrack?: ActiveTrackNode.Serialized;
+    lastTime: number;
+  }
+}
+
+export type Profile<P extends Profile.PropsType = unknown> =
+  | Profile.Section<P>
+  | Profile.Track<P>
+  | Profile.TrackList<P>;
+
+export namespace Profile {
+  export type Serialized = Profile;
+
+  export type TrackList<P extends PropsType> = Track<P>[];
+  export type Track<P extends PropsType> = Section<P>[];
+  export type Section<P extends PropsType> = {
+    time?: number;
+    repeat?: number;
+    wrapper?: keyof typeof buildInWrappers | string | Wrapper;
+    frame?: Partial<P>;
+    syncs?: Profile<P>[];
+    asyncs?: Profile<P>[];
+  };
+  export type FrameItem = number | boolean | string;
+  export type PropsType = Record<string, FrameItem> | unknown;
+  export function normalize<P extends PropsType>(
+    profile: Profile<P>
+  ): Track<P> {
+    if (!Array.isArray(profile)) {
+      // section
+      return [profile];
+    } else if (profile.length === 0) {
+      // empty track/tracklist
+      return [];
+    } else if (!Array.isArray(profile[0])) {
+      // track
+      return profile as Track<P>;
+    } else {
+      // tracklist
+      return [
+        {
+          syncs: profile,
+        },
+      ];
+    }
+  }
+}
+
+export interface Timer<TimerIdType> {
+  init(animation: Animation): void;
+  // 回調時調用animation.timerCallback
+  setTimeout(timeout?: number): TimerIdType;
+  clearTimeout(timerId: TimerIdType): void;
+  setInterval(interval?: number): TimerIdType;
+  clearInterval(timerId: TimerIdType): void;
+  getTime(): number; // in ms
+  setOption?(option: Timer.Options): void;
+}
+
+export namespace Timer {
+  export interface Options {
+    fps?: number;
+  }
+}
+
+export class ActiveTrackNode<P extends Profile.PropsType> {
+  accessKeys: string[];
+  currentIndex: number | null;
+  repeated: number = 0;
+  status: ActiveTrackNode.Status = ActiveTrackNode.Status.Playing;
+  now_time: number = 0;
+  #currentSection: Profile.Section<P> | null = null;
+  #currentIndex: number | null = null;
+  get currentSection() {
+    if (this.#currentSection === null) {
+      if (this.currentIndex === null) {
+        this.#currentSection = this.animation._accessProfile(
+          this.accessKeys
+        ) as Profile.Section<P>;
+      } else {
+        this.#currentSection = this.currentTrack![this.currentIndex!];
+      }
+      this.#currentIndex = this.currentIndex;
+    } else if (this.currentIndex !== this.#currentIndex) {
+      this.#currentSection = this.currentTrack![this.currentIndex!];
+      this.#currentIndex = this.currentIndex;
+    }
+    return this.#currentSection;
+  }
+  #currentTrack: Profile.Track<P> | null = null;
+  get currentTrack() {
+    if (this.#currentTrack === null && this.currentIndex !== null) {
+      this.#currentTrack = this.animation._accessProfile(
+        this.accessKeys
+      ) as Profile.Track<P>;
+    }
+    return this.#currentTrack;
+  }
+  lastProps: Partial<P> = {};
+  nowProps: Partial<P> = {};
+  constructor(
+    public animation: Animation,
+    {
+      accessKeys,
+      index,
+      initProps,
+    }: {
+      accessKeys: string[];
+      index: number | null;
+      initProps: Partial<P>;
+    }
+  ) {
+    this.accessKeys = accessKeys;
+    this.currentIndex = index;
+
+    this.lastProps = { ...initProps };
+    this.nowProps = { ...initProps };
+  }
+
+  serialize(): ActiveTrackNode.Serialized {
+    return {
+      accessKeys: this.accessKeys,
+      currentIndex: this.currentIndex,
+      repeated: this.repeated,
+      status: this.status,
+      now_time: this.now_time,
+      lastProps: this.lastProps,
+      nowProps: this.nowProps,
+      activeSyncs: this.activeSyncs.map((sync) => sync.serialize()),
+    };
+  }
+  static unserialize<P>(
+    animation: Animation,
+    serialized: ActiveTrackNode.Serialized
+  ): ActiveTrackNode<P> {
+    let node = new ActiveTrackNode(animation, {
+      accessKeys: serialized.accessKeys,
+      index: serialized.currentIndex,
+      initProps: serialized.lastProps,
+    });
+    node.lastProps = serialized.lastProps;
+    node.nowProps = serialized.nowProps;
+    node.status = serialized.status;
+    node.repeated = serialized.repeated;
+    node.now_time = serialized.now_time;
+
+    node.activeSyncs = serialized.activeSyncs.map((sync) =>
+      ActiveTrackNode.unserialize<P>(animation, sync)
+    );
+    return node;
+  }
+  /**
+   *
+   * @param delta_time
+   * @returns 剩餘的時間
+   */
+  step(delta_time: number): number {
+    // console.log(`node step: ${delta_time}`);
+
+    // if (this.status === ActiveTrackNode.Status.Pause) return delta_time;
+    // because we should proceed async list
+    // normal
+    if(!this.currentSection) {
+      this.status = ActiveTrackNode.Status.Pause;
+      return delta_time;
+    }
+    while (true) {
+      // constant field: time, wrapper, frame
+      // instant filed: syncs, asyncs
+      if (this.status === ActiveTrackNode.Status.Playing) {
+        if (
+          this.currentSection.time === undefined ||
+          this.currentSection.time <= 0
+        ) {
+          this.nowProps = { ...this.nowProps, ...this.currentSection.frame };
+        } else {
+          if (this.now_time + delta_time >= this.currentSection.time) {
+            // this.now_time = this.currentSection.time
+            delta_time -= this.currentSection.time - this.now_time;
+            this.nowProps = { ...this.nowProps, ...this.currentSection.frame };
+          } else {
+            this.now_time += delta_time;
+            delta_time = 0;
+            // calc
+            let progress = this.now_time / this.currentSection.time;
+            // console.log(`progress: ${progress}`);
+            this.nowProps = this.animation._calcWrappedProps(
+              this.lastProps,
+              this.currentSection.frame ?? {},
+              this.currentSection.wrapper,
+              progress
+            );
+            break;
+          }
+        }
+
+        // sync async
+        if (this.currentSection.syncs && this.currentSection.syncs.length > 0) {
+          this.initSyncs();
+          this.status = ActiveTrackNode.Status.WaitingSyncs;
+        }
+      }
+
+      // step and check sync
+      if (this.status === ActiveTrackNode.Status.WaitingSyncs) {
+        delta_time = this.stepSyncs(delta_time); // returns lefted time
+        this.nowProps = Object.assign(this.nowProps, this.getSyncsProps());
+        if (this.checkSyncsFinished()) {
+          this.status = ActiveTrackNode.Status.Playing;
+          this.activeSyncs = [];
+        } else {
+          // debug
+          if (delta_time !== 0)
+            throw "syncs not finished while lefted time != 0. may be bugs";
+          break;
+        }
+      }
+
+      // check repeat , finish
+      if (this.currentSection.repeat !== undefined) {
+        this.repeated++;
+        if (this.repeated >= this.currentSection.repeat) {
+          // finish and proceed next section
+          // TODO
+          if (this._switchNextSection()) continue;
+          else break;
+        } else {
+          // continue this section
+          this.now_time = 0;
+          this.nowProps = { ...this.lastProps };
+          continue;
+        }
+      } else {
+        if (this._switchNextSection()) continue;
+        else break;
+      }
+    }
+
+    // waiting syncs
+
+    return delta_time;
+  }
+
+  calcProps(): Partial<P> {
+    return this.nowProps;
+  }
+
+  _switchNextSection(): boolean {
+    if (
+      this.currentIndex === null ||
+      this.currentTrack!.length === this.currentIndex + 1
+    ) {
+      // already reach the end
+      this.status = ActiveTrackNode.Status.Pause;
+      return false;
+    } else {
+      this.lastProps = { ...this.nowProps };
+      this.repeated = 0;
+      this.now_time = 0;
+      this.currentIndex++;
+      return true;
+    }
+  }
+
+  activeSyncs: ActiveTrackNode<P>[] = [];
+
+  initSyncs() {
+    // console.log("init syncs");
+
+    let activeSyncs: ActiveTrackNode<P>[] = [];
+    // if (this.currentSection.syncs == null) return;
+    let subprofile = this.currentSection.syncs!;
+    let activeTrackNode;
+    if (Array.isArray(subprofile)) {
+      if (subprofile.length > 0 && Array.isArray(subprofile[0])) {
+        // tracklist
+        for (let j = 0; j < subprofile.length; ++j) {
+          activeTrackNode = new ActiveTrackNode(this.animation, {
+            accessKeys: [
+              ...this.accessKeys,
+              "" + this.currentIndex,
+              "syncs",
+              "" + j,
+            ],
+            index: 0,
+            initProps: this.nowProps, // TODO 因为 lastProps在切换的时候才会更新，所以用nowProps
+          });
+          activeSyncs.push(activeTrackNode);
+        }
+      } else {
+        // Track
+        activeTrackNode = new ActiveTrackNode(this.animation, {
+          accessKeys: [...this.accessKeys, "" + this.currentIndex, "syncs"],
+          index: 0,
+          initProps: this.nowProps, // TODO 因为 lastProps在切换的时候才会更新，所以用nowProps
+        });
+        activeSyncs.push(activeTrackNode);
+        console
+          .log
+          // "create subtrack=" + JSON.stringify(activeTrackNode.serialize())
+          ();
+      }
+    } else {
+      // section
+      activeTrackNode = new ActiveTrackNode(this.animation, {
+        accessKeys: [...this.accessKeys, "" + this.currentIndex, "syncs"],
+        index: null,
+        initProps: this.nowProps, // TODO 因为 lastProps在切换的时候才会更新，所以用nowProps
+      });
+      activeSyncs.push(activeTrackNode);
+    }
+    // activeTrackNode?.step(0); // TODO
+
+    this.activeSyncs = activeSyncs;
+  }
+
+  stepSyncs(delta_time: number): number {
+    let lefted_time = delta_time;
+    for (let i = 0; i < this.activeSyncs.length; ++i) {
+      lefted_time = Math.min(this.activeSyncs[i].step(delta_time), lefted_time);
+    }
+    return lefted_time;
+  }
+
+  checkSyncsFinished(): boolean {
+    for (let i = 0; i < this.activeSyncs.length; ++i) {
+      if (this.activeSyncs[i].status !== ActiveTrackNode.Status.Pause)
+        return false;
+    }
+    return true;
+  }
+
+  getSyncsProps() {
+    let res: Partial<P> = {};
+    for (let i = 0; i < this.activeSyncs.length; ++i) {
+      Object.assign(res, this.activeSyncs[i].calcProps());
+    }
+    return res;
+  }
+}
+
+export namespace ActiveTrackNode {
+  export enum Status {
+    Playing,
+    WaitingSyncs,
+    Pause,
+  }
+  export interface Serialized {
+    accessKeys: string[];
+    currentIndex: number | null;
+    repeated: number;
+    status: ActiveTrackNode.Status;
+    now_time: number;
+    lastProps: Partial<unknown>;
+    nowProps: Partial<unknown>;
+    activeSyncs: ActiveTrackNode.Serialized[];
+  }
+}
+
+// Map a number from [0, 1] (progress time percentage) to [0, 1] (animation parameter value percentage).
+export type Wrapper = (x: number) => number;
+
+const buildInWrappers = {
+  none: (x: number) => (x < 1 ? 0 : 1),
+  linear: (x: number) => x,
+  easeout: (x: number) => Math.pow(x, 3),
+  easein: (x: number) => 1 - Math.pow(1 - x, 3),
+  easeinout: (x: number) =>
+    x < 0.5 ? 0.5 * Math.pow(x, 3) : 1 - 0.5 * Math.pow(1 - x, 3),
+};

package/src/plugins/transform/commands.ts

@@ -0,0 +1,53 @@
+import { HZEngineCore, Script } from "../../index.js";
+
+export function registerHzscriptCommands(core: HZEngineCore) {
+  core.script.use((ctx, next) => {
+    if (ctx.rawtext.trim().split(" ")[0] !== "transition") return next();
+    if (ctx.rawtext.includes(`"`))
+      throw `Transition Command: cannot have quotes in transition command`;
+    if (ctx.slicedArgs.length !== 4)
+      throw `Transition Command: incorrect amount of args`;
+    if (ctx.slicedArgs[1].isQuoted || ctx.slicedArgs[1].isSquared)
+      throw `Transition Command: invalid transition name type`;
+    let transitionName = ctx.slicedArgs[1].str;
+    if (
+      ctx.slicedArgs[2].isQuoted ||
+      ctx.slicedArgs[2].isSquared ||
+      ctx.slicedArgs[2].str !== "="
+    ) {
+      throw `the third arg of transition command should be "="`;
+    }
+    let tuple_str = Script.Utils.joinSlicedArgs(ctx.slicedArgs.slice(3));
+    let tuple = Script.Utils.parseTuple(tuple_str);
+    if (tuple.length !== 2) {
+      throw `thransition tuple must have 2 args`;
+    }
+
+    let inTransforms: string[] = (tuple[0] as string).startsWith("[")
+      ? Script.Utils.parseArray((tuple[0] as string)) as string[]
+      : [(tuple[0] as string)];
+    let outTransforms: string[] = (tuple[1] as string).startsWith("[")
+      ? Script.Utils.parseArray((tuple[1] as string)) as string[]
+      : [(tuple[1] as string)];
+
+    let transitionMap = getTransitionMap(core);
+    transitionMap[transitionName] = {
+      inTransforms,
+      outTransforms,
+    };
+  });
+}
+
+export function getTransitionMap(core: HZEngineCore) {
+  return core.storage.getSaveableData(
+    core.storage.archiveData,
+    true,
+    "script",
+    "transitionMap"
+  ) as unknown as Record<string, TransitionData>;
+}
+
+export type TransitionData = {
+  inTransforms: string[];
+  outTransforms: string[];
+};

package/src/plugins/transform/example_profiles.ts

@@ -0,0 +1,36 @@
+import { Profile } from "./animation.js";
+
+export const ExampleProfile1: Profile = [
+    [ // alpha
+        {
+            frame: {
+                alpha: 0,
+            }
+        },
+        {
+            time: 0.5,
+            wrapper: "easein",
+            frame: {
+                alpha: 1,
+            }
+        }
+    ],
+    [ // x
+        {
+            frame: {
+                xalign: -1,
+                xanchor: -1,
+            }
+        },
+        {
+            time: 1.0,
+            wrapper: "easein",
+            frame: {
+                xalign: 1,
+                xanchor: 1,
+            }
+        }
+
+    ]
+]
+