@rian8337/osu-droid-replay-analyzer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Rian8337
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# `osu-droid-replay-analyzer`
+
+> TODO: description
+
+## Usage
+
+```
+const osuDroidReplayAnalyzer = require('osu-droid-replay-analyzer');
+
+// TODO: DEMONSTRATE API
+```

package/dist/ReplayAnalyzer.js

@@ -0,0 +1,540 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplayAnalyzer = void 0;
+const osu_base_1 = require("@rian8337/osu-base");
+const osu_difficulty_calculator_1 = require("@rian8337/osu-difficulty-calculator");
+const osu_rebalance_difficulty_calculator_1 = require("@rian8337/osu-rebalance-difficulty-calculator");
+const unzipper_1 = require("unzipper");
+const javaDeserialization = __importStar(require("java-deserialization"));
+const stream_1 = require("stream");
+const ReplayData_1 = require("./data/ReplayData");
+const ThreeFingerChecker_1 = require("./analysis/ThreeFingerChecker");
+const TwoHandChecker_1 = require("./analysis/TwoHandChecker");
+const movementType_1 = require("./constants/movementType");
+const hitResult_1 = require("./constants/hitResult");
+/**
+ * A replay analyzer that analyzes a replay from osu!droid.
+ *
+ * Created by reverse engineering the replay parser from the game itself, which can be found {@link https://github.com/osudroid/osu-droid/blob/master/src/ru/nsu/ccfit/zuev/osu/scoring/Replay.java here}.
+ *
+ * Once analyzed, the result can be accessed via the `data` property.
+ */
+class ReplayAnalyzer {
+    constructor(values) {
+        /**
+         * The original odr file of the replay.
+         */
+        this.originalODR = null;
+        /**
+         * The fixed odr file of the replay.
+         */
+        this.fixedODR = null;
+        /**
+         * The results of the analyzer. `null` when initialized.
+         */
+        this.data = null;
+        /**
+         * Penalty value used to penalize dpp for 2-hand.
+         */
+        this.aimPenalty = 1;
+        /**
+         * Penalty value used to penalize dpp for 3 finger abuse.
+         */
+        this.tapPenalty = 1;
+        /**
+         * Whether this replay has been checked against 3 finger usage.
+         */
+        this.hasBeenCheckedFor3Finger = false;
+        /**
+         * Whether this replay has been checked against 2 hand usage.
+         */
+        this.hasBeenCheckedFor2Hand = false;
+        // Sizes of primitive data types in Java (in bytes)
+        this.BYTE_LENGTH = 1;
+        this.SHORT_LENGTH = 2;
+        this.INT_LENGTH = 4;
+        this.FLOAT_LENGTH = 4;
+        this.LONG_LENGTH = 8;
+        this.scoreID = values.scoreID;
+        this.map = values.map;
+    }
+    /**
+     * Analyzes a replay.
+     */
+    async analyze() {
+        if (!this.originalODR && !this.fixedODR) {
+            this.originalODR = await this.downloadReplay();
+        }
+        if (!this.originalODR) {
+            return this;
+        }
+        if (!this.fixedODR) {
+            this.fixedODR = await this.decompress().catch(() => {
+                return null;
+            });
+        }
+        if (!this.fixedODR) {
+            return this;
+        }
+        this.parseReplay();
+        return this;
+    }
+    /**
+     * Downloads the given score ID's replay.
+     */
+    async downloadReplay() {
+        const apiRequestBuilder = new osu_base_1.DroidAPIRequestBuilder()
+            .setRequireAPIkey(false)
+            .setEndpoint("upload")
+            .addParameter("", `${this.scoreID}.odr`);
+        const result = await apiRequestBuilder.sendRequest();
+        if (result.statusCode !== 200) {
+            return null;
+        }
+        return result.data;
+    }
+    /**
+     * Decompresses a replay.
+     *
+     * The decompressed replay is in a form of Java object. This will be converted to a buffer and deserialized to read data from the replay.
+     */
+    decompress() {
+        return new Promise((resolve, reject) => {
+            const stream = new stream_1.Readable();
+            stream.push(this.originalODR);
+            stream.push(null);
+            stream
+                .pipe((0, unzipper_1.Parse)())
+                .on("entry", async (entry) => {
+                const fileName = entry.path;
+                if (fileName === "data") {
+                    return resolve(await entry.buffer());
+                }
+                else {
+                    entry.autodrain();
+                }
+            })
+                .on("error", (e) => {
+                setTimeout(() => reject(e), 2000);
+            });
+        });
+    }
+    /**
+     * Parses a replay after being downloaded and converted to a buffer.
+     */
+    parseReplay() {
+        // javaDeserialization can only somewhat parse some string field
+        // the rest will be a buffer that we need to manually parse
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let rawObject;
+        try {
+            rawObject = javaDeserialization.parse(this.fixedODR);
+        }
+        catch {
+            return;
+        }
+        const resultObject = {
+            replayVersion: rawObject[0].version,
+            folderName: rawObject[1],
+            fileName: rawObject[2],
+            hash: rawObject[3],
+            cursorMovement: [],
+            hitObjectData: [],
+        };
+        if (resultObject.replayVersion >= 3) {
+            resultObject.time = new Date(Number(rawObject[4].readBigUInt64BE(0)));
+            resultObject.hit300k = rawObject[4].readInt32BE(8);
+            resultObject.hit100k = rawObject[4].readInt32BE(16);
+            resultObject.score = rawObject[4].readInt32BE(32);
+            resultObject.maxCombo = rawObject[4].readInt32BE(36);
+            resultObject.accuracy = new osu_base_1.Accuracy({
+                n300: rawObject[4].readInt32BE(12),
+                n100: rawObject[4].readInt32BE(20),
+                n50: rawObject[4].readInt32BE(24),
+                nmiss: rawObject[4].readInt32BE(28),
+            });
+            resultObject.isFullCombo = !!rawObject[4][44];
+            resultObject.playerName = rawObject[5];
+            resultObject.rawMods = rawObject[6].elements;
+            resultObject.convertedMods = this.convertMods(rawObject[6].elements);
+            // Determine rank
+            const totalHits = resultObject.accuracy.n300 +
+                resultObject.accuracy.n100 +
+                resultObject.accuracy.n50 +
+                resultObject.accuracy.nmiss;
+            const isHidden = resultObject.convertedMods.some((m) => m instanceof osu_base_1.ModHidden || m instanceof osu_base_1.ModFlashlight);
+            const hit300Ratio = resultObject.accuracy.n300 / totalHits;
+            switch (true) {
+                case resultObject.accuracy.value() === 1:
+                    if (isHidden) {
+                        resultObject.rank = "XH";
+                    }
+                    else {
+                        resultObject.rank = "X";
+                    }
+                    break;
+                case hit300Ratio > 0.9 &&
+                    resultObject.accuracy.n50 / totalHits < 0.01 &&
+                    !resultObject.accuracy.nmiss:
+                    if (isHidden) {
+                        resultObject.rank = "SH";
+                    }
+                    else {
+                        resultObject.rank = "S";
+                    }
+                    break;
+                case (hit300Ratio > 0.8 && !resultObject.accuracy.nmiss) ||
+                    hit300Ratio > 0.9:
+                    resultObject.rank = "A";
+                    break;
+                case (hit300Ratio > 0.7 && !resultObject.accuracy.nmiss) ||
+                    hit300Ratio > 0.8:
+                    resultObject.rank = "B";
+                    break;
+                case hit300Ratio > 0.6:
+                    resultObject.rank = "C";
+                    break;
+                default:
+                    resultObject.rank = "D";
+            }
+        }
+        if (resultObject.replayVersion >= 4) {
+            const s = rawObject[7].split("|");
+            resultObject.speedModification =
+                parseFloat(s[0].replace("x", "")) || 1;
+            if (s.length > 1) {
+                resultObject.forcedAR = parseFloat(s[1].replace("AR", ""));
+            }
+        }
+        let bufferIndex;
+        switch (true) {
+            // replay v4 and above
+            case resultObject.replayVersion >= 4:
+                bufferIndex = 8;
+                break;
+            // replay v3
+            case resultObject.replayVersion === 3:
+                bufferIndex = 7;
+                break;
+            // replay v1 and v2
+            default:
+                bufferIndex = 4;
+        }
+        const replayDataBufferArray = [];
+        for (bufferIndex; bufferIndex < rawObject.length; ++bufferIndex) {
+            replayDataBufferArray.push(rawObject[bufferIndex]);
+        }
+        // Merge all cursor movement and hit object data section into one for better control when parsing
+        const replayDataBuffer = Buffer.concat(replayDataBufferArray);
+        let bufferCounter = 0;
+        const size = replayDataBuffer.readInt32BE(bufferCounter);
+        bufferCounter += this.INT_LENGTH;
+        // Parse movement data
+        for (let x = 0; x < size; x++) {
+            const moveSize = replayDataBuffer.readInt32BE(bufferCounter);
+            bufferCounter += this.INT_LENGTH;
+            const moveArray = {
+                size: moveSize,
+                time: [],
+                x: [],
+                y: [],
+                id: [],
+            };
+            for (let i = 0; i < moveSize; i++) {
+                moveArray.time[i] = replayDataBuffer.readInt32BE(bufferCounter);
+                bufferCounter += this.INT_LENGTH;
+                moveArray.id[i] = moveArray.time[i] & 3;
+                moveArray.time[i] >>= 2;
+                if (moveArray.id[i] !== movementType_1.movementType.UP) {
+                    if (resultObject.replayVersion >= 5) {
+                        moveArray.x[i] =
+                            replayDataBuffer.readFloatBE(bufferCounter);
+                        bufferCounter += this.FLOAT_LENGTH;
+                        moveArray.y[i] =
+                            replayDataBuffer.readFloatBE(bufferCounter);
+                        bufferCounter += this.FLOAT_LENGTH;
+                    }
+                    else {
+                        moveArray.x[i] =
+                            replayDataBuffer.readInt16BE(bufferCounter);
+                        bufferCounter += this.SHORT_LENGTH;
+                        moveArray.y[i] =
+                            replayDataBuffer.readInt16BE(bufferCounter);
+                        bufferCounter += this.SHORT_LENGTH;
+                    }
+                }
+                else {
+                    moveArray.x[i] = -1;
+                    moveArray.y[i] = -1;
+                }
+            }
+            resultObject.cursorMovement.push(moveArray);
+        }
+        const replayObjectLength = replayDataBuffer.readInt32BE(bufferCounter);
+        bufferCounter += this.INT_LENGTH;
+        // Parse result data
+        for (let i = 0; i < replayObjectLength; i++) {
+            const replayObjectData = {
+                accuracy: 0,
+                tickset: [],
+                result: 0,
+            };
+            replayObjectData.accuracy =
+                replayDataBuffer.readInt16BE(bufferCounter);
+            bufferCounter += this.SHORT_LENGTH;
+            const len = replayDataBuffer.readInt8(bufferCounter);
+            bufferCounter += this.BYTE_LENGTH;
+            if (len > 0) {
+                const bytes = [];
+                for (let j = 0; j < len; j++) {
+                    bytes.push(replayDataBuffer.readInt8(bufferCounter));
+                    bufferCounter += this.BYTE_LENGTH;
+                }
+                // Int/int division in Java; numbers must be truncated to get actual number
+                for (let j = 0; j < len * 8; j++) {
+                    replayObjectData.tickset[j] =
+                        (bytes[len - Math.trunc(j / 8) - 1] &
+                            (1 << Math.trunc(j % 8))) !==
+                            0;
+                }
+            }
+            if (resultObject.replayVersion >= 1) {
+                replayObjectData.result =
+                    replayDataBuffer.readInt8(bufferCounter);
+                bufferCounter += this.BYTE_LENGTH;
+            }
+            resultObject.hitObjectData.push(replayObjectData);
+        }
+        // Parse max combo, hit results, and accuracy in old replay version
+        if (resultObject.replayVersion < 3 && this.map) {
+            let hit300 = 0;
+            let hit300k = 0;
+            let hit100 = 0;
+            let hit100k = 0;
+            let hit50 = 0;
+            let hit0 = 0;
+            let grantsGekiOrKatu = true;
+            const objects = (this.map instanceof osu_difficulty_calculator_1.DroidStarRating ||
+                this.map instanceof osu_rebalance_difficulty_calculator_1.DroidStarRating
+                ? this.map.map
+                : this.map).objects;
+            for (let i = 0; i < resultObject.hitObjectData.length; ++i) {
+                // Hit result
+                const hitObjectData = resultObject.hitObjectData[i];
+                const isNextNewCombo = i + 1 !== objects.length ? objects[i + 1].isNewCombo : true;
+                switch (hitObjectData.result) {
+                    case hitResult_1.hitResult.RESULT_0:
+                        ++hit0;
+                        grantsGekiOrKatu = false;
+                        break;
+                    case hitResult_1.hitResult.RESULT_50:
+                        ++hit50;
+                        grantsGekiOrKatu = false;
+                        break;
+                    case hitResult_1.hitResult.RESULT_100:
+                        ++hit100;
+                        if (grantsGekiOrKatu && isNextNewCombo) {
+                            ++hit100k;
+                        }
+                        break;
+                    case hitResult_1.hitResult.RESULT_300:
+                        ++hit300;
+                        if (grantsGekiOrKatu && isNextNewCombo) {
+                            ++hit300k;
+                        }
+                        break;
+                }
+                if (isNextNewCombo) {
+                    grantsGekiOrKatu = true;
+                }
+            }
+            resultObject.hit300k = hit300k;
+            resultObject.hit100k = hit100k;
+            resultObject.accuracy = new osu_base_1.Accuracy({
+                n300: hit300,
+                n100: hit100,
+                n50: hit50,
+                nmiss: hit0,
+                nobjects: hit300 + hit100 + hit50 + hit0,
+            });
+            // Determine rank
+            const totalHits = resultObject.accuracy.n300 +
+                resultObject.accuracy.n100 +
+                resultObject.accuracy.n50 +
+                resultObject.accuracy.nmiss;
+            const isHidden = resultObject.convertedMods?.some((m) => m instanceof osu_base_1.ModHidden || m instanceof osu_base_1.ModFlashlight) ?? false;
+            const hit300Ratio = resultObject.accuracy.n300 / totalHits;
+            switch (true) {
+                case resultObject.accuracy.value() === 1:
+                    if (isHidden) {
+                        resultObject.rank = "XH";
+                    }
+                    else {
+                        resultObject.rank = "X";
+                    }
+                    break;
+                case hit300Ratio > 0.9 &&
+                    resultObject.accuracy.n50 / totalHits < 0.01 &&
+                    !resultObject.accuracy.nmiss:
+                    if (isHidden) {
+                        resultObject.rank = "SH";
+                    }
+                    else {
+                        resultObject.rank = "S";
+                    }
+                    break;
+                case (hit300Ratio > 0.8 && !resultObject.accuracy.nmiss) ||
+                    hit300Ratio > 0.9:
+                    resultObject.rank = "A";
+                    break;
+                case (hit300Ratio > 0.7 && !resultObject.accuracy.nmiss) ||
+                    hit300Ratio > 0.8:
+                    resultObject.rank = "B";
+                    break;
+                case hit300Ratio > 0.6:
+                    resultObject.rank = "C";
+                    break;
+                default:
+                    resultObject.rank = "D";
+            }
+        }
+        this.data = new ReplayData_1.ReplayData(resultObject);
+    }
+    /**
+     * Gets hit error information of the replay.
+     *
+     * `analyze()` must be called before calling this.
+     */
+    calculateHitError() {
+        if (!this.data || !this.map) {
+            return null;
+        }
+        const hitObjectData = this.data.hitObjectData;
+        let positiveCount = 0;
+        let negativeCount = 0;
+        let positiveTotal = 0;
+        let negativeTotal = 0;
+        const objects = (this.map instanceof osu_difficulty_calculator_1.DroidStarRating ||
+            this.map instanceof osu_rebalance_difficulty_calculator_1.DroidStarRating
+            ? this.map.map
+            : this.map).objects;
+        for (let i = 0; i < hitObjectData.length; ++i) {
+            const v = hitObjectData[i];
+            const o = objects[i];
+            if (o instanceof osu_base_1.Spinner || v.result === hitResult_1.hitResult.RESULT_0) {
+                continue;
+            }
+            const accuracy = v.accuracy;
+            if (accuracy >= 0) {
+                positiveTotal += accuracy;
+                ++positiveCount;
+            }
+            else {
+                negativeTotal += accuracy;
+                ++negativeCount;
+            }
+        }
+        return {
+            positiveAvg: positiveTotal / positiveCount || 0,
+            negativeAvg: negativeTotal / negativeCount || 0,
+            unstableRate: osu_base_1.MathUtils.calculateStandardDeviation(hitObjectData.map((v, i) => v.result !== hitResult_1.hitResult.RESULT_0 &&
+                !(objects[i] instanceof osu_base_1.Spinner)
+                ? v.accuracy
+                : 0)) * 10,
+        };
+    }
+    /**
+     * Converts replay mods to droid mod string.
+     */
+    convertDroidMods(replayMods) {
+        const replayModsConstants = {
+            MOD_NOFAIL: "n",
+            MOD_EASY: "e",
+            MOD_HIDDEN: "h",
+            MOD_HARDROCK: "r",
+            MOD_DOUBLETIME: "d",
+            MOD_HALFTIME: "t",
+            MOD_NIGHTCORE: "c",
+            MOD_PRECISE: "s",
+            MOD_SMALLCIRCLE: "m",
+            MOD_SPEEDUP: "b",
+            MOD_REALLYEASY: "l",
+            MOD_PERFECT: "f",
+            MOD_SUDDENDEATH: "u",
+            MOD_SCOREV2: "v",
+        };
+        let modString = "";
+        for (const mod of replayMods) {
+            for (const property in replayModsConstants) {
+                if (!(property in replayModsConstants)) {
+                    continue;
+                }
+                if (!mod.includes(property)) {
+                    continue;
+                }
+                modString +=
+                    replayModsConstants[property];
+                break;
+            }
+        }
+        return modString;
+    }
+    /**
+     * Converts replay mods to regular mod string.
+     */
+    convertMods(replayMods) {
+        return osu_base_1.ModUtil.droidStringToMods(this.convertDroidMods(replayMods));
+    }
+    /**
+     * Checks if a play is using 3 fingers.
+     *
+     * Requires `analyze()` to be called first and `map` to be defined as `DroidStarRating` or `RebalanceDroidStarRating`.
+     */
+    checkFor3Finger() {
+        if (!(this.map instanceof osu_difficulty_calculator_1.DroidStarRating ||
+            this.map instanceof osu_rebalance_difficulty_calculator_1.DroidStarRating) ||
+            !this.data) {
+            return;
+        }
+        const threeFingerChecker = new ThreeFingerChecker_1.ThreeFingerChecker(this.map, this.data);
+        const result = threeFingerChecker.check();
+        this.is3Finger = result.is3Finger;
+        this.tapPenalty = result.penalty;
+        this.hasBeenCheckedFor3Finger = true;
+    }
+    /**
+     * Checks if a play is using 2 hands.
+     *
+     * Requires `analyze()` to be called first and `map` to be defined as `DroidStarRating` or `RebalanceDroidStarRating`.
+     */
+    checkFor2Hand() {
+        if (!(this.map instanceof osu_difficulty_calculator_1.DroidStarRating ||
+            this.map instanceof osu_rebalance_difficulty_calculator_1.DroidStarRating) ||
+            !this.data) {
+            return;
+        }
+        const twoHandChecker = new TwoHandChecker_1.TwoHandChecker(this.map, this.data);
+        this.is2Hand = twoHandChecker.check();
+        this.hasBeenCheckedFor2Hand = true;
+    }
+}
+exports.ReplayAnalyzer = ReplayAnalyzer;

