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

| Property | Type | Description | |-------------------------|--------------------|-----------------------------------------------------| | nbCircles | number | Number of circles in the map | | nbSliders | number | Number of sliders in the map | | nbSpinners | number | Number of spinners in the map | | fileFormat | string | Map file format | | AudioFilename | string | Audio file name | | AudioLeadIn | string | Audio lead-in time | | PreviewTime | string | Preview time | | Countdown | string | Countdown enabled (1) or disabled (0) | | SampleSet | string | Used sample set | | StackLeniency | string | Object stacking leniency | | Mode | string | Game mode (0: osu!, 1: Taiko, 2: Catch the Beat, 3: Mania)| | LetterboxInBreaks | string | Letterboxing in breaks enabled (1) or disabled (0) | | timingPoints | array of objects | Timing points in the map | | breakTimes | array of objects | Break periods in the map | | hitObjects | array of objects | Hittable objects in the map
|

Example object in timingPoints:

| Property | Type | Description | |-----------------------|-----------|-------------------------------------------------------| | offset | number | Temporal offset of the timing point | | beatLength | number | Length of one beat in milliseconds | | velocity | number | Velocity factor | | timingSignature | number | Rhythmic timing signature | | sampleSetId | number | Sample set identifier | | customSampleIndex | number | Custom sample index | | sampleVolume | number | Sample volume | | timingChange | boolean | Timing change indicator | | kiaiTimeActive | boolean | Kiai Time activation indicator | | bpm | number | Beats per minute (BPM) |

Example object in brealTime:

| Property | Type | Description | |-----------------------|-----------|-------------------------------------------------------| | startTime | number | Start of the break period in milliseconds | | endTime | number | End of the break period in milliseconds |

Example object in hitObjects (circle):

| Property | Type | Description | |---------------------|-----------|-------------------------------------------------| | startTime | number | Start time of the object in milliseconds | | newCombo | boolean | New combo indicator | | soundTypes | array | Sound types associated with the object | | position | array | Object position on the screen | | objectName | string | Object name (circle, slider, spinner, etc.) | | additions | object | Additional information |

Example object in hitObjects (slider):

| Property | Type | Description | |---------------------|-----------|----------------------------------------------------------| | startTime | number | Start time of the object in milliseconds | | newCombo | boolean | New combo indicator | | soundTypes | array | Sound types associated with the object | | position | array | Object position on the screen | | objectName | string | Object name (circle, slider, spinner, etc.) | | repeatCount | number | Number of repeats for sliders | | pixelLength | number | Length of the slider in pixels | | additions | object | Additional information | | edges | array of objects | Information about slider edges (sound, additions) | | points | array of arrays | Control points of the slider (x, y coordinates) | | duration | number | Total duration of the slider in milliseconds | | endTime | number | End time of the slider in milliseconds | | curveType | string | Type of slider curve (bezier, linear, catmull) | | endPosition | array | Final position of the slider (x, y coordinates) |

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

| Property | Type | Description | |----------|---------|--------------------------------------------------| | event | string | The type of event ('joined', 'moved', 'left', 'changeMap'). | | player | string | The pseudo (username) associated with the event. | | slot | number | The slot number associated with the event (only for 'joined' and 'moved'). | | mapID | number | The ID of the map associated with the event (only for 'changeMap'). |

Contributing

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