kipphi 2.1.2 → 2.1.3-beta.2

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>;
@@ -1652,7 +1697,7 @@ declare module "easing" {
 }
 declare module "chart" {
     import { TimeCalculator } from "bpm";
-    import { Easing, TemplateEasingLib } from "easing";
+    import { Easing, SegmentedEasing, TemplateEasing, TemplateEasingLib } from "easing";
     import { EventNodeSequence, EventStartNode, EventEndNode, EventNode } from "event";
     import { JudgeLine } from "judgeline";
     import { NNNList, NNNode } from "note";
@@ -1720,6 +1765,12 @@ declare module "chart" {
         nameAttach: JudgeLine | null;
         /** 难度等级显示绑定的判定线 */
         levelAttach: JudgeLine | null;
+        /** 仅用于构造时检查
+         * @internal
+         */
+        segmentedTemplates: Map<(SegmentedEasing & {
+            easing: TemplateEasing;
+        }), [string, TimeT]>;
         constructor();
         /**
          * 获取有效节拍数
@@ -1853,6 +1904,11 @@ declare module "chart" {
         bindTimeMacro(node: EventStartNode<any>, macroData: MacroData, pos: string): any;
         bindValueMacro(node: EventNode<any>, macroData: MacroData, pos: string): any;
         linkMacro(node: EventNode<EventValueESType>, linkData: MacroLink, pos: string): any;
+        checkErrors(): void;
+        /**
+         * 用于构造谱面时检查
+         */
+        protected checkSegmentedTemplates(): void;
     }
     /**
      * 表示一组判定线的容器
@@ -2023,6 +2079,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 +2211,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 +2240,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 +2272,8 @@ declare module "env" {
         NODES_NOT_CONTINUOUS = 2609,
         NODES_NOT_BELONG_TO_SAME_SEQUENCE = 2610,
         NODES_HAS_ZERO_DELTA = 2611,
+        TEMPLATE_EASING_CIRCULAR_REFERENCE = 2612,
+        EASING_DELTA_CANNOT_BE_ZERO = 2613,
         CANNOT_DIVIDE_EXPRESSION_EVALUATOR = 2352,
         MISSING_MACRO_EVALUATOR_KEY = 2336,
         MACRO_EVALUATOR_NOT_FOUND = 2337,
@@ -2263,6 +2324,8 @@ 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;
+        EASING_DELTA_CANNOT_BE_ZERO: (seqName: string, time: TimeT) => string;
     };
     interface ErrorMap extends Record<keyof typeof ERROR_IDS, Array<any>> {
         EVENT_NODE_NOT_DENSE: [EventNode];
@@ -2328,6 +2391,8 @@ 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>;
+            EASING_DELTA_CANNOT_BE_ZERO: (seqName: string, time: TimeT) => KPAError<ERROR_IDS.EASING_DELTA_CANNOT_BE_ZERO>;
         };
         freeze(): void;
     };
@@ -3027,6 +3092,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;