package/dist/analysis/BeatmapSectionGenerator.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BeatmapSectionGenerator = void 0;
+/**
+ * A beatmap section generator that generates beatmap section based on aim/speed strain.
+ */
+class BeatmapSectionGenerator {
+    /**
+     * Generates `BeatmapSection`s for the specified beatmap.
+     *
+     * @param map The beatmap to generate.
+     * @param minSectionObjectCount The maximum delta time allowed between two beatmap sections.
+     * Increasing this number decreases the amount of beatmap sections in general. Note that this value does not account for the speed multiplier of
+     * the play, similar to the way replay object data is stored.
+     * @param maxSectionDeltaTime The minimum object count required to make a beatmap section. Increasing this number decreases the amount of beatmap sections.
+     */
+    static generateSections(map, minSectionObjectCount, maxSectionDeltaTime) {
+        const beatmapSections = [];
+        let firstObjectIndex = 0;
+        for (let i = 0; i < map.objects.length - 1; ++i) {
+            const current = map.objects[i];
+            const next = map.objects[i + 1];
+            const realDeltaTime = next.object.startTime - current.object.endTime;
+            if (realDeltaTime >= maxSectionDeltaTime) {
+                // Ignore sections that don't meet object count requirement.
+                if (i - firstObjectIndex < minSectionObjectCount) {
+                    firstObjectIndex = i + 1;
+                    continue;
+                }
+                beatmapSections.push({
+                    firstObjectIndex,
+                    lastObjectIndex: i,
+                });
+                firstObjectIndex = i + 1;
+            }
+        }
+        // Don't forget to manually add the last beatmap section, which would otherwise be ignored.
+        if (map.objects.length - firstObjectIndex > minSectionObjectCount) {
+            beatmapSections.push({
+                firstObjectIndex,
+                lastObjectIndex: map.objects.length - 1,
+            });
+        }
+        return beatmapSections;
+    }
+}
+exports.BeatmapSectionGenerator = BeatmapSectionGenerator;