@rian8337/osu-base 2.0.0-alpha.25 → 2.0.0-alpha.31

package/README.md

@@ -4,11 +4,33 @@ The base module required for all my osu! modules.
 
 # Features
 
-This module provides the required feature for all my osu! related modules, which is the beatmap parser.
+This module serves as the foundation of all my osu! modules. It provides multiple features such as:
+
+-   Accuracy calculator and estimator
+    -   Calculate an accuracy value from hit values or estimate hit values from an accuracy value.
+-   API request builders
+    -   Supports osu!droid API and osu! API v1.
+-   Beatmap decoder
+    -   Fully decodes an `.osu` file into a `Beatmap` object that is easier to work with.
+-   Beatmap encoder
+    -   Will encode a beatmap into an `.osu` file with format version 14.
+-   Hit window converters
+    -   Convert an OD value to its hit window values and vice versa.
+-   Map statistics calculator
+    -   Calculate a given map statistics (CS, AR, OD, and HP) with modifications applied (mods, custom speed multiplier, etc).
+-   Mod conversion utilities
+    -   Convert a mod combination string in osu!droid (i.e. `hr`) and osu!standard (i.e. `HDHR`) into an array of mods.
+    -   Available mods can be looked at the documentation.
+-   Storyboard decoder
+    -   Supports `.osb` and `.osu` files.
+-   Storyboard encoder
+    -   Storyboard will be encoded into a format that is supported by `.osu` files (that is, all variable instances will be replaced).
 
 # Specific Requirements
 
-If you want to retrieve a beatmap using osu! API, you need to have an osu! API key set as `OSU_API_KEY` environment variable.
+If you want to use the osu!droid API, you need to have an osu!droid API key set as `DROID_API_KEY` environment variable.
+
+If you want to use the osu! API, you need to have an osu! API key set as `OSU_API_KEY` environment variable.
 
 See usage for more details.
 
@@ -26,7 +48,82 @@ yarn add @rian8337/osu-base
 
 # Usage
 
-## Using osu! API
+## Accuracy Calculator and Estimator
+
+### Calculate Accuracy Value (0-1) from Hit Values
+
+```js
+import { Accuracy } from "@rian8337/osu-base";
+
+// If you specified the amount of great hits (`n300`).
+let accuracyValue = new Accuracy({
+    n300: 1000,
+    n100: 125,
+    n50: 10,
+    nmiss: 5,
+}).value();
+
+console.log(accuracyValue);
+
+// If you didn't specify the amount of great hits (`n300`).
+const objectCount = 2000;
+
+accuracyValue = new Accuracy({
+    n100: 125,
+    n50: 10,
+    nmiss: 5,
+}).value(objectCount);
+```
+
+### Hit Values Estimation
+
+The way this estimation works is that the estimator will see if the accuracy can be estimated by just using good hit values. Otherwise, the estimator will use meh hit values.
+
+Keep in mind that it will not use the miss hit value.
+
+```js
+import { Accuracy } from "@rian8337/osu-base";
+
+const accuracy = new Accuracy({
+    percent: 99.7,
+    nobjects: 2000,
+});
+
+console.log(accuracy.n300);
+console.log(accuracy.n100);
+console.log(accuracy.n50);
+```
+
+## API Request Builders
+
+```js
+import {
+    DroidAPIRequestBuilder,
+    OsuAPIRequestBuilder,
+} from "@rian8337/osu-base";
+
+const droidBuilder = new DroidAPIRequestBuilder()
+    .setEndpoint("getuserinfo.php")
+    .addParameter("uid", 51076);
+
+const droidResult = await droidBuilder.sendRequest();
+
+console.log(droidResult);
+
+const osuBuilder = new OsuAPIRequestBuilder()
+    .setEndpoint("get_beatmaps")
+    .addParamter("b", 901854);
+
+const osuResult = await osuBuilder.sendRequest();
+
+console.log(osuResult);
+```
+
+## Beatmap Decoder
+
+There are two primary ways of using the beatmap decoder.
+
+### Using osu! API
 
 ```js
 import { MapInfo } from "@rian8337/osu-base";
@@ -47,22 +144,173 @@ if (!beatmapInfo.title) {
 console.log(beatmapInfo.map);
 ```
 
