kipphi 2.1.2 → 2.1.3-beta.1

package/bpm.ts

@@ -110,7 +110,12 @@ type BNOrHead = BPMNode | BPMNodeLike<NodeType.HEAD>;
 /**
  * BPM序列类，管理BPM变化序列
  * 拥有与事件类似的逻辑，每对节点之间代表一个BPM相同的片段
- * 片段之间BPM可以发生改变
+ * 片段之间BPM可以发生改变。
+ * 
+ * @example
+ * const bpmList = [{ startTime: [0, 0, 0], bpm: 120 }];
+ * const bpmSequence = new BPMSequence(bpmList, 180);
+ * // JumpArray 在构造器中自动初始化。
  */
 export class BPMSequence extends EventNodeSequence {
     /** 头部节点 */
@@ -141,7 +146,7 @@ export class BPMSequence extends EventNodeSequence {
             BPMStartNode.connect(curPos, startNode);
             curPos = endNode;
         }
-        const last = new BPMStartNode(next.startTime, next.bpm)
+        const last = new BPMStartNode(next.startTime, next.bpm);
         BPMStartNode.connect(curPos, last);
         BPMStartNode.connect(last, this.tail);
         this.initJump();
@@ -160,7 +165,9 @@ export class BPMSequence extends EventNodeSequence {
     }
     
     /**
-     * 更新秒跳转数组
+     * 更新秒跳转数组。
+     * 
+     * 缓存每个节点的秒数发生在这里。
      */
     updateSecondJump(): void {
         let integral = 0;
@@ -179,7 +186,7 @@ export class BPMSequence extends EventNodeSequence {
             node = endNode.next;
         }
         node.cachedStartIntegral = integral;
-        if (this.effectiveBeats  === 0) {
+        if (this.effectiveBeats === 0) {
             return;
         }
         const originalListLength = this.listLength;
@@ -188,7 +195,7 @@ export class BPMSequence extends EventNodeSequence {
             this.tail,
             originalListLength,
             this.duration,
-            (node: AnyBN) => {
+            (node: BPMStartNode | BPMNodeLike<NodeType.TAIL> | BPMNodeLike<NodeType.HEAD>) => {
                 if (node.type === NodeType.TAIL) {
                     return [null, null];
                 }
@@ -259,8 +266,9 @@ export class BPMSequence extends EventNodeSequence {
     
     /**
      * 根据拍数获取节点
+     * 
      * @param beats 拍数
-     * @param usePrev 是否使用前一个节点
+     * @param usePrev 是否使用前一个节点。假设有两个BPM片段，0-2拍，2-无穷，`getNodeAt(2, true)` 会返回第一个片段的开始节点
      * @returns 对应的BPM起始节点
      */
     getNodeAt(beats: number, usePrev?: boolean): BPMStartNode {
@@ -270,6 +278,15 @@ export class BPMSequence extends EventNodeSequence {
 
 /**
  * 时间计算器类，用于处理拍数与秒数之间的转换
+ * 
+ * @example
+ * const bpmList = = [
+ *     { bpm: 120, startTime: [0, 0, 1] }
+ * ];
+ * const tc = new TimeCalculator();
+ * tc.bpmList = bpmList;
+ * tc.duration = 131; // 这两者都是必需的。
+ * tc.initSequence();
  */
 export class TimeCalculator {
     /** BPM片段数据列表 */
@@ -289,6 +306,9 @@ export class TimeCalculator {
      * 初始化BPM序列
      */
     initSequence() {
+        if (!this.bpmList || !this.duration) {
+            throw new Error("TimeCalculator: bpmList and duration must be set before initSequence");
+        }
         const bpmList = this.bpmList;
         // @ts-expect-error 不在构造器中初始化的只读属性
         this.bpmSequence = new BPMSequence(bpmList, this.duration);

package/chart.ts

@@ -169,7 +169,7 @@ export class Chart {
      */
     static fromRPEJSON(data: ChartDataRPE, duration: number) {
         const chart = new Chart();
-        chart.judgeLineGroups = data.judgeLineGroup.map(group => new JudgeLineGroup(group));
+        chart.judgeLineGroups = (data.judgeLineGroup || ["Default"]).map(group => new JudgeLineGroup(group));
         chart.name = data.META.name;
         chart.level = data.META.level;
         chart.offset = data.META.offset;
@@ -294,6 +294,15 @@ export class Chart {
             }
             chart.templateEasingLib.implement(easingData.name, sequence as EventNodeSequence<number>);
         }
+        for (let i = 0; i < len; i++) {
+            const easingData = templateEasings[i];
+            const sequence = chart.sequenceMap.get(easingData.content) as EventNodeSequence;
+            // 遍历该序列检查循环依赖
+            if (sequence.hasReferenceTo(sequence)) {
+                throw err.TEMPLATE_EASING_CIRCULAR_REFERENCE(easingData.name);
+            }
+        }
+
         chart.templateEasingLib.check()
         for (const lineData of data.orphanLines) {
             const line: JudgeLine = JudgeLine.fromKPAJSON(data.version, chart, lineData.id, lineData, chart.templateEasingLib, chart.timeCalculator)

package/chartTypes.ts

@@ -84,11 +84,27 @@ export interface NoteDataRPE {
      * Sets the Z index for the hit effects of the note. Defaults to 7.
      */
     zIndexHitEffects?: number;
-    /** Sets the tint for the hit effects of the note. Defaults to null. */
+    /**
+     * Sets the tint for the hit effects of the note. Defaults to null.
+     * 
+     * @alias color
+     */
     tint?: RGB;
+    /**
+     * @see {@linkcode tint}
+     */
+    color?: RGB;
     tintHitEffects?: RGB;
     
-    /** Determines the width of the judgment area of the note. Defaults to size. */
+    
+    /**
+     * Determines the width of the judgment area of the note. Defaults to size.
+     * @alias judgeSize
+     */
+    judgeArea?: number;
+    /**
+     * @see {@linkcode judgeArea}
+     */
     judgeSize?: number;
 }
 
@@ -113,7 +129,11 @@ export interface NoteDataKPA {
     type: NoteType;
     /** 音符可视时间（打击前多少秒开始显现，默认99999.0） */
     visibleTime?: number;
-    /** y值偏移，使音符被打击时的位置偏离判定线 */
+    /**
+     * y值偏移，使音符被打击时的位置偏离判定线
+     * 
+     * @deprecated 使用{@linkcode absoluteYOffset}代替。
+     */
     yOffset: number;
 
     // 下面是PhiZone Player扩展的内容
@@ -123,11 +143,12 @@ export interface NoteDataKPA {
      * Sets the Z index for the hit effects of the note. Defaults to 7.
      */
     zIndexHitEffects?: number;
-    /** Sets the tint for the hit effects of the note. Defaults to null. */
+    /**
+     * Sets the tint for the hit effects of the note. Defaults to null.
+     */
     tint?: RGB;
     tintHitEffects?: RGB;
     
-    /** Determines the width of the judgment area of the note. Defaults to size. */
     judgeSize?: number;
     visibleBeats?: number;
     absoluteYOffset: number;

package/easing.ts

@@ -1,8 +1,8 @@
 import { type TemplateEasingBodyData, type EasingDataKPA2, EasingType, EventType, type SegmentedEasingData, type NormalEasingData, type BezierEasingData, type TemplateEasingData, WrapperEasingData, WrapperEasingBodyData } from "./chartTypes";
 import { type EventNodeSequence } from "./event";
-import { type TupleCoord } from "./util";
+import { NodeType, type TupleCoord } from "./util";
 import Environment, { err } from "./env";
-import { type ExpressionEvaluator } from "./evaluator";
+import { type EasedEvaluator, type ExpressionEvaluator } from "./evaluator";
 
 
 /// #declaration:global
@@ -318,6 +318,9 @@ export class TemplateEasing extends Easing {
         this.name = name;
     }
     getValue(t: number) {
+        if (t === 1) {
+            return 1;
+        }
         const seq = this.eventNodeSequence;
         const delta = this.valueDelta;
         if (delta === 0) {
@@ -339,6 +342,32 @@ export class TemplateEasing extends Easing {
     get headValue(): number {
         return this.eventNodeSequence.head.next.value;
     }
+    
+    segmentedValueGetter(easingLeft: number, easingRight: number) {
+        // 由于模板缓动是可变的，所以不能在分段缓动构造时预先计算几个变化量
+        return (t: number) => {
+            
+            const leftValue = this.getValue(easingLeft);
+            const rightValue =  this.getValue(easingRight);
+            const timeDelta = easingRight - easingLeft;
+            const delta = rightValue - leftValue;
+            if (delta === 0) {
+                return 0;
+            }
+            return (this.getValue(easingLeft + timeDelta * t) - leftValue) / delta
+        };
+    }
+    
+    static checkCircularReference(seq: EventNodeSequence, template: TemplateEasing) {
+        const seq2 = template.eventNodeSequence;
+        if (seq === seq2) {
+            return true;
+        }
+        if (seq2.hasReferenceTo(seq)) {
+            return true;
+        }
+        return false;
+    }
 }
 
 export class WrapperEasing extends Easing {

package/env.ts

@@ -73,6 +73,7 @@ export enum ERROR_IDS {
     NODES_NOT_CONTINUOUS =                          EASING     | INVALID_USAGE | 1,
     NODES_NOT_BELONG_TO_SAME_SEQUENCE =             EASING     | INVALID_USAGE | 2,
     NODES_HAS_ZERO_DELTA =                          EASING     | INVALID_USAGE | 3,
+    TEMPLATE_EASING_CIRCULAR_REFERENCE =            EASING     | INVALID_USAGE | 4,
 
     CANNOT_DIVIDE_EXPRESSION_EVALUATOR =            EVALUATOR  | INVALID_USAGE | 0,
     MISSING_MACRO_EVALUATOR_KEY =                   EVALUATOR  | INVALID_DATA  | 0,
@@ -181,6 +182,8 @@ export const ERRORS = {
         `EventNode is not dense. At ${pos}`,
     HOLD_HAS_NO_DURATION: () =>
         `Hold should have a duration.`,
+    TEMPLATE_EASING_CIRCULAR_REFERENCE: (temEasName: string) =>
+        `Template Easing '${temEasName}' has circular reference`,
 } satisfies Record<keyof typeof ERROR_IDS, (...args: any[]) => string>
 
 type EnumKeys<E extends Record<string, string | number>> = E[keyof E];

package/evaluator.ts

@@ -13,6 +13,7 @@ import { EasingType, EvaluatorType, EventValueType, EventValueTypeOfType, Interp
 import type { JudgeLine } from "./judgeline";
 import { Chart } from "./chart";
 import { EVENT_MACROS } from "./macro";
+import { type TimeCalculator } from "./bpm";
 
 
 /// #declaration:global
@@ -28,6 +29,7 @@ import { EVENT_MACROS } from "./macro";
  */
 export abstract class Evaluator<T extends EventValueESType> {
     abstract eval(event: NonLastStartNode<T>, beats: number): T;
+    abstract eval(event: NonLastStartNode<T>, seconds: number, timeCalculator: TimeCalculator): T;
     abstract dumpFor(node: EventStartNode<T>): EvaluatorDataKPA2<T>;
 }
 
@@ -38,17 +40,28 @@ export abstract class EasedEvaluator<T extends EventValueESType> extends Evaluat
         super();
         this.easing = easing;
     }
-    override eval(startNode: NonLastStartNode<T>, beats: number): T {
+    override eval(startNode: NonLastStartNode<T>, beats: number): T;
+    override eval(startNode: NonLastStartNode<T>, seconds: number, timeCalculator: TimeCalculator): T;
+    override eval(startNode: NonLastStartNode<T>, beatsOrSeconds: number, timeCalculator?: TimeCalculator): T {
         const next = startNode.next;
-        const timeDelta = TC.getDelta(next.time, startNode.time)
-        const current = beats - TC.toBeats(startNode.time)
         const nextValue = startNode.next.value;
         const value = startNode.value;
         if (nextValue === value) {
             return value;
         }
-        // 其他类型，包括普通缓动和非钩定模板缓动
-        return this.convert(value, nextValue, this.easing.getValue(current / timeDelta));
+        if (timeCalculator) {
+            // 注意这个和下面那个API设计得不一样
+            const startSecs = timeCalculator.toSeconds(TC.toBeats(startNode.time));
+            const endSecs = timeCalculator.toSeconds(TC.toBeats(next.time));
+            const current = beatsOrSeconds - startSecs;
+            const timeDelta = endSecs - startSecs;
+            return this.convert(value, nextValue, this.easing.getValue(current / timeDelta));
+        } else {
+            const timeDelta = TC.getDelta(next.time, startNode.time)
+            const current = beatsOrSeconds - TC.toBeats(startNode.time)
+            // 其他类型，包括普通缓动和非钩定模板缓动
+            return this.convert(value, nextValue, this.easing.getValue(current / timeDelta));
+        }
     }
     abstract convert(start: T, end: T, progress: number): T;
     /**
@@ -159,11 +172,11 @@ export class TextEasedEvaluator extends EasedEvaluator<string> {
         if (interpretedAs === InterpreteAs.float) {
             const start = parseFloat(value);
             const delta = parseFloat(nextValue as string) - start;
-            return start + progress * delta + "";
+            return (start + progress * delta).toFixed(3) + "";
         } else if (interpretedAs === InterpreteAs.int) {
             const start = parseInt(value);
             const delta = parseInt(nextValue as string) - start;
-            return start + Math.round(progress * delta) + "";
+            return start + Math.floor(progress * delta) + "";
         } else 
             if (value.startsWith(nextValue as string)) {
                 const startLen = (nextValue as string).length;
@@ -218,8 +231,10 @@ export class MacroEvaluator<T extends EventValueESType> extends Evaluator<T> {
         node.evaluator = this;
         this.consumers.set(node, this.compile(node, chart));
     }
-    eval(event: NonLastStartNode<T>, beats: number): T {
-        return this.consumers.get(event)!.eval(event, beats);
+    override eval(startNode: NonLastStartNode<T>, beats: number): T;
+    override eval(startNode: NonLastStartNode<T>, seconds: number, timeCalculator: TimeCalculator): T;
+    eval(event: NonLastStartNode<T>, beats: number, timeCalculator?: TimeCalculator): T {
+        return this.consumers.get(event)!.eval(event, beats, timeCalculator);
     }
     dumpFor(node: EventStartNode<T>): MacroEvaluatorDataKPA2 {
         return {
@@ -242,11 +257,21 @@ export class ExpressionEvaluator<T extends EventValueESType> extends Evaluator<T
         super();
         this.func = new Function("t", "return " + jsExpr) as (t: number) => T;
     }
-    override eval(startNode: NonLastStartNode<T>, beats: number): T {
-        const next = startNode.next;
-        const timeDelta = TC.getDelta(next.time, startNode.time)
-        const current = beats - TC.toBeats(startNode.time)
-        return this.func(current / timeDelta);
+    override eval(startNode: NonLastStartNode<T>, beats: number): T;
+    override eval(startNode: NonLastStartNode<T>, seconds: number, timeCalculator: TimeCalculator): T;
+    override eval(startNode: NonLastStartNode<T>, beatsOrSecs: number, timeCalculator?: TimeCalculator): T {
+        if (timeCalculator) {
+            const startSecs = timeCalculator.toSeconds(TC.toBeats(startNode.time));
+            const endSecs = timeCalculator.toSeconds(TC.toBeats(startNode.next.time));
+            const current = beatsOrSecs - startSecs;
+            const timeDelta = endSecs - startSecs;
+            return this.func(current / timeDelta);
+        } else {    
+            const next = startNode.next;
+            const timeDelta = TC.getDelta(next.time, startNode.time)
+            const current = beatsOrSecs - TC.toBeats(startNode.time)
+            return this.func(current / timeDelta);
+        }
     }
     override dumpFor(): ExpressionEvaluatorDataKPA2 {
         return {

package/event.ts

@@ -78,11 +78,6 @@ export abstract class EventNode<VT extends EventValueESType = number> extends Ev
      * @deprecated
      */
     static getEasing(data: EventDataKPA<EventValueESType>, templates: TemplateEasingLib, notSegmented = false): Easing {
-        const left = data.easingLeft;
-        const right = data.easingRight;
-        if (!notSegmented && (left && right) && (left !== 0.0 || right !== 1.0)) {
-            return new SegmentedEasing(EventNode.getEasing(data, templates, true), left, right)
-        }
         if (data.bezier) {
             const bp = data.bezierPoints
             const easing = new BezierEasing([bp[0], bp[1]], [bp[2], bp[3]]);
@@ -346,14 +341,16 @@ export class EventStartNode<VT extends EventValueESType = number> extends EventN
             macroTime: this.macroTime?.dumpForNode(this),
             linkedMacro: [...this.linkedMacros].map(macro => macro.dumpLinkForNode(this)),
         }
-    } 
-    getValueAt(beats: number): VT {
+    }
+    getValueAt(seconds: number, timeCalculator: TimeCalculator): VT;
+    getValueAt(beats: number): VT;
+    getValueAt(beatsOrSecs: number, timeCalculator?: TimeCalculator): VT {
         // 除了尾部的开始节点，其他都有下个节点
         // 钩定型缓动也有
         if (this.next.type === NodeType.TAIL) {
             return this.value;
         }
-        return this.evaluator.eval(this as NonLastStartNode<VT>, beats);
+        return this.evaluator.eval(this as NonLastStartNode<VT>, beatsOrSecs, timeCalculator);
     }
     getSpeedValueAt(this: EventStartNode<number>, beats: number) {
         if (this.next.type === NodeType.TAIL) {
@@ -798,6 +795,9 @@ export class EventNodeSequence<VT extends EventValueESType = number> { // 泛型
     getValueAt(beats: number, usePrev: boolean = false): VT {
         return this.getNodeAt(beats, usePrev).getValueAt(beats);
     }
+    getValueAtBySecs(beats: number, seconds: number, timeCalculator: TimeCalculator, usePrev: boolean = false) {
+        return this.getNodeAt(beats, usePrev).getValueAt(seconds, timeCalculator);
+    }
     getFloorPositionAt(this: EventNodeSequence<number>, beats: number, timeCalculator: TimeCalculator) {
         const node: EventStartNode<number> = this.getNodeAt(beats);
         const value = node.getLocalFloorPos(beats, timeCalculator) + node.floorPosition;
@@ -826,7 +826,7 @@ export class EventNodeSequence<VT extends EventValueESType = number> { // 泛型
             const prevStart = node.previous.previous;
             currentFP = prevStart.floorPosition + prevStart.getFullLocalFloorPos(tc);
         } else {
-            currentFP = 0;
+            node.floorPosition = currentFP = 0;
         }
         while (true) {
             const canBeEnd = node.next;
@@ -967,6 +967,23 @@ export class EventNodeSequence<VT extends EventValueESType = number> { // 泛型
             currentNode = currentNode.next.next;
         }
     }
+    hasReferenceTo(this: EventNodeSequence<number>, seq: EventNodeSequence<number>) {
+        
+        let node = this.head.next;
+        while (true) {
+            const endNode = node.next;
+            if (endNode.type === NodeType.TAIL) {
+                break;
+            }
+            const evaluator = node.evaluator;
+            if (evaluator instanceof EasedEvaluator && evaluator.easing instanceof TemplateEasing) {
+                if (TemplateEasing.checkCircularReference(seq, evaluator.easing as TemplateEasing)) {
+                    return true;
+                }
+            }
+            node = endNode.next;
+        }
+    }
 }
 
 export type SpeedENS = EventNodeSequence<number> & { type: EventType.speed };

package/index.d.ts

@@ -75,10 +75,25 @@ declare module "chartTypes" {
          * Sets the Z index for the hit effects of the note. Defaults to 7.
          */
         zIndexHitEffects?: number;
-        /** Sets the tint for the hit effects of the note. Defaults to null. */
+        /**
+         * Sets the tint for the hit effects of the note. Defaults to null.
+         *
+         * @alias color
+         */
         tint?: RGB;
+        /**
+         * @see {@linkcode tint}
+         */
+        color?: RGB;
         tintHitEffects?: RGB;
-        /** Determines the width of the judgment area of the note. Defaults to size. */
+        /**
+         * Determines the width of the judgment area of the note. Defaults to size.
+         * @alias judgeSize
+         */
+        judgeArea?: number;
+        /**
+         * @see {@linkcode judgeArea}
+         */
         judgeSize?: number;
     }
     export interface NoteDataKPA {
@@ -102,7 +117,11 @@ declare module "chartTypes" {
         type: NoteType;
         /** 音符可视时间（打击前多少秒开始显现，默认99999.0） */
         visibleTime?: number;
-        /** y值偏移，使音符被打击时的位置偏离判定线 */
+        /**
+         * y值偏移，使音符被打击时的位置偏离判定线
+         *
+         * @deprecated 使用{@linkcode absoluteYOffset}代替。
+         */
         yOffset: number;
         /** Sets the Z index for the object. */
         zIndex?: number;
@@ -110,10 +129,11 @@ declare module "chartTypes" {
          * Sets the Z index for the hit effects of the note. Defaults to 7.
          */
         zIndexHitEffects?: number;
-        /** Sets the tint for the hit effects of the note. Defaults to null. */
+        /**
+         * Sets the tint for the hit effects of the note. Defaults to null.
+         */
         tint?: RGB;
         tintHitEffects?: RGB;
-        /** Determines the width of the judgment area of the note. Defaults to size. */
         judgeSize?: number;
         visibleBeats?: number;
         absoluteYOffset: number;
@@ -533,7 +553,7 @@ declare module "chartTypes" {
     export type ExtendedEventTypeName = "scaleX" | "scaleY" | "text" | "color";
 }
 declare module "version" {
-    export const VERSION = 212;
+    export const VERSION = 213;
     export const SCHEMA = "https://cdn.jsdelivr.net/npm/kipphi@2.1.0/chartType2.schema.json";
 }
 declare module "util" {
@@ -684,7 +704,12 @@ declare module "bpm" {
     /**
      * BPM序列类，管理BPM变化序列
      * 拥有与事件类似的逻辑，每对节点之间代表一个BPM相同的片段
-     * 片段之间BPM可以发生改变
+     * 片段之间BPM可以发生改变。
+     *
+     * @example
+     * const bpmList = [{ startTime: [0, 0, 0], bpm: 120 }];
+     * const bpmSequence = new BPMSequence(bpmList, 180);
+     * // JumpArray 在构造器中自动初始化。
      */
     export class BPMSequence extends EventNodeSequence {
         duration: number;
@@ -707,7 +732,9 @@ declare module "bpm" {
          */
         initJump(): void;
         /**
-         * 更新秒跳转数组
+         * 更新秒跳转数组。
+         *
+         * 缓存每个节点的秒数发生在这里。
          */
         updateSecondJump(): void;
         /**
@@ -729,14 +756,24 @@ declare module "bpm" {
         dumpBPM(): BPMSegmentData[];
         /**
          * 根据拍数获取节点
+         *
          * @param beats 拍数
-         * @param usePrev 是否使用前一个节点
+         * @param usePrev 是否使用前一个节点。假设有两个BPM片段，0-2拍，2-无穷，`getNodeAt(2, true)` 会返回第一个片段的开始节点
          * @returns 对应的BPM起始节点
          */
         getNodeAt(beats: number, usePrev?: boolean): BPMStartNode;
     }
     /**
      * 时间计算器类，用于处理拍数与秒数之间的转换
+     *
+     * @example
+     * const bpmList = = [
+     *     { bpm: 120, startTime: [0, 0, 1] }
+     * ];
+     * const tc = new TimeCalculator();
+     * tc.bpmList = bpmList;
+     * tc.duration = 131; // 这两者都是必需的。
+     * tc.initSequence();
      */
     export class TimeCalculator {
         /** BPM片段数据列表 */
@@ -1197,6 +1234,7 @@ declare module "judgeline" {
          */
         getValues(beats: number, usePrev?: boolean): [x: number, y: number, theta: number, alpha: number];
         getStackedValue(type: keyof EventLayer, beats: number, usePrev?: boolean): number;
+        getStackedValueBySeconds(type: keyof EventLayer, beats: number, seconds: number, timeCalculator: TimeCalculator, usePrev?: boolean): number;
         /**
          * 获取指定时间点的FloorPosition。
          *
@@ -1329,6 +1367,7 @@ declare module "evaluator" {
     import type { EventStartNode, NonLastStartNode } from "event";
     import { EventValueTypeOfType, InterpreteAs, MacroEvaluatorBodyData, MacroEvaluatorDataKPA2, type ColorEasedEvaluatorKPA2, type EvaluatorDataKPA2, type EventValueESType, type ExpressionEvaluatorDataKPA2, type NumericEasedEvaluatorKPA2, type RGB, type TextEasedEvaluatorKPA2 } from "chartTypes";
     import { Chart } from "chart";
+    import { type TimeCalculator } from "bpm";
     /**
      * **求值器**
      *
@@ -1340,12 +1379,14 @@ declare module "evaluator" {
      */
     export abstract class Evaluator<T extends EventValueESType> {
         abstract eval(event: NonLastStartNode<T>, beats: number): T;
+        abstract eval(event: NonLastStartNode<T>, seconds: number, timeCalculator: TimeCalculator): T;
         abstract dumpFor(node: EventStartNode<T>): EvaluatorDataKPA2<T>;
     }
     export abstract class EasedEvaluator<T extends EventValueESType> extends Evaluator<T> {
         readonly easing: Easing;
         constructor(easing: Easing);
         eval(startNode: NonLastStartNode<T>, beats: number): T;
+        eval(startNode: NonLastStartNode<T>, seconds: number, timeCalculator: TimeCalculator): T;
         abstract convert(start: T, end: T, progress: number): T;
         /**
          * 派生一个类型相同但使用不同缓动的求值器
@@ -1397,7 +1438,8 @@ declare module "evaluator" {
         constructor(expression: string, id: string);
         compile(node: EventStartNode<T>, chart: Chart): ExpressionEvaluator<T>;
         assignTo(node: EventStartNode<T>, chart: Chart): void;
-        eval(event: NonLastStartNode<T>, beats: number): T;
+        eval(startNode: NonLastStartNode<T>, beats: number): T;
+        eval(startNode: NonLastStartNode<T>, seconds: number, timeCalculator: TimeCalculator): T;
         dumpFor(node: EventStartNode<T>): MacroEvaluatorDataKPA2;
         dumpContent(): MacroEvaluatorBodyData;
     }
@@ -1406,6 +1448,7 @@ declare module "evaluator" {
         readonly func: (t: number) => T;
         constructor(jsExpr: string);
         eval(startNode: NonLastStartNode<T>, beats: number): T;
+        eval(startNode: NonLastStartNode<T>, seconds: number, timeCalculator: TimeCalculator): T;
         dumpFor(): ExpressionEvaluatorDataKPA2;
     }
 }
@@ -1530,6 +1573,8 @@ declare module "easing" {
         dump(): TemplateEasingData;
         get valueDelta(): number;
         get headValue(): number;
+        segmentedValueGetter(easingLeft: number, easingRight: number): (t: number) => number;
+        static checkCircularReference(seq: EventNodeSequence, template: TemplateEasing): boolean;
     }
     export class WrapperEasing extends Easing {
         evaluator: ExpressionEvaluator<number>;
@@ -2023,6 +2068,7 @@ declare module "event" {
          */
         dump(): EventDataKPA2<VT>;
         dumpAsFinal(): FinalEventStartNodeDataKPA2<VT>;
+        getValueAt(seconds: number, timeCalculator: TimeCalculator): VT;
         getValueAt(beats: number): VT;
         getSpeedValueAt(this: EventStartNode<number>, beats: number): number;
         /**
@@ -2154,6 +2200,7 @@ declare module "event" {
         updateJump(from: ENOrHead<VT>, to: ENOrTail<VT>): void;
         getNodeAt(beats: number, usePrev?: boolean): EventStartNode<VT>;
         getValueAt(beats: number, usePrev?: boolean): VT;
+        getValueAtBySecs(beats: number, seconds: number, timeCalculator: TimeCalculator, usePrev?: boolean): VT;
         getFloorPositionAt(this: EventNodeSequence<number>, beats: number, timeCalculator: TimeCalculator): number;
         /**
          * 更新某个速度节点之后的FP
@@ -2182,6 +2229,7 @@ declare module "event" {
          */
         static mergeSequences(sequences: EventNodeSequence[]): EventNodeSequence<number>;
         checkErrors(): void;
+        hasReferenceTo(this: EventNodeSequence<number>, seq: EventNodeSequence<number>): boolean;
     }
     export type SpeedENS = EventNodeSequence<number> & {
         type: EventType.speed;
@@ -2213,6 +2261,7 @@ declare module "env" {
         NODES_NOT_CONTINUOUS = 2609,
         NODES_NOT_BELONG_TO_SAME_SEQUENCE = 2610,
         NODES_HAS_ZERO_DELTA = 2611,
+        TEMPLATE_EASING_CIRCULAR_REFERENCE = 2612,
         CANNOT_DIVIDE_EXPRESSION_EVALUATOR = 2352,
         MISSING_MACRO_EVALUATOR_KEY = 2336,
         MACRO_EVALUATOR_NOT_FOUND = 2337,
@@ -2263,6 +2312,7 @@ declare module "env" {
         MACRO_NOT_PARAMETRIC: (macroId: string, pos: any) => string;
         EVENT_NODE_NOT_DENSE: (pos: string) => string;
         HOLD_HAS_NO_DURATION: () => string;
+        TEMPLATE_EASING_CIRCULAR_REFERENCE: (temEasName: string) => string;
     };
     interface ErrorMap extends Record<keyof typeof ERROR_IDS, Array<any>> {
         EVENT_NODE_NOT_DENSE: [EventNode];
@@ -2328,6 +2378,7 @@ declare module "env" {
             MACRO_NOT_PARAMETRIC: (macroId: string, pos: any) => KPAError<ERROR_IDS.MACRO_NOT_PARAMETRIC>;
             EVENT_NODE_NOT_DENSE: (pos: string) => KPAError<ERROR_IDS.EVENT_NODE_NOT_DENSE>;
             HOLD_HAS_NO_DURATION: () => KPAError<ERROR_IDS.HOLD_HAS_NO_DURATION>;
+            TEMPLATE_EASING_CIRCULAR_REFERENCE: (temEasName: string) => KPAError<ERROR_IDS.TEMPLATE_EASING_CIRCULAR_REFERENCE>;
         };
         freeze(): void;
     };
@@ -3027,6 +3078,7 @@ declare module "rpeChartCompiler" {
         chart: Chart;
         sequenceMap: Map<EventNodeSequence<any>, EventNodeSequence<any>>;
         interpolationStep: TimeT;
+        deletesEmptyLines: boolean;
         constructor(chart: Chart);
         compileChart(): ChartDataRPE;
         compileJudgeLine(judgeLine: JudgeLine): JudgeLineDataRPE;