kipphi 2.0.0 → 2.1.0

package/env.ts

@@ -1,7 +1,215 @@
 
+// chart              1
+// bpm                2
+// nnnlist            3
+// judgeline          4
+// nnList             5
+// EventNodeSequence  6
+// notenode           7
+// eventnode          8
+// evaluator          9
+// easing             a
+// note               b
+
+
+// 就挺神奇的！明明typeof后面跟值，这里却可以写成类型导入
+import { type TimeT, type EventValueType } from "./chartTypes";
+import { EventNode } from "./event";
+import { toTimeString } from "./util";
+
+// occupied 1
+// invalid data 2
+// invalid usage 3
+
+const
+    CHART = 0x100,
+    BPM = 0x200,
+    NNN_LIST = 0x300,
+    JUDGE_LINE = 0x400,
+    NN_LIST = 0x500,
+    ENS = 0x600,
+    NOTE_NODE = 0x700,
+    EVENT_NODE = 0x800,
+    EVALUATOR = 0x900,
+    EASING = 0xA00,
+    NOTE = 0xB00,
+    TC = 0xC00,
+    MACRO = 0xD00,
+    INTERNAL = 0xF00,
+
+    OCCPIED = 0x10,
+    INVALID_DATA = 0x20, // 一般是指读取谱面时的无效事件类型、缓动号等等
+    INVALID_USAGE = 0x30, // 不知道归入哪里就放这吧（（（
+    INVALID_TYPE = 0x40 // 这里的type指ECMAScript数据类型，事件类型错误可以归入此类
+    ;
+
+
+
+export enum ERROR_IDS {
+    UI_OCCUPIED =                                   CHART      | OCCPIED,
+
+
+    SEQUENCE_NAME_OCCUPIED =                        ENS        | OCCPIED       | 0,
+    SEQUENCE_NODE_TIME_OCCUPIED =                   ENS        | OCCPIED       | 1,
+    INVALID_EVENT_NODE_SEQUENCE_TYPE =              ENS        | INVALID_DATA  | 0,
+    EVENT_NODE_TIME_NOT_INCREMENTAL =               ENS        | INVALID_DATA  | 1,
+    PARENT_SEQUENCE_NOT_FOUND =                     ENS        | INVALID_USAGE | 1,
+    NEEDS_AT_LEAST_ONE_ENS =                        ENS        | INVALID_USAGE | 2,
+    SEQUENCE_TYPE_NOT_CONSISTENT =                  ENS        | INVALID_USAGE | 3,
+    
+    EXPECTED_TYPED_ENS =                            ENS        | INVALID_TYPE  | 0,
+
+    CANNOT_SUBSTITUTE_EXPRESSION_EVALUATOR =        EVENT_NODE | INVALID_USAGE | 0,
+    CANNOT_INSERT_BEFORE_HEAD =                     EVENT_NODE | INVALID_USAGE | 1,
+    CANNOT_GET_FULL_INTEGRAL_OF_FINAL_START_NODE =  EVENT_NODE | INVALID_USAGE | 2,
+    CANNOT_INTERPOLATE_TAILING_START_NODE =         EVENT_NODE | INVALID_USAGE | 3,
+
+    INVALID_EASING_ID =                             EASING     | INVALID_DATA  | 0,
+    CANNOT_IMPLEMENT_TEMEAS_WITH_NON_EASING_ENS =   EASING     | INVALID_DATA  | 1,
+    CANNOT_IMPLEMENT_TEMEAS_WITH_NON_NUMERIC_ENS =  EASING     | INVALID_DATA  | 2,
+    UNIMPLEMENTED_TEMPLATE_EASING =                 EASING     | INVALID_DATA  | 3,
+    MUST_INTERPOLATE_TEMPLATE_EASING =              EASING     | INVALID_USAGE | 0,
+    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,
+
+    CANNOT_DIVIDE_EXPRESSION_EVALUATOR =            EVALUATOR  | INVALID_USAGE | 0,
+    MISSING_MACRO_EVALUATOR_KEY =                   EVALUATOR  | INVALID_DATA  | 0,
+    MACRO_EVALUATOR_NOT_FOUND =                     EVALUATOR  | INVALID_DATA  | 1,
+    
+    
+
+    INVALID_NOTE_PROP_TYPE =                        NOTE       | INVALID_TYPE  | 0,
+
+
+    INVALID_TIME_TUPLE =                            TC         | INVALID_DATA  | 0,
+
+    TIME_MACRO_NOT_FOUND =                          MACRO      | INVALID_DATA  | 0,
+    VALUE_MACRO_NOT_FOUND =                         MACRO      | INVALID_DATA  | 1,
+    UNKNOWN_MACRO_EXPRESSION =                      MACRO      | INVALID_DATA  | 2,
+    JAVASCRIPT_SYNTAX_ERROR =                       MACRO      | INVALID_DATA  | 3,
+    PROTO_PRESENT_IN_NONPARAMETRIC =                MACRO      | INVALID_USAGE | 0,
+    PARAMETRIC_MACRO_REQUIRES_PROTO_KEY =           MACRO      | INVALID_DATA  | 4,
+    MACRO_NOT_PARAMETRIC =                          MACRO      | INVALID_DATA  | 5,
+}
+
+export const ERRORS = {
+    UI_OCCUPIED: (name: string) =>
+        `UI '${name}' is occupied`,
+
+    
+    SEQUENCE_NAME_OCCUPIED: (name: string) =>
+        `Sequence name '${name}' is occupied`,
+    SEQUENCE_NODE_TIME_OCCUPIED: (time: TimeT, id: string) => 
+        `Time ${toTimeString(time)} already has a node (in sequence ${id})`,
+    INVALID_EVENT_NODE_SEQUENCE_TYPE: (type: any) =>
+        `Invalid event node sequence type: '${type}'`,
+    EXPECTED_TYPED_ENS: (typeStr: keyof typeof EventValueType, id: string, value: unknown) =>
+        `Expected EventNodeSequence for ${typeStr} but seen value ${value} (Processing ${id})`,
+    EVENT_NODE_TIME_NOT_INCREMENTAL: (pos: string) =>
+        `EventNode time is not incremental (at ${pos})`,
+    PARENT_SEQUENCE_NOT_FOUND: (nodeTime: TimeT) =>
+        `Parent EventNodeSequence not found for an EventNode at time ${toTimeString(nodeTime)} (Did you forget to add it to a sequence?)`,
+    NEEDS_AT_LEAST_ONE_ENS: () =>
+        `Needs at least one EventNodeSequence`,
+    SEQUENCE_TYPE_NOT_CONSISTENT: (typeStr: string, but: string) =>
+        `EventNodeSequence type is not consistent (expected ${typeStr} but seen value ${but})`,
+    
+    
+    CANNOT_SUBSTITUTE_EXPRESSION_EVALUATOR: () =>
+        `Cannot substitute ExpressionEvaluator`,
+    CANNOT_INSERT_BEFORE_HEAD: () =>
+        "Cannot insert before the first EventStartNode",
+    CANNOT_GET_FULL_INTEGRAL_OF_FINAL_START_NODE: () =>
+        "Cannot get full integral of final start node",
+    CANNOT_INTERPOLATE_TAILING_START_NODE: () =>
+        "Cannot interpolate tailing start node",
+
+    INVALID_EASING_ID: (id: string) =>
+        `Invalid easing id: '${id}'`,
+    CANNOT_IMPLEMENT_TEMEAS_WITH_NON_EASING_ENS: (temEasName: string) =>
+        `Cannot implement TemplateEasing with a non-easing-typed EventNodeSequence (Processing template '${temEasName}')`, 
+    CANNOT_IMPLEMENT_TEMEAS_WITH_NON_NUMERIC_ENS: (temEasName: string) =>
+        `Cannot implement TemplateEasing with a non-numeric EventNodeSequence (Processing template '${temEasName}')`, 
+    MUST_INTERPOLATE_TEMPLATE_EASING: () =>
+        "Must interpolate template easing",
+    
+    NODES_NOT_CONTINUOUS: () =>
+        "The EventNodes to encapsulate are not continuous",
+    NODES_NOT_BELONG_TO_SAME_SEQUENCE: () =>
+        "The EventNodes to encapsulate does not belong to same sequence",
+    NODES_HAS_ZERO_DELTA: () =>
+        "The EventNodes to encapsulate has zero delta",
+
+    INVALID_NOTE_PROP_TYPE: (prop: string, value: any, type: any) =>
+        `Invalid type for ${prop}. Got *${value}*, expected ${type}`,
+
+    INVALID_TIME_TUPLE: (tuple: any) =>
+        `Invalid time tuple: '${typeof tuple === "undefined" ? 'undefined' : tuple.valueOf()}'`,
+
+
+
+
+    CANNOT_DIVIDE_EXPRESSION_EVALUATOR: (id: string) =>
+        `Cannot divide ExpressionEvaluator (Compiling ${id})`,
+
+
+    UNIMPLEMENTED_TEMPLATE_EASING: (temEasName: string) =>
+        `Unimplemented template easing: '${temEasName}'`,
+
+    MISSING_MACRO_EVALUATOR_KEY: (pos: string) =>
+        `Missing Macro Evaluator key. At ${pos}`,
+    MACRO_EVALUATOR_NOT_FOUND: (evaluatorId: string, pos: string) =>
+        `Macro Evaluator '${evaluatorId}' not found. At ${pos}`,
+    TIME_MACRO_NOT_FOUND: (macroId: string, pos: string) =>
+        `Time Macro '${macroId}' not found. At ${pos}`,
+    VALUE_MACRO_NOT_FOUND: (macroId: string, pos: string) =>
+        `Value Macro '${macroId}' not found. At ${pos}`,
+    UNKNOWN_MACRO_EXPRESSION: (expression: string, macroId: string) =>
+        `Unknown Macro Expression '${expression}'. At ${macroId}`,
+    PROTO_PRESENT_IN_NONPARAMETRIC: (macroId: string) =>
+        `'@proto can only be used in parametric Macros. At ${macroId}'`,
+    JAVASCRIPT_SYNTAX_ERROR: (error: Error, macroId: string) =>
+        `JavaScript Syntax Error: ${error.message}. At ${macroId}`,
+    PARAMETRIC_MACRO_REQUIRES_PROTO_KEY: (pos) =>
+        `Parametric Macro requires key. At ${pos}`,
+    MACRO_NOT_PARAMETRIC: (macroId: string, pos) =>
+        `Macro '${macroId}' is not parametric. At ${pos}`,
+} satisfies Record<keyof typeof ERROR_IDS, (...args: any[]) => string>
+
+export class KPAError<ET extends ERROR_IDS> extends Error {
+    constructor(message: string, public id: ET) {
+        super(message);
+    }
+    /**
+     * 对于解析谱面等场景，有时可能需要找出全部的错误，不宜直接抛出错误中断代码执行
+     * 
+     * 此时可以调用该方法，该方法会输出错误并把它保存到KPAError的一个`buffer`静态属性下。
+     */
+    warn() {
+        console.warn(this.stack);
+        KPAError.buffer.push(this);
+    }
+    static buffer: KPAError<ERROR_IDS>[] = [];
+    static flush() {
+        KPAError.buffer = [];
+    }
+}
+
+export const err = new Proxy(ERRORS, {
+    get(target, name) {
+        return (...args: any[]) => new KPAError(target[name](...args) + `(KP${ERROR_IDS[name].toString(16)})`, ERROR_IDS[name]);
+    }
+}) as unknown as { [key in keyof typeof ERRORS]: (...args: Parameters<typeof ERRORS[key]>) => KPAError<typeof ERROR_IDS[key]>};
+
 export default {
     DEFAULT_TEMPLATE_LENGTH: 16,
     BEZIER_INTERPOLATION_DENSITY: 256,
     NNLIST_Y_OFFSET_HALF_SPAN: 100,
+    JUMPARRAY_MIN_LENGTH: 64,
+    JUMPARRAY_MAX_LENGTH: 4096,
+    JUMPARRAY_MINOR_SCALE_COUNT: 16,
+    ERROR_IDS,
+    err,
     freeze() { Object.freeze(this); }
 }