-### Not retrieving beatmap file
+#### Not retrieving beatmap file
 
-You can also opt out from downloading the beatmap (`.osu`) file if you just want to retrieve information from the API by setting `file` to `false`, however a parsed beatmap will not be provided.
+You can also opt out from downloading the beatmap (`.osu`) file if you just want to retrieve information from the API by setting `file` to `false`, however a decoded beatmap will not be provided.
 
-## Using without osu! API
+### Not using osu! API
 
 ```js
 import { readFile } from "fs";
-import { Parser } from "@rian8337/osu-base";
+import { BeatmapDecoder } from "@rian8337/osu-base";
 
 readFile("path/to/file.osu", { encoding: "utf-8" }, (err, data) => {
     if (err) throw err;
 
-    const parser = new Parser().parse(data);
+    const decoder = new BeatmapDecoder().decode(data);
 
-    // Parsed beatmap can be accessed via the `map` field
-    console.log(parser.map);
+    // Decoded beatmap can be accessed via the `result` field
+    console.log(decoder.result);
 });
 ```
+
+## Beatmap Encoder
+
+```js
+import { Beatmap, BeatmapEncoder } from "@rian8337/osu-base";
+
+const beatmap = new Beatmap();
+
+const encoder = new BeatmapEncoder(beatmap).encode();
+
+// Encoded beatmap can be accessed via the `result` field
+console.log(encoder.result);
+```
+
+## Hit Window Converters
+
+### OD to Hit Window
+
+```js
+import { DroidHitWindow, OsuHitWindow } from "@rian8337/osu-base";
+
+// Convert OD to osu!droid hit window
+const droidWindow = new DroidHitWindow(10);
+
+console.log(droidHitWindow.hitWindowFor300());
+console.log(droidHitWindow.hitWindowFor100());
+console.log(droidHitWindow.hitWindowFor50());
+
+// Calculating for the Precise mod in mind is also possible
+console.log(droidHitWindow.hitWindowFor300(true));
+console.log(droidHitWindow.hitWindowFor100(true));
+console.log(droidHitWindow.hitWindowFor50(true));
+
+// Convert OD to osu!standard hit window
+const osuWindow = new OsuHitWindow(10);
+
+console.log(osuWindow.hitWindowFor300());
+console.log(osuWindow.hitWindowFor100());
+console.log(osuWindow.hitWindowFor50());
+```
+
+### Hit Window to OD
+
+```js
+import { DroidHitWindow, OsuHitWindow } from "@rian8337/osu-base";
+
+// Convert hit window to osu!droid OD
+console.log(DroidHitWindow.hitWindow300ToOD(50));
+console.log(DroidHitWindow.hitWindow100ToOD(100));
+console.log(DroidHitWindow.hitWindow50ToOD(200));
+
+// Calculating for the Precise mod in mind is also possible
+console.log(DroidHitWindow.hitWindow300ToOD(25, true));
+console.log(DroidHitWindow.hitWindow100ToOD(80, true));
+console.log(DroidHitWindow.hitWindow50ToOD(130, true));
+
+// Convert hit window to osu!standard OD
+console.log(OsuHitWindow.hitWindow300ToOD(20));
+console.log(OsuHitWindow.hitWindow100ToOD(60));
+console.log(OsuHitWindow.hitWindow50ToOD(100));
+```
+
+## Map Statistics Calculator
+
+The map statistics calculator can only be used once per instance.
+
+### General Usage
+
+```js
+import { MapStats } from "@rian8337/osu-base";
+
+const stats = new MapStats({
+    cs: 4,
+    ar: 9,
+    od: 8,
+    hp: 6,
+}).calculate();
+
+console.log(stats);
+```
+
+Every value is optional.
+
+### Available Options
+
+You can specify more options to alter the final result of the calculation:
+
+-   Mods
+-   Custom speed multiplier
+-   Force AR (whether to keep the AR at its original value)
+-   Game mode (switch between osu!droid and osu!standard, defaults to osu!standard)
+
+```js
+import { MapStats, ModUtil, modes } from "@rian8337/osu-base";
+
+const stats = new MapStats({
+    cs: 4,
+    ar: 9,
+    od: 8,
+    hp: 6,
+    mods: ModUtil.pcStringToMods("HDHR"),
+    speedMultiplier: 1.25,
+    isForceAR: true,
+}).calculate({ mode: modes.osu });
+
+console.log(stats);
+```
+
+## Mod Conversion Utilities
+
+```js
+import { ModUtil } from "@rian8337/osu-base";
+
+// Convert droid mod string into an array of mods
+console.log(ModUtil.droidStringToMods("hr"));
+
+// Convert PC modbits into an array of mods
+console.log(ModUtil.pcModbitsToMods(12));
+
+// Convert PC mod string into an array mods
+console.log(ModUtil.pcStringToMods("HDHR"));
+```
+
+## Storyboard Decoder
+
+```js
+import { readFile } from "fs";
+import { StoryboardDecoder } from "@rian8337/osu-base";
+
+readFile("path/to/file.osb", { encoding: "utf-8" }, (err, data) => {
+    if (err) throw err;
+
+    const decoder = new StoryboardDecoder().decode(data);
+
+    // Decoded storyboard can be accessed via the `result` field
+    console.log(decoder.result);
+});
+```
+
+## Storyboard Encoder
+
+```js
+import { Storyboard, StoryboardEncoder } from "@rian8337/osu-base";
+
+const storyboard = new Storyboard();
+
+const encoder = new StoryboardEncoder(storyboard).encode();
+
+// Encoded storyboard can be accessed via the `result` field
+console.log(encoder.result);
+```

