kipphi 2.0.1 → 2.1.1

package/README.md

@@ -1,9 +1,14 @@
-# Parse your chart into an editor-friendly format with Kipphi!
+# 用“奇谱”谱面内核将谱面解析为编辑器友好的格式！
+这是一个Phigros KPA、RPE谱面的解析器兼谱面操作系统。它是[KPA（奇谱发生器）](https://github.com/TeamZincs/KPA)的子项目。
 
-This is a Phigros KipphiApparatus/Re:PhiEdit ChartJSON Parser. It is a subproject of [KPA](https://github.com/TeamZincs/KPA).
+“奇谱”来自荷兰化学家启普，他发明了“启普发生器”，用于生产气体并随时停止反应。
 
-"Kipphi" comes from the Dutch chemist Kipp, who invented Kipp's Apparatus, which was used to produce gas and stop the reaction at any time.
+在(Phigros 自制谱Wiki)[https://pgrfm.miraheze.org/wiki]了解更多。
 
+# Parse your chart into an editor-friendly format with Kipphi!
 
-## Usage
+This is a Phigros KipphiApparatus/Re:PhiEdit ChartJSON Parser and Chart Operating System. It is a subproject of [KPA](https://github.com/TeamZincs/KPA).
+
+"Kipphi" comes from the Dutch chemist Kipp, who invented Kipp's Apparatus, which was used to produce gas and stop the reaction at any time.
 
+Learn more at [Phigros Custom Chart Wiki](https://pgrfm.miraheze.org/wiki).

package/basic.ts

@@ -0,0 +1,285 @@
+import { Chart } from "../chart";
+
+
+
+
+export type OpEventType = "do" | "undo" | "redo" | "error" | "needsupdate" | "maxcombochanged" | "noundo" | "noredo" | "firstmodified" | "needsreflow";
+
+// 最讲类型安全的一集（
+// 当然要有，不然的话编辑器那边检测的时候逆变会出问题
+
+interface DirectlyInstaciableEventMap {
+    "noundo": OpEvent;
+    "noredo": OpEvent;
+    "firstmodified": OpEvent;
+    "needsupdate": OpEvent;
+}
+
+// 创建一个类型来检测意外的 override
+// AI太好用了你知道吗
+type CheckFinalOverrides<T> = {
+    [K in keyof T]: K extends keyof OpEventMap ? 
+        T[K] extends OpEventMap[K] ? T[K] : never : 
+        T[K]
+};
+
+interface OpEventMap extends CheckFinalOverrides<DirectlyInstaciableEventMap> {
+    "error": OperationErrorEvent;
+    "maxcombochanged": MaxComboChangeEvent;
+    "undo": OperationEvent;
+    "redo": OperationEvent;
+    "do": OperationEvent;
+    "needsreflow": NeedsReflowEvent;
+}
+
+
+class OpEvent extends Event {
+    protected constructor(type: OpEventType) {
+        super(type);
+    }
+    /**
+     * 如果这个类型没有对应子类应该用这个
+     */
+    static create(type: keyof DirectlyInstaciableEventMap) {
+        return new OpEvent(type);
+    }
+}
+
+export class NeedsReflowEvent extends OpEvent {
+    constructor(public condition: number) {
+        super("needsreflow");
+    }
+}
+
+export class OperationEvent extends OpEvent {
+    constructor(t: "do" | "undo" | "redo" | "error", public operation: Operation) {
+        super(t);
+    }
+}
+
+export class OperationErrorEvent extends OperationEvent {
+    constructor(operation: Operation, public error: Error) {
+        super("error", operation);
+    }
+}
+
+export class MaxComboChangeEvent extends OpEvent {
+    constructor(public comboDelta: number) {
+        super("maxcombochanged");
+    }
+}
+
+
+
+export class OperationList extends EventTarget {
+    operations: Operation[];
+    undoneOperations: Operation[];
+    constructor(public chart: Chart) {
+        super()
+        this.operations = [];
+        this.undoneOperations = [];
+    }
+    undo() {
+        const op = this.operations.pop()
+        if (op) {
+            if (!this.chart.modified){
+                this.chart.modified = true;
+                this.dispatchEvent(OpEvent.create("firstmodified"))
+            }
+            
+            try {
+                op.undo(this.chart);
+            } catch (e) {
+                this.dispatchEvent(new OperationErrorEvent(op, e as Error))
+                return
+            }
+            this.undoneOperations.push(op)
+            this.dispatchEvent(new OperationEvent("undo", op))
+            this.processFlags(op);
+        } else {
+            this.dispatchEvent(OpEvent.create("noundo"))
+        }
+    }
+    redo() {
+        const op = this.undoneOperations.pop()
+        if (op) {
+            if (!this.chart.modified){
+                this.chart.modified = true;
+                this.dispatchEvent(OpEvent.create("firstmodified"))
+            }
+            
+            try {
+                op.do(this.chart);
+            } catch (e) {
+                this.dispatchEvent(new OperationErrorEvent(op, e as Error))
+                return
+            }
+            this.operations.push(op)
+            this.dispatchEvent(new OperationEvent("redo", op))
+            this.processFlags(op);
+        } else {
+            this.dispatchEvent(OpEvent.create("noredo"))
+        }
+    }
+    do(operation: Operation) {
+        if (operation.ineffective) {
+            return
+        }
+        if (!this.chart.modified){
+            this.chart.modified = true;
+            this.dispatchEvent(OpEvent.create("firstmodified"))
+        }
+        // 如果上一个操作是同一个构造器的，那么试图修改上一个操作而不是立即推入新的操作
+        if (this.operations.length !== 0) {
+                
+            const lastOp = this.operations[this.operations.length - 1]
+            if (operation.constructor === lastOp.constructor) {
+                // 返回值指示是否重写成功
+                if (lastOp.rewrite(operation)) {
+                    this.processFlags(operation)
+                    return;
+                }
+            }
+        }
+        try {
+            operation.do(this.chart);
+        } catch (e) {
+            this.dispatchEvent(new OperationErrorEvent(operation, e as Error))
+            return
+        }
+        this.dispatchEvent(new OperationEvent("do", operation));
+        this.processFlags(operation);
+        this.operations.push(operation);
+    }
+    processFlags(operation: Operation) {
+
+        if (operation.updatesEditor) {
+            this.dispatchEvent(OpEvent.create("needsupdate"));
+        }
+        if (operation.comboDelta) {
+            this.dispatchEvent(new MaxComboChangeEvent(operation.comboDelta));
+        }
+        if (operation.reflows) {
+            this.dispatchEvent(new NeedsReflowEvent(operation.reflows))
+        }
+    }
+    clear() {
+        this.operations = [];
+    }
+    addEventListener<T extends OpEventType>(type: T, listener: (event: OpEventMap[T]) => void, options?: boolean | AddEventListenerOptions): void {
+        super.addEventListener(type, listener, options);
+    }
+}
+
+
+export abstract class Operation {
+    ineffective: boolean;
+    updatesEditor: boolean;
+    // 用于判定线编辑区的重排，若操作完成时的布局为这个值就会重排
+    reflows: number;
+    /** 
+     * 此操作对谱面总物量产生了多少影响，正增负减。
+     * 
+     * 如果操作自身无法评估，应返回NaN，导致全谱重新数清物量
+     */
+    comboDelta: number;
+    constructor() {
+
+    }
+    abstract do(chart: Chart): void
+    abstract undo(chart: Chart): void
+    rewrite(op: typeof this): boolean {return false;}
+    toString(): string {
+        return this.constructor.name;
+    }
+    static lazy<C extends new (...args: any[]) => any = typeof this>(this: C, ...args: ConstructorParameters<C>) {
+        return new LazyOperation<C>(this, ...args)
+    }
+}
+
+
+
+
+/**
+ * 懒操作，实例化的时候不记录任何数据，do的时候才执行真正实例化
+ * 防止连续的操作中状态改变导致的错误
+ */
+export class LazyOperation<C extends new (...args: any[]) => any> extends Operation {
+    public operationClass: C;
+    public args: ConstructorParameters<C>;
+    public operation: InstanceType<C> | null = null;
+    constructor(
+        operationClass: C,
+        ...args: ConstructorParameters<C>
+    ) {
+        super();
+        this.operationClass = operationClass;
+        this.args = args;
+    }
+    do(chart: Chart) {
+        this.operation = new this.operationClass(...this.args);
+        this.operation.do(chart);
+    }
+    undo(chart: Chart) {
+        this.operation.undo(chart);
+    }
+}
+
+
+/**
+ * C语言借来的概念
+ * 
+ * 一个不确定类型的子操作
+ * 
+ * 注意这个操作不懒，会在构造时就实例化子操作
+ */
+export class UnionOperation<T extends Operation> extends Operation {
+    operation: T;
+    constructor(matcher: () => T) {
+        super();
+        this.operation = matcher();
+        if (!this.operation) {
+            this.ineffective = true;
+        }
+    }
+    // 这样子写不够严密，如果要继承这个类，并且子操作需要谱面，就要重写这个方法的签名
+    do(chart?: Chart) {
+        this.operation.do(chart);
+    }
+    undo(chart?: Chart) {
+        this.operation.undo(chart);
+    }
+}
+
+
+export class ComplexOperation<T extends Operation[]> extends Operation {
+    subOperations: T;
+    length: number;
+    constructor(...sub: T) {
+        super()
+        this.subOperations = sub
+        this.length = sub.length
+        this.reflows = sub.reduce((prev, op) => prev | op.reflows, 0);
+        this.updatesEditor = sub.some((op) => op.updatesEditor);
+        this.comboDelta = sub.reduce((prev, op) => prev + op.comboDelta, 0);
+    }
+    // 这样子写不够严密，如果要继承这个类，并且子操作需要谱面，就要重写这个方法的签名
+    do(chart?: Chart) {
+        const length = this.length
+        for (let i = 0; i < length; i++) {
+            const op = this.subOperations[i]
+            if (op.ineffective) {
+                continue;
+            }
+            op.do(chart)
+        }
+    }
+    undo(chart?: Chart) {
+        const length = this.length
+        for (let i = length - 1; i >= 0; i--) {
+            const op = this.subOperations[i]
+            if (op.ineffective) { continue; }
+            op.undo(chart)
+        }
+    }
+}

package/bpm.ts

@@ -8,58 +8,116 @@ import TC from "./time";
 /// #declaration:global
 
 /**
- * 
+ * BPM起始节点类，表示BPM变化的开始点
+ * 每个BPMStartNode代表一个BPM值的开始，直到下一个BPM节点
  */
 export class BPMStartNode extends EventStartNode {
+    /** 每拍的秒数(Seconds Per Beat) */
     spb: number;
+    /** 缓存的起始积分值，用于时间计算 */
     cachedStartIntegral?: number;
+    /** 缓存的积分值，用于时间计算 */
     cachedIntegral?: number;
+    /** 下一个BPM结束节点或尾部节点 */
     override next: BPMEndNode | BPMNodeLike<NodeType.TAIL>;
+    /** 上一个BPM结束节点或头部节点 */
     override previous: BPMEndNode | BPMNodeLike<NodeType.HEAD>;
+    
+    /**
+     * 创建一个新的BPM起始节点
+     * @param startTime 节点开始时间
+     * @param bpm BPM值
+     */
     constructor(startTime: TimeT, bpm: number) {
         super(startTime, bpm);
         this.spb = 60 / bpm;
     }
+    
+    /**
+     * 计算指定拍数对应的秒数
+     * @param beats 拍数
+     * @returns 对应的秒数
+     */
     getSeconds(beats: number): number {
         return (beats - TC.toBeats(this.time)) * 60 / this.value;
     }
+    
+    /**
+     * 获取当前BPM段的完整持续时间（秒）
+     * @this NonLastBPMStartNode 非最后一个BPM节点
+     * @returns 当前BPM段的持续时间（秒）
+     */
     getFullSeconds(this: NonLastBPMStartNode): number {
         return (TC.toBeats(this.next.time) - TC.toBeats(this.time)) * 60 / this.value;
     }
 }
+
+/**
+ * BPM结束节点类，表示BPM段的结束点
+ * 用于标记BPM段的结束位置
+ */
 export class BPMEndNode extends EventEndNode {
+    /** 每拍的秒数(Seconds Per Beat) */
     spb: number;
+    /** 前一个BPM起始节点 */
     override previous: BPMStartNode;
+    /** 下一个BPM起始节点 */
     override next: BPMStartNode;
+    
+    /**
+     * 创建一个新的BPM结束节点
+     * @param endTime 节点结束时间
+     */
     constructor(endTime: TimeT) {
         super(endTime, null);
     }
 }
 
+/** 非最后一个BPM起始节点类型 */
 type NonLastBPMStartNode = BPMStartNode & { next: BPMEndNode };
 
+/**
+ * BPM节点接口，定义了BPM节点的基本结构
+ */
 interface BPMNodeLike<T extends NodeType> extends EventNodeLike<T> {
+    /** 下一个节点 */
     next: [BPMStartNode, null, BNOrTail][T] | null;
+    /** 上一个节点 */
     previous: [null, BPMStartNode, BNOrHead][T] | null;
 }
+
+/** BPM节点类型 */
 type BPMNode = BPMStartNode | BPMEndNode;
+
+/** 任意BPM节点类型 */
 type AnyBN = (BPMNode | BPMNodeLike<NodeType.TAIL> | BPMNodeLike<NodeType.HEAD>);
+
+/** BPM节点或尾部节点类型 */
 type BNOrTail = BPMNode | BPMNodeLike<NodeType.TAIL>;
+
+/** BPM节点或头部节点类型 */
 type BNOrHead = BPMNode | BPMNodeLike<NodeType.HEAD>;
 
 /**
- * 拥有与事件类似的逻辑
- * 每对节点之间代表一个BPM相同的片段
+ * BPM序列类，管理BPM变化序列
+ * 拥有与事件类似的逻辑，每对节点之间代表一个BPM相同的片段
  * 片段之间BPM可以发生改变
  */
-
 export class BPMSequence extends EventNodeSequence {
+    /** 头部节点 */
     declare head: BPMNodeLike<NodeType.HEAD>;
+    /** 尾部节点 */
     declare tail: BPMNodeLike<NodeType.TAIL>;
-    /** 从拍数访问节点 */
-    override jump: JumpArray<AnyEN>;
-    /** 以秒计时的跳数组，处理从秒访问节点 */
+    /** 从拍数访问节点的跳转数组 */
+    declare jump: JumpArray<AnyBN>;
+    /** 以秒计时的跳转数组，处理从秒访问节点 */
     secondJump: JumpArray<AnyBN>;
+    
+    /**
+     * 创建BPM序列
+     * @param bpmList BPM片段数据列表
+     * @param duration 总持续时间
+     */
     constructor(bpmList: BPMSegmentData[], public duration: number) {
         super(EventType.bpm, null);
         let curPos: BPMNodeLike<NodeType.HEAD> | BPMEndNode = this.head;
@@ -79,8 +137,11 @@ export class BPMSequence extends EventNodeSequence {
         BPMStartNode.connect(last, this.tail);
         this.initJump();
     }
+    
+    /**
+     * 初始化跳转数组
+     */
     override initJump(): void {
-        console.log(this)
         this.effectiveBeats = TC.toBeats(this.tail.previous.time)
         if (this.effectiveBeats !== 0) {
             super.initJump(); // 为0可以跳过jumpArray，用不到
@@ -88,6 +149,10 @@ export class BPMSequence extends EventNodeSequence {
         }
         this.updateSecondJump();
     }
+    
+    /**
+     * 更新秒跳转数组
+     */
     updateSecondJump(): void {
         let integral = 0;
         // 计算积分并缓存到BPMNode
@@ -114,7 +179,7 @@ export class BPMSequence extends EventNodeSequence {
             this.tail,
             originalListLength,
             this.duration,
-            (node: BPMStartNode) => {
+            (node: AnyBN) => {
                 if (node.type === NodeType.TAIL) {
                     return [null, null];
                 }
@@ -135,11 +200,22 @@ export class BPMSequence extends EventNodeSequence {
             }
         );
     }
+    
+    /**
+     * 更新跳转数组
+     * @param from 起始节点
+     * @param to 结束节点
+     */
     override updateJump(from: ENOrHead, to: ENOrTail): void {
         super.updateJump(from, to);
         this.updateSecondJump();
     }
 
+    /**
+     * 根据秒数获取BPM起始节点
+     * @param seconds 秒数
+     * @returns 对应的BPM起始节点
+     */
     getNodeBySeconds(seconds: number): BPMStartNode {
         if (this.effectiveBeats === 0) {
             return this.tail.previous
@@ -150,6 +226,11 @@ export class BPMSequence extends EventNodeSequence {
         }
         return node as BPMStartNode;
     }
+    
+    /**
+     * 导出BPM数据
+     * @returns BPM片段数据数组
+     */
     dumpBPM(): BPMSegmentData[] {
         let cur = this.head.next;
         const ret: BPMSegmentData[] = [];
@@ -166,43 +247,81 @@ export class BPMSequence extends EventNodeSequence {
         } 
         return ret;
     }
+    
+    /**
+     * 根据拍数获取节点
+     * @param beats 拍数
+     * @param usePrev 是否使用前一个节点
+     * @returns 对应的BPM起始节点
+     */
     getNodeAt(beats: number, usePrev?: boolean): BPMStartNode {
         return super.getNodeAt(beats, usePrev) as BPMStartNode;
     }
 }
 
+/**
+ * 时间计算器类，用于处理拍数与秒数之间的转换
+ */
 export class TimeCalculator {
+    /** BPM片段数据列表 */
     bpmList: BPMSegmentData[];
-    bpmSequence: BPMSequence;
+    /** BPM序列 */
+    readonly bpmSequence: BPMSequence;
+    /** 总持续时间 */
     duration: number;
 
+    /**
+     * 创建时间计算器
+     */
     constructor() {
     }
 
+    /**
+     * 初始化BPM序列
+     */
     initSequence() {
         const bpmList = this.bpmList;
+        // @ts-expect-error 不在构造器中初始化的只读属性
         this.bpmSequence = new BPMSequence(bpmList, this.duration);
     }
+    
+    /**
+     * 将拍数转换为秒数
+     * @param beats 拍数
+     * @returns 对应的秒数
+     */
     toSeconds(beats: number) {
         const node: BPMStartNode = this.bpmSequence.getNodeAt(beats);
         return node.cachedStartIntegral + node.getSeconds(beats)
     }
+    
     /**
      * 获取从beats1到beats2的秒数
-     * @param beats1 
-     * @param beats2 
-     * @returns 
+     * @param beats1 起始拍数
+     * @param beats2 结束拍数
+     * @returns 两拍数之间的秒数差
      */
     segmentToSeconds(beats1: number, beats2: number): number {
         const ret = this.toSeconds(beats2) - this.toSeconds(beats1)
         return ret
     }
+    
+    /**
+     * 将秒数转换为拍数
+     * @param seconds 秒数
+     * @returns 对应的拍数
+     */
     secondsToBeats(seconds: number) {
         const node = this.bpmSequence.getNodeBySeconds(seconds);
         // console.log("node:", node)
         const beats = (seconds - node.cachedStartIntegral) / node.spb;
         return TC.toBeats(node.time) + beats
     }
+    
+    /**
+     * 导出BPM数据
+     * @returns BPM片段数据数组
+     */
     dump(): BPMSegmentData[] {
         return this.bpmSequence.dumpBPM();
     }
@@ -210,4 +329,4 @@ export class TimeCalculator {
 }
 
 
-/// #enddeclaration
+/// #enddeclaration