package/evaluator.ts

@@ -6,11 +6,13 @@ import {
 } from "./easing";
 
 
-import { TimeCalculator as TC } from "./time" 
+import TC from "./time";
 
-import type { Chart } from "./chart";
-import type { EventEndNode, EventStartNode } from "./event";
-import { EvaluatorType, EventValueType, InterpreteAs, type ColorEasedEvaluatorKPA2, type EasedEvaluatorDataOfType, type EvaluatorDataKPA2, type EventValueESType, type EventValueTypeOfType, type ExpressionEvaluatorDataKPA2, type NumericEasedEvaluatorKPA2, type RGB, type TextEasedEvaluatorKPA2 } from "./chartTypes";
+import type { EventEndNode, EventStartNode, NonLastStartNode } from "./event";
+import { EasingType, EvaluatorType, EventValueType, EventValueTypeOfType, InterpreteAs, MacroEvaluatorBodyData, MacroEvaluatorDataKPA2, type ColorEasedEvaluatorKPA2, type EvaluatorDataKPA2, type EventValueESType, type ExpressionEvaluatorDataKPA2, type NumericEasedEvaluatorKPA2, type RGB, type TextEasedEvaluatorKPA2 } from "./chartTypes";
+import type { JudgeLine } from "./judgeline";
+import { Chart } from "./chart";
+import { EVENT_MACROS } from "./macro";
 
 
 /// #declaration:global
