kipphi 2.0.0 → 2.1.0

package/README.md

@@ -4,6 +4,4 @@ This is a Phigros KipphiApparatus/Re:PhiEdit ChartJSON Parser. It is a subprojec
 
 "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.
 
-
-## Usage
-
+警告：KPA 2.1版本发布以前均为实验性代码，可能会出现API兼容性问题，当前不建议将此代码用于生产！

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

@@ -0,0 +1,332 @@
+import { EventType, type BPMSegmentData, type TimeT } from "./chartTypes";
+import { EventEndNode, EventNodeLike, EventNodeSequence, EventStartNode, type AnyEN, type ENOrHead, type ENOrTail } from "./event";
+import { JumpArray } from "./jumparray";
+import { NodeType } from "./util";
+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可以发生改变
+ */
+export class BPMSequence extends EventNodeSequence {
+    /** 头部节点 */
+    declare head: BPMNodeLike<NodeType.HEAD>;
+    /** 尾部节点 */
+    declare tail: BPMNodeLike<NodeType.TAIL>;
+    /** 从拍数访问节点的跳转数组 */
+    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;
+        let next = bpmList[0];
+        this.listLength = bpmList.length;
+        for (let i = 1; i < bpmList.length; i++) {
+            const each = next;
+            next = bpmList[i];
+            const startNode = new BPMStartNode(each.startTime, each.bpm);
+            const endNode = new BPMEndNode(next.startTime);
+            BPMStartNode.connect(startNode, endNode);
+            BPMStartNode.connect(curPos, startNode);
+            curPos = endNode;
+        }
+        const last = new BPMStartNode(next.startTime, next.bpm)
+        BPMStartNode.connect(curPos, last);
+        BPMStartNode.connect(last, this.tail);
+        this.initJump();
+    }
+    
+    /**
+     * 初始化跳转数组
+     */
+    override initJump(): void {
+        this.effectiveBeats = TC.toBeats(this.tail.previous.time)
+        if (this.effectiveBeats !== 0) {
+            super.initJump(); // 为0可以跳过jumpArray，用不到
+            // 只有一个BPM片段就会这样
+        }
+        this.updateSecondJump();
+    }
+    
+    /**
+     * 更新秒跳转数组
+     */
+    updateSecondJump(): void {
+        let integral = 0;
+        // 计算积分并缓存到BPMNode
+        let node: BPMStartNode = this.head.next;
+        while (true) {
+            node.cachedStartIntegral = integral;
+            if (node.next.type === NodeType.TAIL) {
+                break;
+            }
+            integral += (node as NonLastBPMStartNode).getFullSeconds();
+
+            const endNode = <BPMEndNode>(<BPMStartNode>node).next;
+            node.cachedIntegral = integral;
+
+            node = endNode.next;
+        }
+        node.cachedStartIntegral = integral;
+        if (this.effectiveBeats  === 0) {
+            return;
+        }
+        const originalListLength = this.listLength;
+        this.secondJump = new JumpArray<AnyBN>(
+            this.head,
+            this.tail,
+            originalListLength,
+            this.duration,
+            (node: AnyBN) => {
+                if (node.type === NodeType.TAIL) {
+                    return [null, null];
+                }
+                if (node.type === NodeType.HEAD) {
+                    return [0, node.next];
+                }
+                const endNode = <BPMEndNode>(<BPMStartNode>node).next;
+                const time = node.cachedIntegral;
+                const nextNode = endNode.next;
+                if (nextNode.next.type === NodeType.TAIL) {
+                    return [time, nextNode.next]; // Tailer代替最后一个StartNode去占位
+                } else {
+                    return [time, nextNode];
+                }
+            },
+            (node: BPMStartNode, seconds: number) => {
+                return node.cachedIntegral > seconds ? false : (<BPMEndNode>node.next).next;
+            }
+        );
+    }
+    
+    /**
+     * 更新跳转数组
+     * @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
+        }
+        const node = this.secondJump.getNodeAt(seconds);
+        if (node.type === NodeType.TAIL) {
+            return node.previous;
+        }
+        return node as BPMStartNode;
+    }
+    
+    /**
+     * 导出BPM数据
+     * @returns BPM片段数据数组
+     */
+    dumpBPM(): BPMSegmentData[] {
+        let cur = this.head.next;
+        const ret: BPMSegmentData[] = [];
+        while (true) {
+            ret.push({
+                bpm: cur.value,
+                startTime: cur.time
+            })
+            const end = cur.next;
+            if (end.type === NodeType.TAIL) {
+                break;
+            }
+            cur = end.next;
+        } 
+        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[];
+    /** 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 两拍数之间的秒数差
+     */
+    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();
+    }
+
+}
+
+
+/// #enddeclaration