@rian8337/osu-base v3.3.0

About

The base module required for all my osu! modules.

Features

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 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.

Installation

npm i @rian8337/osu-base

or

yarn add @rian8337/osu-base

Usage

Accuracy Calculator and Estimator

Calculate Accuracy Value (0-1) from Hit Values

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.

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

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

import { MapInfo } from "@rian8337/osu-base";

// MD5 hash is also supported in the first parameter
const beatmapInfo = await MapInfo.getInformation(901854);

if (!beatmapInfo.title) {
    return console.log("Beatmap not found");
}

// Decoded beatmap can be accessed via the `map` field
console.log(beatmapInfo.map);

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 decoded beatmap will not be provided.

Not using osu! API

import { readFile } from "fs";
import { BeatmapDecoder } from "@rian8337/osu-base";

readFile("path/to/file.osu", { encoding: "utf-8" }, (err, data) => {
    if (err) throw err;

    const decoder = new BeatmapDecoder().decode(data);

    // Decoded beatmap can be accessed via the `result` field
    console.log(decoder.result);
});

Beatmap Encoder

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

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

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

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)

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

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

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

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);