@rian8337/osu-droid-replay-analyzer 1.0.0 → 1.0.4

package/README.md

@@ -1,11 +1,161 @@
-# `osu-droid-replay-analyzer`
+# About
 
-> TODO: description
+A replay analyzer for osu!droid.
 
-## Usage
+# Features
 
+This module allows parsing osu!droid replay files (`.odr`) to get replay information.
+
+Additionally, it provides a detection system to detect whether the player used three fingers or more to stream or two hands to jump.
+
+Two hand detection is still a WIP.
+
+# Specific Requirements
+
+This module has no specific requirements, however installed modules in installation may have specific requirements. It's advised to check them.
+
+# Installation
+
+```
+npm i @rian8337/osu-base @rian8337/osu-droid-replay-analyzer
+```
+
+or
+
+```
+yarn add @rian8337/osu-base @rian8337/osu-droid-replay-analyzer
+```
+
+# Usage
+
+To use the replay analyzer, you need a replay file (`.odr`).
+
+## Obtaining a replay file
+
+There are multiple ways to get one.
+
+### Obtaining a replay file with a score ID
+
+If you know a score's ID, you can use it to directly retrieve a replay:
+
+```js
+import { MapInfo } from "@rian8337/osu-base";
+import { ReplayAnalyzer } from "@rian8337/osu-droid-replay-analyzer";
+
+// Obtaining a beatmap file is optional, however it allows the replay analyzer to output more data
+// for old replays (replay version 1 or 2)
+const beatmapInfo = await MapInfo.getInformation({ beatmapID: 901854 });
+
+if (!beatmapInfo.title) {
+    return console.log("Beatmap not found");
+}
+
+// A `ReplayAnalyzer` instance that contains the replay
+const replay = await new ReplayAnalyzer({
+    scoreID: 12948732,
+    map: beatmapInfo.map,
+}).analyze();
+
+// The data of the replay
+const { data } = replay;
+
+if (!data) {
+    return console.log("Replay not found");
+}
+
+console.log(data);
 ```
-const osuDroidReplayAnalyzer = require('osu-droid-replay-analyzer');
 
-// TODO: DEMONSTRATE API
+### Obtaining a local replay file
+
+```js
+import { readFile } from "fs";
+import { MapInfo } from "@rian8337/osu-base";
+import { ReplayAnalyzer } from "@rian8337/osu-droid-replay-analyzer";
+
+readFile("path/to/file.odr", async (err, replayData) => {
+    if (err) throw err;
+
+    // Obtaining a beatmap file is optional, however it allows the replay analyzer to output more data
+    // for old replays (replay version 1 or 2)
+    const beatmapInfo = await MapInfo.getInformation({ beatmapID: 901854 });
+
+    if (!beatmapInfo.title) {
+        return console.log("Beatmap not found");
+    }
+
+    // A `ReplayAnalyzer` instance that contains the replay
+    const replay = new ReplayAnalyzer({ scoreID: 0, map: beatmapInfo.map });
+
+    replay.originalODR = replayData;
+
+    await replay.analyze();
+
+    // The data of the replay
+    const { data } = replay;
+
+    console.log(data);
+});
+```
+
+## Playstyle detections
+
+To use this, you need to have a calculated instance of a beatmap from `@rian8337/osu-difficulty-calculator` or `@rian8337/osu-rebalance-difficulty-calculator`:
+
+```
+npm i @rian8337/osu-difficulty-calculator @rian8337/osu-rebalance-difficulty-calculator
+```
+
+or
+
+```
+yarn add @rian8337/osu-difficulty-calculator @rian8337/osu-rebalance-difficulty-calculator
+```
+
+You can exclude a difficulty module that you don't plan to use.
+
+```js
+import { MapInfo, MapStats } from "@rian8337/osu-base";
+import { DroidStarRating } from "@rian8337/osu-difficulty-calculator";
+import { ReplayAnalyzer } from "@rian8337/osu-droid-replay-analyzer";
+
+const beatmapInfo = await MapInfo.getInformation({ beatmapID: 901854 });
+
+if (!beatmapInfo.title) {
+    return console.log("Beatmap not found");
+}
+
+// A `ReplayAnalyzer` instance that contains the replay
+const replay = await new ReplayAnalyzer({
+    scoreID: 12948732,
+    map: beatmapInfo.map,
+}).analyze();
+
+// The data of the replay
+const { data } = replay;
+
+if (!data) {
+    return console.log("Replay not found");
+}
+
+const stats = new MapStats({
+    ar: data.forcedAR,
+    speedMultiplier: data.speedModification,
+    isForceAR: !isNaN(data.forcedAR),
+    // In osu!droid version 1.6.7 and below, there exists a bug where NC is slower than DT in a few beatmaps
+    // This option checks for said condition
+    oldStatistics: data.replayVersion <= 3,
+});
+
+replay.map = new DroidStarRating().calculate({
+    map: beatmapInfo.map,
+    mods: data.convertedMods,
+    stats: stats,
+});
+
+// Check for three-finger usage
+replay.checkFor3Finger();
+
+// Check for two-hand usage
+replay.checkFor2Hand();
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rian8337/osu-droid-replay-analyzer",
-  "version": "1.0.0",
+  "version": "1.0.4",
   "description": "A replay analyzer for analyzing osu!droid replay files.",
   "keywords": [
     "osu",
@@ -22,6 +22,8 @@
   },
   "scripts": {
     "build": "tsc",
+    "generate-docs": "typedoc src/index.ts",
+    "lint": "eslint --ext ts",
     "prepare": "dts-gen -m java-deserialization -o -f ./node_modules/java-deserialization/src/index.d.ts && npm run build",
     "test": "echo \"No tests for this module\""
   },
@@ -29,9 +31,9 @@
     "url": "https://github.com/Rian8337/osu-droid-module/issues"
   },
   "dependencies": {
-    "@rian8337/osu-base": "^1.0.0",
-    "@rian8337/osu-difficulty-calculator": "^1.0.0",
-    "@rian8337/osu-rebalance-difficulty-calculator": "^1.0.0",
+    "@rian8337/osu-base": "^1.0.4",
+    "@rian8337/osu-difficulty-calculator": "^1.0.4",
+    "@rian8337/osu-rebalance-difficulty-calculator": "^1.0.4",
     "java-deserialization": "^0.1.0",
     "unzipper": "^0.10.11"
   },
@@ -43,5 +45,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "e4fdb9c1ed6f90e70651c1aedfdb964b61cb240d"
+  "gitHead": "31e88dedb78e6b1e0123b67bcc5d4dd31f5dfc60"
 }

package/typings/index.d.ts

@@ -205,6 +205,28 @@ declare module "@rian8337/osu-droid-replay-analyzer" {
         });
     }
 
+    /**
+     * Utility to check whether or not a beatmap is three-fingered.
+     */
+    export class ThreeFingerChecker {
+        /**
+         * The beatmap to analyze.
+         */
+        readonly map: DroidStarRating | RebalanceDroidStarRating;
+        /**
+         * The data of the replay.
+         */
+        readonly data: ReplayData;
+        /**
+         * Checks whether a beatmap is eligible to be detected for three finger.
+         *
+         * @param map The beatmap.
+         */
+        static isEligibleToDetect(
+            map: DroidStarRating | RebalanceDroidStarRating
+        ): boolean;
+    }
+
     //#endregion
 
     //#region Enums
@@ -296,7 +318,6 @@ declare module "@rian8337/osu-droid-replay-analyzer" {
         readonly unstableRate: number;
     }
 
-
     /**
      * Contains information about a replay.
      */