package/dist/index.js

@@ -815,9 +815,7 @@ class Slider extends HitObject {
             startTime: finalSpanEndTime,
         });
         this.nestedHitObjects.push(this.tail);
-        this.nestedHitObjects.sort((a, b) => {
-            return a.startTime - b.startTime;
-        });
+        this.nestedHitObjects.sort((a, b) => a.startTime - b.startTime);
     }
     toString() {
         return `Position: [${this.position.x}, ${this.position.y}], distance: ${this.path.expectedDistance}, repetitions: ${this.repetitions}, slider ticks: ${this.nestedHitObjects.filter((v) => v instanceof SliderTick).length}`;
@@ -1872,6 +1870,51 @@ class HitWindow {
  * Represents the hit window of osu!droid.
  */
 class DroidHitWindow extends HitWindow {
+    /**
+     * Calculates the overall difficulty value of a great hit window.
+     *
+     * @param value The value of the hit window, in milliseconds.
+     * @param isPrecise Whether to calculate for Precise mod.
+     * @returns The overall difficulty value.
+     */
+    static hitWindow300ToOD(value, isPrecise) {
+        if (isPrecise) {
+            return 5 - (value - 55) / 6;
+        }
+        else {
+            return 5 - (value - 75) / 5;
+        }
+    }
+    /**
+     * Calculates the overall difficulty value of a good hit window.
+     *
+     * @param value The value of the hit window, in milliseconds.
+     * @param isPrecise Whether to calculate for Precise mod.
+     * @returns The overall difficulty value.
+     */
+    static hitWindow100ToOD(value, isPrecise) {
+        if (isPrecise) {
+            return 5 - (value - 120) / 8;
+        }
+        else {
+            return 5 - (value - 150) / 10;
+        }
+    }
+    /**
+     * Calculates the overall difficulty value of a meh hit window.
+     *
+     * @param value The value of the hit window, in milliseconds.
+     * @param isPrecise Whether to calculate for Precise mod.
+     * @returns The overall difficulty value.
+     */
+    static hitWindow50ToOD(value, isPrecise) {
+        if (isPrecise) {
+            return 5 - (value - 180) / 10;
+        }
+        else {
+            return 5 - (value - 250) / 10;
+        }
+    }
     hitWindowFor300(isPrecise) {
         if (isPrecise) {
             return 55 + 6 * (5 - this.overallDifficulty);
@@ -1901,6 +1944,33 @@ class DroidHitWindow extends HitWindow {
  * Represents the hit window of osu!standard.
  */
 class OsuHitWindow extends HitWindow {
+    /**
+     * Calculates the overall difficulty value of a great hit window.
+     *
+     * @param value The value of the hit window, in milliseconds.
+     * @returns The overall difficulty value.
+     */
+    static hitWindow300ToOD(value) {
+        return (80 - value) / 6;
+    }
+    /**
+     * Calculates the overall difficulty value of a good hit window.
+     *
+     * @param value The value of the hit window, in milliseconds.
+     * @returns The overall difficulty value.
+     */
+    static hitWindow100ToOD(value) {
+        return (140 - value) / 8;
+    }
+    /**
+     * Calculates the overall difficulty value of a meh hit window.
+     *
+     * @param value The value of the hit window, in milliseconds.
+     * @returns The overall difficulty value.
+     */
+    static hitWindow50ToOD(value) {
+        return (200 - value) / 10;
+    }
     hitWindowFor300() {
         return 80 - 6 * this.overallDifficulty;
     }
@@ -2076,6 +2146,8 @@ class ModFlashlight extends Mod {
  * Represents the Hidden mod.
  */
 class ModHidden extends Mod {
+    static fadeInDurationMultiplier = 0.4;
+    static fadeOutDurationMultiplier = 0.3;
     scoreMultiplier = 1.06;
     acronym = "HD";
     name = "Hidden";
@@ -2234,9 +2306,7 @@ class ModUtil {
      * Mods that change the way the map looks.
      */
     static mapChangingMods = [
-        new ModDoubleTime(),
-        new ModNightCore(),
-        new ModHalfTime(),
+        ...this.speedChangingMods,
         new ModEasy(),
         new ModHardRock(),
         new ModSmallCircle(),
@@ -2394,29 +2464,31 @@ class MapStats {
         }
         switch (params?.mode ?? exports.modes.osu) {
             case exports.modes.droid:
-                // In droid pre-1.6.8, NC speed multiplier is assumed bugged (1.39)
+                // In droid pre-1.6.8, NC speed multiplier is assumed bugged (1.39).
                 if (this.mods.some((m) => m instanceof ModNightCore) &&
                     this.oldStatistics) {
                     this.speedMultiplier *= 1.39 / 1.5;
                 }
                 // CS and OD work differently in droid, therefore it
                 // needs to be computed regardless of map-changing mods
-                // and statistics multiplier
+                // and statistics multiplier.
                 if (this.od !== undefined) {
-                    // apply EZ or HR to OD
+                    // Apply EZ or HR to OD.
                     this.od = Math.min(this.od * statisticsMultiplier, 10);
-                    // convert original OD to droid OD
+                    // Convert original OD to droid hit window to take
+                    // droid hit window and the PR mod in mind.
                     const droidToMS = new DroidHitWindow(this.od).hitWindowFor300(this.mods.some((m) => m instanceof ModPrecise)) / this.speedMultiplier;
-                    this.od = 5 - (droidToMS - 50) / 6;
+                    // Convert droid hit window back to original OD.
+                    this.od = OsuHitWindow.hitWindow300ToOD(droidToMS);
                 }
                 // HR and EZ works differently in droid in terms of
-                // CS modification (even CS in itself as well)
+                // CS modification (even CS in itself as well).
                 //
                 // If present mods are found, they need to be removed
                 // from the bitwise enum of mods to prevent double
-                // calculation
+                // calculation.
                 if (this.cs !== undefined) {
-                    // Assume 681 is height
+                    // Assume 681 is height.
                     const assumedHeight = 681;
                     let scale = ((assumedHeight / 480) * (54.42 - this.cs * 4.48) * 2) /
                         128 +
@@ -5226,6 +5298,15 @@ class Encoder {
      * The result of the encoding process.
      */
     finalResult = "";
+    /**
+     * The result of the encoding process.
+     */
+    get result() {
+        return this.finalResult;
+    }
+    /**
+     * @param target The target of the encoding process.
+     */
     constructor(target) {
         this.target = target;
     }
@@ -5237,7 +5318,7 @@ class Encoder {
     encode() {
         this.reset();
         this.encodeInternal();
-        return this.finalResult;
+        return this;
     }
     /**
      * Writes a line to encoded text.
@@ -5715,7 +5796,7 @@ class BeatmapEventsEncoder extends BeatmapBaseEncoder {
             this.writeLine(`2,${b.startTime},${b.endTime}`);
         }
         if (this.map.events.storyboard) {
-            this.writeLine(new StoryboardEncoder(this.map.events.storyboard, false).encode());
+            this.writeLine(new StoryboardEncoder(this.map.events.storyboard, false).encode().result);
         }
         else {
             this.writeLine("//Storyboard Layer 0 (Background)");
@@ -6314,9 +6395,9 @@ class MapInfo {
      * - Option `0`: return map title and mods used if defined
      * - Option `1`: return song source and map download link to beatmap mirrors
      * - Option `2`: return circle, slider, and spinner count
-     * - Option `3`: return CS, AR, OD, and HP statistics for droid
-     * - Option `4`: return CS, AR, OD, and HP statistics for PC
-     * - Option `5`: return BPM, map length, max combo, and max score
+     * - Option `3`: return CS, AR, OD, HP, and max score statistics for droid
+     * - Option `4`: return CS, AR, OD, HP, and max score statistics for PC
+     * - Option `5`: return BPM, map length, and max combo
      * - Option `6`: return last update date and map status
      * - Option `7`: return favorite count and play count
      *
@@ -6404,6 +6485,7 @@ class MapInfo {
                 droidModifiedStats.ar = MathUtils.round(droidModifiedStats.ar, 2);
                 droidModifiedStats.od = MathUtils.round(droidModifiedStats.od, 2);
                 droidModifiedStats.hp = MathUtils.round(droidModifiedStats.hp, 2);
+                const maxScore = this.map?.maxDroidScore(new MapStats(mapParams)) ?? 0;
                 return `**CS**: ${droidOriginalStats.cs}${Precision.almostEqualsNumber(droidOriginalStats.cs, droidModifiedStats.cs)
                     ? ""
                     : ` (${droidModifiedStats.cs})`} - **AR**: ${droidOriginalStats.ar}${Precision.almostEqualsNumber(droidOriginalStats.ar, droidModifiedStats.ar)
@@ -6412,7 +6494,9 @@ class MapInfo {
                     ? ""
                     : ` (${droidModifiedStats.od})`} - **HP**: ${droidOriginalStats.hp}${Precision.almostEqualsNumber(droidOriginalStats.hp, droidModifiedStats.hp)
                     ? ""
-                    : ` (${droidModifiedStats.hp})`}`;
+                    : ` (${droidModifiedStats.hp})`}${maxScore > 0
+                    ? `\n**Max Score**: ${maxScore.toLocaleString()}`
+                    : ""}`;
             }
             case 4: {
                 const mapStatistics = new MapStats(mapParams).calculate();
@@ -6420,6 +6504,7 @@ class MapInfo {
                 mapStatistics.ar = MathUtils.round(mapStatistics.ar, 2);
                 mapStatistics.od = MathUtils.round(mapStatistics.od, 2);
                 mapStatistics.hp = MathUtils.round(mapStatistics.hp, 2);
+                const maxScore = this.map?.maxOsuScore(mapStatistics.mods) ?? 0;
                 return `**CS**: ${this.cs}${Precision.almostEqualsNumber(this.cs, mapStatistics.cs)
                     ? ""
                     : ` (${mapStatistics.cs})`} - **AR**: ${this.ar}${Precision.almostEqualsNumber(this.ar, mapStatistics.ar)
@@ -6428,12 +6513,12 @@ class MapInfo {
                     ? ""
                     : ` (${mapStatistics.od})`} - **HP**: ${this.hp}${Precision.almostEqualsNumber(this.hp, mapStatistics.hp)
                     ? ""
-                    : ` (${mapStatistics.hp})`}`;
+                    : ` (${mapStatistics.hp})`}${maxScore > 0
+                    ? `\n**Max Score**: ${maxScore.toLocaleString()}`
+                    : ""}`;
             }
             case 5: {
                 const mapStatistics = new MapStats(mapParams).calculate();
-                const droidMaxScore = this.map?.maxDroidScore(mapStatistics) ?? 0;
-                const osuMaxScore = this.map?.maxOsuScore(mapStatistics.mods) ?? 0;
                 const convertedBPM = this.convertBPM(mapStatistics);
                 let string = "**BPM**: ";
                 if (this.map) {
@@ -6441,12 +6526,7 @@ class MapInfo {
                     if (uninheritedTimingPoints.length === 1) {
                         string += `${this.bpm}${!Precision.almostEqualsNumber(this.bpm, convertedBPM)
                             ? ` (${convertedBPM})`
-                            : ""} - **Length**: ${this.convertTime(mapStatistics)} - **Max Combo**: ${this.maxCombo}x${droidMaxScore > 0
-                            ? `\n**Max Droid Score**: ${droidMaxScore.toLocaleString()}`
-                            : ""}${osuMaxScore > 0
-                            ? (droidMaxScore > 0 ? " - " : "\n") +
-                                `**Max Standard Score**: ${osuMaxScore.toLocaleString()}`
-                            : ""}`;
+                            : ""} - **Length**: ${this.convertTime(mapStatistics)} - **Max Combo**: ${this.maxCombo}x`;
                     }
                     else {
                         let maxBPM = this.bpm;
@@ -6473,25 +6553,13 @@ class MapInfo {
                                 string += `(${convertedBPM}) `;
                             }
                         }
-                        string += `- **Length**: ${this.convertTime(mapStatistics)} - **Max Combo**: ${this.maxCombo}x${droidMaxScore > 0
-                            ? `\n**Max Droid Score**: ${droidMaxScore.toLocaleString()}`
-                            : ""}${osuMaxScore > 0
-                            ? (droidMaxScore > 0 ? " - " : "\n") +
-                                `**Max Standard Score**: ${osuMaxScore.toLocaleString()}`
-                            : ""}`;
+                        string += `- **Length**: ${this.convertTime(mapStatistics)} - **Max Combo**: ${this.maxCombo}x`;
                     }
                 }
                 else {
                     string += `${this.bpm}${!Precision.almostEqualsNumber(this.bpm, convertedBPM)
                         ? ` (${convertedBPM})`
-                        : ""} - **Length**: ${this.convertTime(mapStatistics)} - **Max Combo**: ${this.maxCombo}x${droidMaxScore > 0
-                        ? `${droidMaxScore > 0
-                            ? `\n**Max Droid Score**: ${droidMaxScore.toLocaleString()}`
-                            : ""}${osuMaxScore > 0
-                            ? (droidMaxScore > 0 ? " - " : "\n") +
-                                `**Max Standard Score**: ${osuMaxScore.toLocaleString()}`
-                            : ""}`
-                        : ""}`;
+                        : ""} - **Length**: ${this.convertTime(mapStatistics)} - **Max Combo**: ${this.maxCombo}x`;
                 }
                 return string;
             }