kipphi 2.1.2 → 2.1.3-beta.2

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

@@ -10,6 +10,7 @@ import {
     NormalEasing,
     rpeEasingArray,
     SegmentedEasing,
+    TemplateEasing,
     TemplateEasingLib,
 } from "./easing";
 
@@ -149,6 +150,11 @@ export class Chart {
     /** 难度等级显示绑定的判定线 */
     levelAttach:       JudgeLine | null = null;
 
+    /** 仅用于构造时检查 
+     * @internal
+     */
+    segmentedTemplates: Map<(SegmentedEasing & { easing: TemplateEasing}), [string, TimeT]> = new Map();
+
     constructor() {}
     
     /**
@@ -169,7 +175,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;
@@ -286,6 +292,9 @@ export class Chart {
         for (let i = 0; i < len; i++) {
             const easingData = templateEasings[i];
             const sequence = chart.sequenceMap.get(easingData.content);
+            if (!sequence) {
+                continue; // 后面check的时候会错误处理
+            }
             if (sequence.type !== EventType.easing) {
                 throw err.CANNOT_IMPLEMENT_TEMEAS_WITH_NON_EASING_ENS(easingData.name);
             }
@@ -294,7 +303,19 @@ export class Chart {
             }
             chart.templateEasingLib.implement(easingData.name, sequence as EventNodeSequence<number>);
         }
-        chart.templateEasingLib.check()
+        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();
+
+        chart.checkSegmentedTemplates();
+
         for (const lineData of data.orphanLines) {
             const line: JudgeLine = JudgeLine.fromKPAJSON(data.version, chart, lineData.id, lineData, chart.templateEasingLib, chart.timeCalculator)
             chart.orphanLines.push(line)
@@ -718,6 +739,25 @@ export class Chart {
         
     }
     */
+    checkErrors() {
+        KPAError.flush();
+        for (const [_, seq] of this.sequenceMap) {
+            seq.checkErrors();
+        }
+    }
+    /**
+     * 用于构造谱面时检查
+     */
+    protected checkSegmentedTemplates() {
+        for (const [easing, [pos, time]] of this.segmentedTemplates) {
+            const inner = easing.easing;
+            if (inner.getValue(easing.left) === inner.getValue(easing.right)) {
+                err.EASING_DELTA_CANNOT_BE_ZERO(pos, time).warn();
+            }
+        }
+        this.segmentedTemplates.clear();
+        // 查完就清除，不再需要
+    }
 }
 
 /**

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,8 @@ 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,
+    EASING_DELTA_CANNOT_BE_ZERO =                   EASING     | INVALID_USAGE | 5,
 
     CANNOT_DIVIDE_EXPRESSION_EVALUATOR =            EVALUATOR  | INVALID_USAGE | 0,
     MISSING_MACRO_EVALUATOR_KEY =                   EVALUATOR  | INVALID_DATA  | 0,
@@ -181,6 +183,10 @@ 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`,
+    EASING_DELTA_CANNOT_BE_ZERO: (seqName: string, time: TimeT) =>
+        `Easing delta cannot be zero. (at ${seqName}, ${toTimeString(time)}`,
 } 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) {
@@ -643,6 +640,12 @@ export class EventNodeSequence<VT extends EventValueESType = number> { // 泛型
         for (let index = 0; index < length; index++) {
             const event = data[index];
             const [start, end] = chart.createEventFromData<VT>(event, valueType, `${pos}.events[${index}]`);
+
+            // 收集被截的模板缓动
+            const evaluator = start.evaluator;
+            if (evaluator instanceof EasedEvaluator && evaluator.easing instanceof SegmentedEasing && evaluator.easing.easing instanceof TemplateEasing) {
+                chart.segmentedTemplates.set(evaluator.easing as any, [pos, start.time]);
+            }
             // 从前面复制了，复用性减一
             // KPA2没有更改RPE的按事件存储的机制。
             if (TC.lt(event.startTime, lastEndTime)) { // event.startTime < lastEndTime
@@ -798,6 +801,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 +832,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;
@@ -956,15 +962,50 @@ export class EventNodeSequence<VT extends EventValueESType = number> { // 泛型
         }
 
         let lastEnd: EventEndNode<VT> = endNode;
+        currentNode = endNode.next;
         while (true) {
+            const evaluator = currentNode.evaluator;
+            if (this.type === EventType.easing && evaluator instanceof EasedEvaluator && evaluator.easing instanceof TemplateEasing) {
+                if (TemplateEasing.checkCircularReference(this as EventNodeSequence, evaluator.easing)) {
+                    err.TEMPLATE_EASING_CIRCULAR_REFERENCE(this.id).warn();
+                }
+            }
+            if (evaluator instanceof EasedEvaluator && evaluator.easing instanceof SegmentedEasing) {
+                const easing = evaluator.easing;
+                const inner = easing.easing;
+                if (inner.getValue(easing.left) === inner.getValue(easing.right)) {
+                    err.EASING_DELTA_CANNOT_BE_ZERO(this.id, currentNode.time).warn();
+                }
+            }
             const endNode = currentNode.next;
             if (endNode.type === NodeType.TAIL) {
                 break;
             }
+            if (!TC.gt(endNode.time, currentNode.time)) {
+                err.EVENT_NODE_TIME_NOT_INCREMENTAL(`${this.id}, ${currentNode.time}`).warn();
+            }
             if (TC.ne(lastEnd.time, currentNode.time)) {
                 err.EVENT_NODE_NOT_DENSE(`${this.id}, ${currentNode.time}`).warn();
             }
             currentNode = currentNode.next.next;
+            lastEnd = endNode;
+        }
+    }
+    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;
         }
     }
 }