Introduction

Assist.Games Research is a side-project that aims to bring expose osu! scripting interface for public usage. By doing so, we provide ways to hook, patch and modify osu! runtime without low-level programming knowledge. The interface is being served by OAC(assist.games osu! client). The scripting interface was designed to provide access to all the features that would allow gameplay modifications.

• Native Dear Imgui drawing support using simplified Javascript interface (Diglet Project)
• Easy osu! input overriding.
• Support for integration with already existing GUI Interface.
• Custom loader and authentication based on Assist.Game services.
• Function hooking and patching using x86 ASM.

Terms of usage

Scripting Interface cannot be used online. The API automatically prevents score-submissions when the interface is called by foreign script. You will be banned without warning if we detect malicious intent when using SI in online play. We want to stay on Peppy’s good side here.

Online usage is strictly prohibited for now!

Exported Methods

• base
  • config
  • async login(code: string)
  • hideConsole()
  • getClipboard()
  • openFileDialog(name: string, format: string)
  • saveFileDialog(name: string, format: string)
  • get osu()
  • get drawlist()
  • parseReplay(replayPath: string)
  • createInteractable(data)
  • osu
    • get window()
    • get playField()
    • get hookManager()
    • get addresses()
    • set mouseOverride(value: number)
    • set keyOverride(value: number)
    • set cursorPosition(value: Vector2)
    • setKeys(k1: number, k2: number)
    • get originalCursorPosition()
    • get time()
    • get player()
    • get process()
    • get mods()
    • getKeyState(key: number)
    • get audioLength()
    • requestAudioSeek(milliseconds: number)
    • requestFramesInjection()
    • setFramesCapacity(capacity: number)
    • async setCurrentBeatmap(checksum: string, withEditor: boolean)
    • get currentGameMode()
    • get editorHitObjectManager()
    • set dimLevel(value: number)
    • set editorGridShow(show: boolean)
    • get framesList()

Creating a script

Setup

Get started by cloning our script template.

git clone https://github.com/assistgames/module-template

then you need to install all the dependecies by doing

npm install

What you’ll need

• Node.js version 18.4.0 32 bit:
  • When installing Node.js, you are recommended to check all checkboxes related to dependencies.
• Interface Executable:
  • You need to be whitelisted and active subscriber on Assist.Games.

• Intermediate TypeScript and JavaScript knowledge

• Intermediate Game Hacking knowledge

Exporting Script Class

Inside our /src/main.ts we can see a simple script that does nothing.

In order for the base to understand your script, you must export a Script class, which contains required methods.

import { BaseInterface, ScriptBase } from "../scriptInterface";

export class Script implements ScriptBase {
    private base: BaseInterface;

    constructor(base: BaseInterface) {
        this.base = base;
    }

    ready(): void {

    }
    mapStart(type: "fast" | "lazy"): void {

    }
    mapEnd(): void {

    }
    cleanup(): void {

    }
}

• constructor
  • Gets called when the script is initiated, user might not be authenticated.
  • Access to osu interface is not present
• ready()
  • Called when user logs in successfully
  • Safe for hooking and overriding cursor or keyboard.
  • this.base.osu becomes accessible.
• mapStart()
  • Called map starts
• mapStart()
  • Called map ends
• mapStart()
  • Called when base unloads the script

Adding a tab

Let’s add a simple menu tab and checkbox. We can do that by creating a config field like this.

private tabName: string = "My Cool Script";
private enabledOption: ConfigField;
constructor(base: BaseInterface) {
    this.base = base;
    this.enabledOption = this.base.config.field(`${this.tabName}::Enabled`, { value: false });
}

Build your script

Building your script is fairly easy, you need to re-name the output file in the build.js script.

require('esbuild').build({
    entryPoints: ['./src/main.ts'],
    bundle: true,
    outfile: "./my-awesome-script.js", // <---- here
    format: "cjs"
})

Now by running the build command

npm build

you should be able to see a generated .js file.

Loading your script

To load your script you need to move it to the same folder with the base file

    /my-scripts
        /interface.exe
        /settings.json
        /my-cool-script.build.js

after starting interface.exe, it should output any errors if they are present.

Get Involved

Scripting Interface is not free. You currently need to be whitelisted to get access to it, as we’re still updating it actively. Assist Games Research group is maintained by Dima and Cherry.

• Join us on Discord.
• Issues are tracked on GitHub Issues.

Feel free to buy on Assist.Games.