@@ -24,19 +26,19 @@ import { EvaluatorType, EventValueType, InterpreteAs, type ColorEasedEvaluatorKP
  * @immutable
  * @since 2.0.0
  */
-export abstract class Evaluator<T> {
-    abstract eval(event: EventStartNode<T>, beats: number): T;
-    abstract dump(): EvaluatorDataKPA2<T>;
+export abstract class Evaluator<T extends EventValueESType> {
+    abstract eval(event: NonLastStartNode<T>, beats: number): T;
+    abstract dumpFor(node: EventStartNode<T>): EvaluatorDataKPA2<T>;
 }
 
 
-export abstract class EasedEvaluator<T> extends Evaluator<T> {
+export abstract class EasedEvaluator<T extends EventValueESType> extends Evaluator<T> {
     readonly easing: Easing;
     constructor(easing: Easing) {
         super();
         this.easing = easing;
     }
-    override eval(startNode: EventStartNode<T> & { next: EventEndNode }, beats: 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)
@@ -48,7 +50,31 @@ export abstract class EasedEvaluator<T> extends Evaluator<T> {
         // 其他类型，包括普通缓动和非钩定模板缓动
         return this.convert(value, nextValue, this.easing.getValue(current / timeDelta));
     }
-    abstract convert(start: T, end: T, t: number): T;
+    abstract convert(start: T, end: T, progress: number): T;
+    /**
+     * 派生一个类型相同但使用不同缓动的求值器
+     * @param easing 
+     * @returns 
+     */
+    abstract deriveWithEasing(easing: Easing): EasedEvaluator<T>;
+
+    static getEvaluatorFromEasing<T extends EventValueESType>(type: EventValueTypeOfType<T>, easing: Easing, interpretedAs?: InterpreteAs): EasedEvaluatorOfType<T> {
+        const easingIsNormal = easing instanceof NormalEasing;
+        switch (type) {
+            case EventValueType.numeric:
+                return easingIsNormal
+                    ? NumericEasedEvaluator.evaluatorsOfNormalEasing[easing.rpeId] as EasedEvaluatorOfType<T>
+                    : new NumericEasedEvaluator(easing) as EasedEvaluatorOfType<T>;
+            case EventValueType.color:
+                return easingIsNormal
+                    ? ColorEasedEvaluator.evaluatorsOfNormalEasing[easing.rpeId] as EasedEvaluatorOfType<T>
+                    : new ColorEasedEvaluator(easing) as EasedEvaluatorOfType<T>;
+            case EventValueType.text:
+                return easingIsNormal
+                    ? TextEasedEvaluator.evaluatorsOfNoEzAndItpAs[easing.rpeId][interpretedAs ?? InterpreteAs.str] as EasedEvaluatorOfType<T>
+                    : new TextEasedEvaluator(easing, interpretedAs) as EasedEvaluatorOfType<T>
+        }
+    }
 }
 
 export type EasedEvaluatorOfType<T extends EventValueESType> = T extends number ? NumericEasedEvaluator : T extends RGB ? ColorEasedEvaluator : TextEasedEvaluator;
@@ -59,7 +85,7 @@ export class NumericEasedEvaluator extends EasedEvaluator<number> {
         super(easing);
     }
     private cache?: NumericEasedEvaluatorKPA2
-    override dump(): NumericEasedEvaluatorKPA2 {
+    override dumpFor(): NumericEasedEvaluatorKPA2 {
         return this.cache ??= {
             type: EvaluatorType.eased,
             easing: this.easing.dump()
@@ -70,13 +96,20 @@ export class NumericEasedEvaluator extends EasedEvaluator<number> {
     }
     static default = new NumericEasedEvaluator(linearEasing);
     static evaluatorsOfNormalEasing: NumericEasedEvaluator[] = rpeEasingArray.map(easing => new NumericEasedEvaluator(easing));
+    override deriveWithEasing(easing: Easing): NumericEasedEvaluator {
+        if (easing instanceof NormalEasing) {
+            return NumericEasedEvaluator.evaluatorsOfNormalEasing[easing.rpeId];
+        } else {
+            return new NumericEasedEvaluator(easing);
+        }
+    }
 }
 
 export class ColorEasedEvaluator extends EasedEvaluator<RGB> {
     constructor(easing: Easing) {
         super(easing);
     }
-    override dump(): ColorEasedEvaluatorKPA2 {
+    override dumpFor(): ColorEasedEvaluatorKPA2 {
         return {
             type: EvaluatorType.eased,
             easing: this.easing.dump()
@@ -90,6 +123,13 @@ export class ColorEasedEvaluator extends EasedEvaluator<RGB> {
     }
     static default = new ColorEasedEvaluator(linearEasing);
     static evaluatorsOfNormalEasing: ColorEasedEvaluator[] = rpeEasingArray.map(easing => new ColorEasedEvaluator(easing));
+    override deriveWithEasing(easing: Easing): ColorEasedEvaluator {
+        if (easing instanceof NormalEasing) {
+            return ColorEasedEvaluator.evaluatorsOfNormalEasing[easing.rpeId];
+        } else {
+            return new ColorEasedEvaluator(easing);
+        }
+    }
 }
 
 
@@ -102,18 +142,16 @@ export class ColorEasedEvaluator extends EasedEvaluator<RGB> {
  */
 export class TextEasedEvaluator extends EasedEvaluator<string> {
     constructor(easing: Easing,
-        public readonly interpretedAs: InterpreteAs = InterpreteAs.str,
-        public readonly font: string = "cmdysj.ttf"
+        public readonly interpretedAs: InterpreteAs = InterpreteAs.str
     )
     {
         super(easing);
     }
-    override dump(): TextEasedEvaluatorKPA2 {
+    override dumpFor(): TextEasedEvaluatorKPA2 {
         return {
             type: EvaluatorType.eased,
             easing: this.easing.dump(),
-            interpretedAs: this.interpretedAs,
-            font: this.font
+            interpretedAs: this.interpretedAs
         }
     }
     override convert(value: string, nextValue: string, progress: number): string {
@@ -148,21 +186,69 @@ export class TextEasedEvaluator extends EasedEvaluator<string> {
         new TextEasedEvaluator(easing, InterpreteAs.int),
         new TextEasedEvaluator(easing, InterpreteAs.float),
     ]);
+    override deriveWithEasing(easing: Easing): EasedEvaluator<string> {
+        if (easing instanceof NormalEasing) {
+            return TextEasedEvaluator.evaluatorsOfNoEzAndItpAs[easing.rpeId][this.interpretedAs];
+        } else {
+            return new TextEasedEvaluator(easing, this.interpretedAs);
+        }
+    }
+}
+
+
+
+export class MacroEvaluator<T extends EventValueESType> extends Evaluator<T> {
+    readonly consumers: Map<EventStartNode<T>, ExpressionEvaluator<T>> = new Map();
+    constructor(public expression: string, public id: string) {
+        super();
+    }
+    compile(node: EventStartNode<T>, chart: Chart): ExpressionEvaluator<T> {
+        const jsExpr = this.expression
+        .replace(/@([a-z\.]+)/, (k) => {
+            return JSON.stringify(EVENT_MACROS[k](node, chart)) + " "
+        }).replace(/@\{\{(.+?)\}\}/g, (k) => {
+            const replaced = k.replace(new RegExp(Object.keys(EVENT_MACROS).join("|"), "g"), (k) => {
+                return JSON.stringify(EVENT_MACROS[k](node, chart)) + " "
+            });
+            return JSON.stringify(new Function("return " + replaced)()) + " ";
+        });
+        return new ExpressionEvaluator(jsExpr);
+    }
+    assignTo(node: EventStartNode<T>, chart: Chart): void {
+        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);
+    }
+    dumpFor(node: EventStartNode<T>): MacroEvaluatorDataKPA2 {
+        return {
+            type: EvaluatorType.macro,
+            name: this.id,
+            compiled: this.consumers.get(node)!.jsExpr
+        }
+    }
+    dumpContent(): MacroEvaluatorBodyData {
+        return {
+            id: this.id,
+            macro: this.expression
+        }
+    }
 }
 
-export class ExpressionEvaluator<T> extends Evaluator<T> {
+export class ExpressionEvaluator<T extends EventValueESType> extends Evaluator<T> {
     readonly func: (t: number) => T;
     constructor(public readonly jsExpr: string) {
         super();
         this.func = new Function("t", "return " + jsExpr) as (t: number) => T;
     }
-    override eval(startNode: EventStartNode<T> & { next: EventEndNode }, beats: 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 dump(): ExpressionEvaluatorDataKPA2 {
+    override dumpFor(): ExpressionEvaluatorDataKPA2 {
         return {
             type: EvaluatorType.expressionbased,
             jsExpr: this.jsExpr