@rian8337/osu-base 1.0.0

package/dist/utils/PathApproximator.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PathApproximator = void 0;
+const Vector2_1 = require("../mathutil/Vector2");
+const Precision_1 = require("./Precision");
+const Utils_1 = require("./Utils");
+/**
+ * Path approximator for sliders.
+ */
+class PathApproximator {
+    /**
+     * Approximates a bezier slider's path.
+     *
+     * Creates a piecewise-linear approximation of a bezier curve by adaptively repeatedly subdividing
+     * the control points until their approximation error vanishes below a given threshold.
+     *
+     * @param controlPoints The anchor points of the slider.
+     */
+    static approximateBezier(controlPoints) {
+        const output = [];
+        const count = controlPoints.length - 1;
+        if (count < 0) {
+            return output;
+        }
+        const subdivisionBuffer1 = new Array(count + 1);
+        const subdivisionBuffer2 = new Array(count * 2 + 1);
+        // "toFlatten" contains all the curves which are not yet approximated well enough.
+        // We use a stack to emulate recursion without the risk of running into a stack overflow.
+        // (More specifically, we iteratively and adaptively refine our curve with a
+        // depth-first search (https://en.wikipedia.org/wiki/Depth-first_search)
+        // over the tree resulting from the subdivisions we make.)
+        const toFlatten = [Utils_1.Utils.deepCopy(controlPoints)];
+        const freeBuffers = [];
+        const leftChild = subdivisionBuffer2;
+        while (toFlatten.length > 0) {
+            const parent = toFlatten.pop();
+            if (this.bezierIsFlatEnough(parent)) {
+                // If the control points we currently operate on are sufficiently "flat", we use
+                // an extension to De Casteljau's algorithm to obtain a piecewise-linear approximation
+                // of the bezier curve represented by our control points, consisting of the same amount
+                // of points as there are control points.
+                this.bezierApproximate(parent, output, subdivisionBuffer1, subdivisionBuffer2, count + 1);
+                freeBuffers.push(parent);
+                continue;
+            }
+            // If we do not yet have a sufficiently "flat" (in other words, detailed) approximation we keep
+            // subdividing the curve we are currently operating on.
+            const rightChild = freeBuffers.length > 0
+                ? freeBuffers.pop()
+                : new Array(count + 1);
+            this.bezierSubdivide(parent, leftChild, rightChild, subdivisionBuffer1, count + 1);
+            // We re-use the buffer of the parent for one of the children, so that we save one allocation per iteration.
+            for (let i = 0; i < count + 1; ++i) {
+                parent[i] = leftChild[i];
+            }
+            toFlatten.push(rightChild);
+            toFlatten.push(parent);
+        }
+        output.push(controlPoints[count]);
+        return output;
+    }
+    /**
+     * Approximates a catmull slider's path.
+     *
+     * Creates a piecewise-linear approximation of a Catmull-Rom spline.
+     *
+     * @param controlPoints The anchor points of the slider.
+     */
+    static approximateCatmull(controlPoints) {
+        const result = [];
+        for (let i = 0; i < controlPoints.length - 1; ++i) {
+            const v1 = i > 0 ? controlPoints[i - 1] : controlPoints[i];
+            const v2 = controlPoints[i];
+            const v3 = i < controlPoints.length - 1
+                ? controlPoints[i + 1]
+                : v2.add(v2).subtract(v1);
+            const v4 = i < controlPoints.length - 2
+                ? controlPoints[i + 2]
+                : v3.add(v3).subtract(v2);
+            for (let c = 0; c < this.catmullDetail; ++c) {
+                result.push(this.catmullFindPoint(v1, v2, v3, v4, c / this.catmullDetail));
+                result.push(this.catmullFindPoint(v1, v2, v3, v4, (c + 1) / this.catmullDetail));
+            }
+        }
+        return result;
+    }
+    /**
+     * Approximates a slider's circular arc.
+     *
+     * Creates a piecewise-linear approximation of a circular arc curve.
+     *
+     * @param controlPoints The anchor points of the slider.
+     */
+    static approximateCircularArc(controlPoints) {
+        const a = controlPoints[0];
+        const b = controlPoints[1];
+        const c = controlPoints[2];
+        // If we have a degenerate triangle where a side-length is almost zero, then give up and fall
+        // back to a more numerically stable method.
+        if (Precision_1.Precision.almostEqualsNumber(0, (b.y - a.y) * (c.x - a.x) - (b.x - a.x) * (c.y - a.y))) {
+            return [];
+        }
+        // See: https://en.wikipedia.org/wiki/Circumscribed_circle#Cartesian_coordinates_2
+        const d = 2 *
+            (a.x * b.subtract(c).y +
+                b.x * c.subtract(a).y +
+                c.x * a.subtract(b).y);
+        const aSq = Math.pow(a.length, 2);
+        const bSq = Math.pow(b.length, 2);
+        const cSq = Math.pow(c.length, 2);
+        const center = new Vector2_1.Vector2(aSq * b.subtract(c).y +
+            bSq * c.subtract(a).y +
+            cSq * a.subtract(b).y, aSq * c.subtract(b).x +
+            bSq * a.subtract(c).x +
+            cSq * b.subtract(a).x).divide(d);
+        const dA = a.subtract(center);
+        const dC = c.subtract(center);
+        const r = dA.length;
+        const thetaStart = Math.atan2(dA.y, dA.x);
+        let thetaEnd = Math.atan2(dC.y, dC.x);
+        while (thetaEnd < thetaStart) {
+            thetaEnd += 2 * Math.PI;
+        }
+        let dir = 1;
+        let thetaRange = thetaEnd - thetaStart;
+        // Decide in which direction to draw the circle, depending on which side of
+        // AC B lies.
+        let orthoAtoC = c.subtract(a);
+        orthoAtoC = new Vector2_1.Vector2(orthoAtoC.y, -orthoAtoC.x);
+        if (orthoAtoC.dot(b.subtract(a)) < 0) {
+            dir = -dir;
+            thetaRange = 2 * Math.PI - thetaRange;
+        }
+        // We select the amount of points for the approximation by requiring the discrete curvature
+        // to be smaller than the provided tolerance. The exact angle required to meet the tolerance
+        // is: 2 * Math.Acos(1 - TOLERANCE / r)
+        // The special case is required for extremely short sliders where the radius is smaller than
+        // the tolerance. This is a pathological rather than a realistic case.
+        const amountPoints = 2 * r <= this.circularArcTolerance
+            ? 2
+            : Math.max(2, Math.ceil(thetaRange /
+                (2 * Math.acos(1 - this.circularArcTolerance / r))));
+        const output = [];
+        for (let i = 0; i < amountPoints; ++i) {
+            const fract = i / (amountPoints - 1);
+            const theta = thetaStart + dir * fract * thetaRange;
+            const o = new Vector2_1.Vector2(Math.cos(theta), Math.sin(theta)).scale(r);
+            output.push(center.add(o));
+        }
+        return output;
+    }
+    /**
+     * Approximates a linear slider's path.
+     *
+     * Creates a piecewise-linear approximation of a linear curve.
+     * Basically, returns the input.
+     *
+     * @param controlPoints The anchor points of the slider.
+     */
+    static approximateLinear(controlPoints) {
+        return controlPoints;
+    }
+    /**
+     * Checks if a bezier slider is flat enough to be approximated.
+     *
+     * Make sure the 2nd order derivative (approximated using finite elements) is within tolerable bounds.
+     *
+     * NOTE: The 2nd order derivative of a 2D curve represents its curvature, so intuitively this function
+     * checks (as the name suggests) whether our approximation is _locally_ "flat". More curvy parts
+     * need to have a denser approximation to be more "flat".
+     *
+     * @param controlPoints The anchor points of the slider.
+     */
+    static bezierIsFlatEnough(controlPoints) {
+        for (let i = 1; i < controlPoints.length - 1; ++i) {
+            const prev = controlPoints[i - 1];
+            const current = controlPoints[i];
+            const next = controlPoints[i + 1];
+            const final = prev.subtract(current.scale(2)).add(next);
+            if (Math.pow(final.length, 2) >
+                Math.pow(this.bezierTolerance, 2) * 4) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Approximates a bezier slider's path.
+     *
+     * This uses {@link https://en.wikipedia.org/wiki/De_Casteljau%27s_algorithm De Casteljau's algorithm} to obtain an optimal
+     * piecewise-linear approximation of the bezier curve with the same amount of points as there are control points.
+     *
+     * @param controlPoints The control points describing the bezier curve to be approximated.
+     * @param output The points representing the resulting piecewise-linear approximation.
+     * @param subdivisionBuffer1 The first buffer containing the current subdivision state.
+     * @param subdivisionBuffer2 The second buffer containing the current subdivision state.
+     * @param count The number of control points in the original array.
+     */
+    static bezierApproximate(controlPoints, output, subdivisionBuffer1, subdivisionBuffer2, count) {
+        const l = subdivisionBuffer2;
+        const r = subdivisionBuffer1;
+        this.bezierSubdivide(controlPoints, l, r, subdivisionBuffer1, count);
+        for (let i = 0; i < count - 1; ++i) {
+            l[count + i] = r[i + 1];
+        }
+        output.push(controlPoints[0]);
+        for (let i = 1; i < count - 1; ++i) {
+            const index = 2 * i;
+            const p = l[index - 1]
+                .add(l[index].scale(2))
+                .add(l[index + 1])
+                .scale(0.25);
+            output.push(p);
+        }
+    }
+    /**
+     * Subdivides `n` control points representing a bezier curve into 2 sets of `n` control points, each
+     * describing a bezier curve equivalent to a half of the original curve. Effectively this splits
+     * the original curve into 2 curves which result in the original curve when pieced back together.
+     *
+     * @param controlPoints The anchor points of the slider.
+     * @param l Parts of the slider for approximation.
+     * @param r Parts of the slider for approximation.
+     * @param subdivisionBuffer Parts of the slider for approximation.
+     * @param count The amount of anchor points in the slider.
+     */
+    static bezierSubdivide(controlPoints, l, r, subdivisionBuffer, count) {
+        const midpoints = subdivisionBuffer;
+        for (let i = 0; i < count; ++i) {
+            midpoints[i] = controlPoints[i];
+        }
+        for (let i = 0; i < count; ++i) {
+            l[i] = midpoints[0];
+            r[count - i - 1] = midpoints[count - i - 1];
+            for (let j = 0; j < count - i - 1; ++j) {
+                midpoints[j] = midpoints[j].add(midpoints[j + 1]).divide(2);
+            }
+        }
+    }
+    /**
+     * Finds a point on the spline at the position of a parameter.
+     *
+     * @param vec1 The first vector.
+     * @param vec2 The second vector.
+     * @param vec3 The third vector.
+     * @param vec4 The fourth vector.
+     * @param t The parameter at which to find the point on the spline, in the range [0, 1].
+     */
+    static catmullFindPoint(vec1, vec2, vec3, vec4, t) {
+        const t2 = Math.pow(t, 2);
+        const t3 = Math.pow(t, 3);
+        return new Vector2_1.Vector2(0.5 *
+            (2 * vec2.x +
+                (-vec1.x + vec3.x) * t +
+                (2 * vec1.x - 5 * vec2.x + 4 * vec3.x - vec4.x) * t2 +
+                (-vec1.x + 3 * vec2.x - 3 * vec3.x + vec4.x) * t3), 0.5 *
+            (2 * vec2.y +
+                (-vec1.y + vec3.y) * t +
+                (2 * vec1.y - 5 * vec2.y + 4 * vec3.y - vec4.y) * t2 +
+                (-vec1.y + 3 * vec2.y - 3 * vec3.y + vec4.y) * t3));
+    }
+}
+exports.PathApproximator = PathApproximator;
+PathApproximator.bezierTolerance = 0.25;
+/**
+ * The amount of pieces to calculate for each control point quadruplet.
+ */
+PathApproximator.catmullDetail = 50;
+PathApproximator.circularArcTolerance = 0.1;

package/dist/utils/Precision.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Precision = void 0;
+/**
+ * Precision utilities.
+ */
+class Precision {
+    /**
+     * Checks if two numbers are equal with a given tolerance.
+     *
+     * @param value1 The first number.
+     * @param value2 The second number.
+     * @param acceptableDifference The acceptable difference as threshold. Default is `Precision.FLOAT_EPSILON = 1e-3`.
+     */
+    static almostEqualsNumber(value1, value2, acceptableDifference = this.FLOAT_EPSILON) {
+        return Math.abs(value1 - value2) <= acceptableDifference;
+    }
+    /**
+     * Checks if two vectors are equal with a given tolerance.
+     *
+     * @param vec1 The first vector.
+     * @param vec2 The second vector.
+     * @param acceptableDifference The acceptable difference as threshold. Default is `Precision.FLOAT_EPSILON = 1e-3`.
+     */
+    static almostEqualsVector(vec1, vec2, acceptableDifference = this.FLOAT_EPSILON) {
+        return (this.almostEqualsNumber(vec1.x, vec2.x, acceptableDifference) &&
+            this.almostEqualsNumber(vec1.y, vec2.y, acceptableDifference));
+    }
+}
+exports.Precision = Precision;
+Precision.FLOAT_EPSILON = 1e-3;

package/dist/utils/SliderPath.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SliderPath = void 0;
+const PathType_1 = require("../constants/PathType");
+const PathApproximator_1 = require("../utils/PathApproximator");
+const Vector2_1 = require("../mathutil/Vector2");
+const Precision_1 = require("./Precision");
+/**
+ * Represents a slider's path.
+ */
+class SliderPath {
+    constructor(values) {
+        /**
+         * Whether or not the instance has been initialized.
+         */
+        this.isInitialized = false;
+        /**
+         * The calculated path of the slider.
+         */
+        this.calculatedPath = [];
+        /**
+         * The cumulative length of the slider.
+         */
+        this.cumulativeLength = [];
+        this.pathType = values.pathType;
+        this.controlPoints = values.controlPoints;
+        this.expectedDistance = values.expectedDistance;
+        this.ensureInitialized();
+    }
+    /**
+     * Initializes the instance.
+     */
+    ensureInitialized() {
+        if (this.isInitialized) {
+            return;
+        }
+        this.isInitialized = true;
+        this.calculatedPath.length = 0;
+        this.cumulativeLength.length = 0;
+        this.calculatePath();
+        this.calculateCumulativeLength();
+    }
+    /**
+     * Calculates the slider's path.
+     */
+    calculatePath() {
+        this.calculatedPath.length = 0;
+        let spanStart = 0;
+        for (let i = 0; i < this.controlPoints.length; i++) {
+            if (i === this.controlPoints.length - 1 ||
+                this.controlPoints[i].equals(this.controlPoints[i + 1])) {
+                const spanEnd = i + 1;
+                const cpSpan = this.controlPoints.slice(spanStart, spanEnd);
+                this.calculateSubPath(cpSpan).forEach((t) => {
+                    if (this.calculatedPath.length === 0 ||
+                        !this.calculatedPath.at(-1).equals(t)) {
+                        this.calculatedPath.push(t);
+                    }
+                });
+                spanStart = spanEnd;
+            }
+        }
+    }
+    /**
+     * Calculates the slider's subpath.
+     */
+    calculateSubPath(subControlPoints) {
+        switch (this.pathType) {
+            case PathType_1.PathType.Linear:
+                return PathApproximator_1.PathApproximator.approximateLinear(subControlPoints);
+            case PathType_1.PathType.PerfectCurve: {
+                if (subControlPoints.length !== 3) {
+                    break;
+                }
+                const subPath = PathApproximator_1.PathApproximator.approximateCircularArc(subControlPoints);
+                // If for some reason a circular arc could not be fit to the 3 given points, fall back to a numerically stable bezier approximation.
+                if (subPath.length === 0) {
+                    break;
+                }
+                return subPath;
+            }
+            case PathType_1.PathType.Catmull:
+                return PathApproximator_1.PathApproximator.approximateCatmull(subControlPoints);
+        }
+        return PathApproximator_1.PathApproximator.approximateBezier(subControlPoints);
+    }
+    /**
+     * Calculates the slider's cumulative length.
+     */
+    calculateCumulativeLength() {
+        let calculatedLength = 0;
+        this.cumulativeLength.length = 0;
+        this.cumulativeLength.push(0);
+        for (let i = 0; i < this.calculatedPath.length - 1; ++i) {
+            const diff = this.calculatedPath[i + 1].subtract(this.calculatedPath[i]);
+            calculatedLength += diff.length;
+            this.cumulativeLength.push(calculatedLength);
+        }
+        if (calculatedLength !== this.expectedDistance) {
+            // In osu-stable, if the last two control points of a slider are equal, extension is not performed.
+            if (this.controlPoints.length >= 2 &&
+                this.controlPoints.at(-1).equals(this.controlPoints.at(-2)) &&
+                this.expectedDistance > calculatedLength) {
+                this.cumulativeLength.push(calculatedLength);
+                return;
+            }
+            // The last length is always incorrect
+            this.cumulativeLength.pop();
+            let pathEndIndex = this.calculatedPath.length - 1;
+            if (calculatedLength > this.expectedDistance) {
+                // The path will be shortened further, in which case we should trim any more unnecessary lengths and their associated path segments
+                while (this.cumulativeLength.length > 0 &&
+                    this.cumulativeLength.at(-1) >= this.expectedDistance) {
+                    this.cumulativeLength.pop();
+                    this.calculatedPath.splice(pathEndIndex--, 1);
+                }
+            }
+            if (pathEndIndex <= 0) {
+                // The expected distance is negative or zero
+                this.cumulativeLength.push(0);
+                return;
+            }
+            // The direction of the segment to shorten or lengthen
+            const dir = this.calculatedPath[pathEndIndex].subtract(this.calculatedPath[pathEndIndex - 1]);
+            dir.normalize();
+            this.calculatedPath[pathEndIndex] = this.calculatedPath[pathEndIndex - 1].add(dir.scale(this.expectedDistance - this.cumulativeLength.at(-1)));
+            this.cumulativeLength.push(this.expectedDistance);
+        }
+    }
+    /**
+     * Computes the position on the slider at a given progress that ranges from 0 (beginning of the path)
+     * to 1 (end of the path).
+     *
+     * @param progress Ranges from 0 (beginning of the path) to 1 (end of the path).
+     */
+    positionAt(progress) {
+        this.ensureInitialized();
+        const d = this.progressToDistance(progress);
+        return this.interpolateVerticles(this.indexOfDistance(d), d);
+    }
+    /**
+     * Returns the progress of reaching expected distance.
+     */
+    progressToDistance(progress) {
+        return Math.min(Math.max(progress, 0), 1) * this.expectedDistance;
+    }
+    /**
+     * Interpolates verticles of the slider.
+     */
+    interpolateVerticles(i, d) {
+        if (this.calculatedPath.length === 0) {
+            return new Vector2_1.Vector2(0, 0);
+        }
+        if (i <= 0) {
+            return this.calculatedPath[0];
+        }
+        if (i >= this.calculatedPath.length) {
+            return this.calculatedPath.at(-1);
+        }
+        const p0 = this.calculatedPath[i - 1];
+        const p1 = this.calculatedPath[i];
+        const d0 = this.cumulativeLength[i - 1];
+        const d1 = this.cumulativeLength[i];
+        // Avoid division by and almost-zero number in case two points are extremely close to each other.
+        if (Precision_1.Precision.almostEqualsNumber(d0, d1)) {
+            return p0;
+        }
+        const w = (d - d0) / (d1 - d0);
+        return p0.add(p1.subtract(p0).scale(w));
+    }
+    /**
+     * Returns the index of distance.
+     */
+    indexOfDistance(d) {
+        const index = this.cumulativeLength.indexOf(d);
+        if (index < 0) {
+            for (let i = 0; i < this.cumulativeLength.length; ++i) {
+                if (this.cumulativeLength[i] > d) {
+                    return i;
+                }
+            }
+            return this.cumulativeLength.length;
+        }
+        return index;
+    }
+}
+exports.SliderPath = SliderPath;

package/dist/utils/Utils.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Utils = void 0;
+const lodash_clonedeep_1 = __importDefault(require("lodash.clonedeep"));
+/**
+ * Some utilities, no biggie.
+ */
+class Utils {
+    /**
+     * Returns a random element of an array.
+     *
+     * @param array The array to get the element from.
+     */
+    static getRandomArrayElement(array) {
+        return array[Math.floor(Math.random() * array.length)];
+    }
+    /**
+     * Deep copies an object.
+     *
+     * @param obj The object to deep copy.
+     */
+    static deepCopy(obj) {
+        return (0, lodash_clonedeep_1.default)(obj);
+    }
+    /**
+     * Creates an array with specific length that's prefilled with an initial value.
+     *
+     * @param length The length of the array.
+     * @param initialValue The initial value of each array value.
+     */
+    static initializeArray(length, initialValue) {
+        const array = new Array(length);
+        if (initialValue !== undefined) {
+            for (let i = 0; i < length; ++i) {
+                array[i] = initialValue;
+            }
+        }
+        return array;
+    }
+    /**
+     * Pauses the execution of a function for
+     * the specified duration.
+     *
+     * @param duration The duration to pause for, in seconds.
+     */
+    static sleep(duration) {
+        return new Promise((resolve) => setTimeout(resolve, duration * 1000));
+    }
+}
+exports.Utils = Utils;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@rian8337/osu-base",
+  "version": "1.0.0",
+  "description": "Base module for all osu! related modules.",
+  "keywords": [
+    "osu",
+    "beatmap-parser"
+  ],
+  "author": "Rian8337 <52914632+Rian8337@users.noreply.github.com>",
+  "homepage": "https://github.com/Rian8337/osu-droid-module#readme",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "typings/index.d.ts",
+  "files": [
+    "dist/**",
+    "typings/**"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "jest -i"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rian8337/osu-droid-module.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Rian8337/osu-droid-module/issues"
+  },
+  "dependencies": {
+    "@types/lodash.clonedeep": "^4.5.6",
+    "dotenv": "^14.2.0",
+    "lodash.clonedeep": "^4.5.0",
+    "request": "^2.88.2"
+  },
+  "devDependencies": {
+    "@types/request": "^2.48.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "e4fdb9c1ed6f90e70651c1aedfdb964b61cb240d"
+}