How to Use osu! Mapping Tools with osu-winello: A Complete Guide

osu-winello provides a dedicated mappingTools command that automates the installation and launching of osu! Mapping Tools inside the Wine prefix.

The nellokudo/osu-winello repository is a Linux wrapper for running osu! via Wine. It includes built-in support for the community-maintained osu! Mapping Tools (a suite of beatmap editing utilities), allowing mappers to access advanced editing features without leaving their Linux environment.

What Are osu! Mapping Tools?

osu! Mapping Tools is a collection of utilities created by the mapping community to streamline beatmap creation, difficulty calculation, and metadata management. These tools typically require a Windows environment or .NET runtime, which osu-winello provides through its Wine prefix configuration.

The mappingTools Command in osu-winello

Rather than manually configuring Wine and downloading installers, osu-winello exposes a single command that handles the entire workflow.

How It Works Internally

When you run osu-wine --mappingtools, the wrapper script located at osu-wine (lines 312-317) intercepts the flag and forwards the request to the main installation script via MainScript "mappingTools".

The core logic resides in the mappingTools() function within osu-winello.sh (lines 825-859). This function performs several critical setup steps:

1. Process Verification – Ensures osu! is not currently running to prevent file locks
2. Environment Setup – Configures a minimal .NET runtime environment inside the Wine prefix
3. DLL Overrides – Disables icu.dll overrides to prevent crashes during tool execution
4. Registry Configuration – Adds the DisableHWAcceleration registry key for Avalon graphics to ensure UI stability
5. Installer Management – Downloads the official mapping_tools_installer_x64.exe using the URL constructed from MAPPINGTOOLSLINK (defined in lines 25-41) and executes it within the Wine prefix
6. Process Integration – Launches Mapping Tools using yawl with the enter=$OSUPID verb, ensuring it runs inside the same Wine container as osu!

Version and Download Configuration

The script maintains version control through variables defined at lines 25-41 of osu-winello.sh:

• MAPPINGTOOLSVERSION – Tracks the current release version
• MAPPINGTOOLSLINK – Constructs the direct download URL for the x64 installer

This ensures users always receive the latest stable release without manual URL hunting.

Step-by-Step Installation and Usage

Follow these steps to run osu! Mapping Tools on Linux using osu-winello:

# 1. Install osu-winello (if not already installed)

git clone https://github.com/NelloKudo/osu-winello.git
cd osu-winello
chmod +x ./osu-winello.sh
./osu-winello.sh

# 2. Launch osu! (required before starting Mapping Tools)

osu-wine

# 3. In a separate terminal, while osu! is running, launch Mapping Tools

osu-wine --mappingtools

Note: If you have already installed osu-winello but never used Mapping Tools, simply run osu-wine --mappingtools. The script automatically detects missing installations, downloads the installer, and launches the tools.

During first installation, the Windows installer UI will appear within your Wine prefix. Accept the default installation prompts to complete the setup.

Key Source Files and Functions

Understanding the source structure helps with troubleshooting:

File	Purpose	Key Section
osu-winello.sh	Core installer and utility functions	Lines 25-41 (version/URL definition), Lines 825-859 (mappingTools() implementation)
osu-wine	User-facing wrapper script	Lines 312-317 (--mappingtools flag handling)
README.md	Documentation	Flags section documenting --mappingtools usage

Summary

• osu-winello provides native Linux support for osu! Mapping Tools through the osu-wine --mappingtools command.
• The implementation automatically handles .NET environment setup, DLL configuration, and registry modifications required for stable operation.
• Mapping Tools run inside the same Wine prefix as osu!, ensuring seamless integration with your existing beatmap library.
• Source code locations: Version definitions in osu-winello.sh lines 25-41, core logic in lines 825-859, and CLI handling in osu-wine lines 312-317.

Frequently Asked Questions

Do I need to install .NET Framework manually to use Mapping Tools with osu-winello?

No. The mappingTools() function in osu-winello.sh automatically configures a minimal .NET environment within the Wine prefix. It handles all necessary runtime dependencies, including disabling problematic icu.dll overrides and setting registry keys for graphics acceleration.

Can I run Mapping Tools while osu! is closed?

No. The script explicitly checks that osu! is running before launching Mapping Tools. The implementation uses yawl with the enter=$OSUPID verb to inject the process into the same Wine container as the running osu! instance. If osu! is not active, the script will prompt you to start it first.

Where are the Mapping Tools installed when using osu-winello?

The installer downloads mapping_tools_installer_x64.exe from the official GitHub releases (as defined by MAPPINGTOOLSLINK in lines 25-41 of osu-winello.sh) and executes it within the Wine prefix. The actual installation location follows the standard Windows installer defaults inside your osu-winello Wine prefix, typically under drive_c/Program Files/ or the user's selected directory during the installation wizard.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}