DEV Community

Frank
Frank

Posted on

Parsing osu! skin.ini files: the quirks nobody documents

If you have ever tried to build a tool around osu! skins (a previewer, a converter, a "which skin is this?" bot), you hit skin.ini within the first hour. It looks like a plain INI file. It is not quite one. Here are the quirks I ran into while indexing a few thousand skins for osuskins.org, and a small Python parser that survives real-world files.

What is actually inside an .osk

An .osk file is just a ZIP archive with a different extension. Inside you get images (hitcircle.png, cursor@2x.png, default-0.png...), sounds (normal-hitclap.wav...) and, usually, a skin.ini. Sometimes the whole skin sits inside one extra top-level folder, so do not assume skin.ini is at the root:

import zipfile

def find_skin_ini(osk_path):
    with zipfile.ZipFile(osk_path) as z:
        candidates = [n for n in z.namelist() if n.lower().endswith("skin.ini")]
        # shortest path wins: the real one, not a backup in a subfolder
        candidates.sort(key=lambda n: n.count("/"))
        return candidates[0] if candidates else None
Enter fullscreen mode Exit fullscreen mode

Note .lower(): file names inside skins come from Windows users, so Skin.ini, SKIN.INI and skin.ini all appear in the wild.

The quirks

1. Encoding is a lottery. Most files are UTF-8, many have a BOM, and older ones from Japanese, Korean or Russian creators are in Shift-JIS, CP949 or CP1251. Decode with utf-8-sig first and fall back, rather than crashing on byte 0x82.

2. Comments are //, not ;. Python's configparser will choke on them, and on duplicate keys, and on the repeated [Mania] sections (see below). Write your own line parser; it is 30 lines.

3. Sections repeat. [Mania] appears once per key count, each block starting with Keys: 4, Keys: 7 and so on. Treat it as a list, keyed by the Keys value.

4. Separators are : and whitespace is everywhere. Name: Rafis, Name:Rafis and Name : Rafis all show up.

5. Colours are r,g,b or r,g,b,a, sometimes with spaces, occasionally with a stray trailing comma. Combo1 to Combo8 define combo colours; if none are given the game uses its defaults.

6. Version changes behaviour. Version: 1.0, 2.0, 2.5, 2.7 or latest controls how some elements are drawn (for example the old vs. new spinner and the mania layout). A missing Version key in an existing skin.ini means 1.0, which surprises people whose "modern" skin suddenly renders with legacy rules.

7. Missing files fall back to the default skin. A skin that only ships a cursor and hit circles is perfectly valid. Your previewer needs the default assets on hand, or it will show holes.

A parser that survives real files

import re

ENCODINGS = ("utf-8-sig", "shift_jis", "cp949", "cp1251", "latin-1")

def decode(raw: bytes) -> str:
    for enc in ENCODINGS:
        try:
            return raw.decode(enc)
        except UnicodeDecodeError:
            continue
    return raw.decode("utf-8", errors="replace")

def parse_skin_ini(raw: bytes) -> dict:
    data = {"mania": []}
    section = None
    current = None
    for line in decode(raw).splitlines():
        line = line.split("//", 1)[0].strip()
        if not line:
            continue
        m = re.match(r"^\[(.+?)\]$", line)
        if m:
            section = m.group(1).strip().lower()
            if section == "mania":
                current = {}
                data["mania"].append(current)
            else:
                current = data.setdefault(section, {})
            continue
        if ":" not in line or current is None:
            continue
        key, value = (p.strip() for p in line.split(":", 1))
        current[key] = value  # last one wins, like the game
    return data

def colour(value: str):
    parts = [p.strip() for p in value.split(",") if p.strip()]
    nums = [max(0, min(255, int(float(p)))) for p in parts[:4]]
    return tuple(nums) if len(nums) >= 3 else None
Enter fullscreen mode Exit fullscreen mode

Usage:

ini = parse_skin_ini(open("skin.ini", "rb").read())
general = ini.get("general", {})
print(general.get("Name"), "by", general.get("Author"))
combos = [colour(v) for k, v in sorted(ini.get("colours", {}).items())
          if k.lower().startswith("combo")]
print([c for c in combos if c])
for block in ini["mania"]:
    print(block.get("Keys"), "keys, column width:", block.get("ColumnWidth"))
Enter fullscreen mode Exit fullscreen mode

Splitting on // naively would break a URL in a value, but skin.ini values almost never contain URLs, and the game itself treats // as a comment start, so matching the game is the right call.

Things worth extracting for a catalogue

When I index skins, these fields turned out to be the most useful for players browsing:

  • Name, Author, Version from [General]
  • combo colours (great for "show me blue skins" filters)
  • which modes the skin actually skins: look for taiko-*, fruit-* and mania-* images, plus [Mania] blocks
  • whether HD (@2x) assets exist
  • cursor settings like CursorExpand and CursorRotate, which players care about a lot

Try it on real skins

If you want a pile of real-world files to test against, osuskins.org lists thousands of skins with the creator credited and direct, link-checked downloads (no ad-gate, no login). The install guide is handy if you are new to osu! and want to see how the game loads what you just parsed, and the in-browser skin editor shows the same skin.ini fields as a form.

If you find a skin.ini quirk I missed, tell me in the comments. There is always one more.

Top comments (0)