osu-utils v1.0.0

Osu-Utils

Who osu-utils ?

Osu Utils is an open source node js library allowing to have many tools for the creation of project related to osu. It includes simple processes such as calculating accuracy but also parsing a score entirely to extract accurate data.

Installation

1. Install osu utils using npm:

   npm install osu-utils

2. Import osu utils in your javascript project:

   const osu_utils = require('osu-utils');
   const osuUtils = new osu_utils();

Usage

CalcAccuracy Function

The CalcAccuracy function is designed to calculate accuracy for various game modes in the context of rhythm games. It takes several parameters representing the number of hits of different types and additional parameters specific to certain game modes.

Parameters:

• m (Game Mode): An integer representing the game mode. Should be one of the values 0, 1, 2, 3.
• h3, h1, h5, h0 (Hit Counts): The counts of different hit types. For standard modes, h3 represents 300s, h1 represents 100s, h5 represents 50s, and h0 represents misses. For other modes, refer to specific calculations for Taiko, Catch the Beat (CtB), and Mania.
• k (CtB Mode): An optional parameter representing a specific value for CtB mode. Default is 0.
• g (Mania Mode): An optional parameter representing a specific value for Mania mode. Default is 0.

Usage:

try {
    // Example for Standard Mode
    const accuracyStandard = osuUtils.CalcAccuracy(0, 150, 50, 10, 5);

    // Example for Taiko Mode
    const accuracyTaiko = osuUtils.CalcAccuracy(1, 300, 50, 10);

    // Example for Catch the Beat Mode
    const accuracyCtB = osuUtils.CalcAccuracy(2, 100, 30, 5, 0.5);

    // Example for Mania Mode
    const accuracyMania = osuUtils.CalcAccuracy(3, 800, 150, 20, 10, 0.5, 2);

    console.log(accuracyStandard, accuracyTaiko, accuracyCtB, accuracyMania);
} catch (error) {
    console.error(error.message);
}

Rank Function

The Rank function is designed to determine the rank based on the provided parameters such as hit counts, accuracy, and specific parameters for certain game modes.

Parameters:

• m (Game Mode): An integer representing the game mode. Should be one of the values 0, 1, 2, 3.
• h3, h1, h5, h0 (Hit Counts): The counts of different hit types. For standard modes, h3 represents 300s, h1 represents 100s, h5 represents 50s, and h0 represents misses.
• mds (Mod Strings): An optional parameter representing mod strings specific to the beatmap. Default is null.
• pAcc (Player Accuracy): A floating-point number representing the player's accuracy.

Usage:

try {
    // Example for Standard Mode
    const rankStandard = osuUtils.Rank(0, 150, 50, 10, 5, "HDHR", 98.5);

    // Example for Taiko Mode
    const rankTaiko = osuUtils.Rank(1, 300, 50, 10, null, 96.2);

    // Example for Catch the Beat Mode
    const rankCtB = osuUtils.Rank(2, 100, 30, 5, "NF", 92.0);

    // Example for Mania Mode
    const rankMania = osuUtils.Rank(3, 800, 150, 20, 10, "EZHT", 99.8);

    console.log(rankStandard, rankTaiko, rankCtB, rankMania);
} catch (error) {
    console.error(error.message);
}

TimeStampToMs Function

The TimeStampToMs function is a simple wrapper function that converts a timestamp in milliseconds using another function called tsMs.

Parameters:

• ms (Timestamp in Milliseconds): An integer representing a timestamp in milliseconds.

Usage:

// Example
const timestamp = 1642310400000; // January 17, 2022, 00:00:00 UTC
const convertedTime = osuUtils.TimeStampToMs(timestamp);

console.log(convertedTime);

ModsIntToString Function

The ModsIntToString function is designed to convert a numeric representation of mods into a space-separated string of mod names. It utilizes a predefined Mods object to map numeric values to mod names.

Parameters:

• int (Numeric Representation of Mods): An integer representing the numeric value of mods.

Usage:

// Example
const modsValue = 34; // Numeric representation of mods
const modNamesString = osuUtils.ModsIntToString(modsValue);

console.log(modNamesString);

ModeStringToInt Function

The ModeStringToInt function is designed to convert a mode string into its corresponding numeric representation using a predefined Modes object.

Parameters:

• modeString (Mode String): A string representing the mode ('osu', 'taiko', 'ctb', 'mania').

Usage:

// Example
const modeString = 'osu'; // Mode string
const modeNumeric = osuUtils.ModeStringToInt(modeString);

console.log(modeNumeric);

ParseMapFile Function

The ParseMapFile function is designed to parse a map file and invoke a callback with the parsed information. It utilizes the parseBm module for parsing the beatmap data.

Parameters:

• file (File Path): A string representing the path to the map file.
• callback (Callback Function): A callback function that will be invoked with the parsed information or an error. It has the signature (error: Error | null, parsedData?: any) => void.

Usage:

// Example
const filePath = '/path/to/beatmap.osu'; // Replace with the actual file path
osuUtils.ParseMapFile(filePath, function (error, parsedData) {
    if (error) {
        console.error(error.message);
    } else {
        console.log(parsedData);
    }
});

|

Example object in timingPoints:

Example object in brealTime:

Example object in hitObjects (circle):

Example object in hitObjects (slider):

BanchoMessage Function

The BanchoMessage function is designed to parse a Bancho message and extract relevant information based on the message content and associated username.

Parameters:

• objectMessage (Bancho Message Object):
  • objectMessage.content (string): The content of the Bancho message.
  • objectMessage.pseudo (string): The username (pseudo) associated with the message.

Usage:

// Example
const banchoMessage = {
    content: "joined room Slot1",
    pseudo: "BanchoBot"
};

const parsedInfo = osuUtils.BanchoMessage(banchoMessage);

if (parsedInfo) {
    console.log(parsedInfo);
} else {
    console.log("Invalid Bancho message");
}

Contributing

Contributions are welcome! If you find any issues or want to add new features, feel free to submit a pull request.