A skin folder can hide a surprising number of animation sequences: hit bursts, slider balls, overlays, combo bursts, the health-bar fill. If the frame list has gaps, or if AnimationFramerate is still set for a 2-frame flicker, you only notice in-game. This short script lists numbered sequences in a skin folder and prints the current AnimationFramerate from skin.ini so you can decide what to fix before you pack an .osk.
It uses only the Python standard library. Point it at the root of a skin (the folder that contains skin.ini).
#!/usr/bin/env python3
"""List contiguous osu! skin animation sequences and AnimationFramerate."""
import re
import sys
from collections import defaultdict
from pathlib import Path
FRAME_RE = re.compile(
r"^(?P<base>.+?)-(?P<idx>\d+)(?P<hd>@2x)?\.(?P<ext>png|jpg)$",
re.I,
)
SLIDERB_RE = re.compile(
r"^(?P<base>sliderb)(?P<idx>\d+)(?P<hd>@2x)?\.(?P<ext>png|jpg)$",
re.I,
)
def animation_framerate(ini: Path) -> str:
if not ini.is_file():
return "(no skin.ini)"
rate = None
for line in ini.read_text(errors="replace").splitlines():
s = line.split('#', 1)[0].strip()
if s.lower().startswith('animationframerate'):
parts = s.split(':', 1)
rate = parts[1].strip() if len(parts) == 2 else s
return rate or "(not set)"
def collect(folder: Path):
groups = defaultdict(set)
for p in folder.iterdir():
if not p.is_file():
continue
m = SLIDERB_RE.match(p.name) or FRAME_RE.match(p.name)
if not m:
continue
key = (m["base"].lower(), m["hd"] or "", m["ext"].lower())
groups[key].add(int(m["idx"]))
return groups
def main():
root = Path(sys.argv[1] if len(sys.argv) > 1 else '.').expanduser()
print('skin:', root.resolve())
print('AnimationFramerate:', animation_framerate(root / 'skin.ini'))
groups = collect(root)
if not groups:
print('No numbered animation frames found.')
return
for (base, hd, ext), idxs in sorted(groups.items()):
seq = sorted(idxs)
expected = list(range(seq[0], seq[-1] + 1))
missing = [i for i in expected if i not in idxs]
tag = base + (hd or '') + '.' + ext
gap = (', missing ' + str(missing)) if missing else ''
print(f'{tag}: {len(seq)} frames, {seq[0]}-{seq[-1]}' + gap)
if __name__ == '__main__':
main()
I ran this against a temporary folder with hit300-0.png, hit300-1.png, hit300-3.png and sliderb0.png. It reported a hit300 sequence spanning 0-3 with frame 2 missing, and a one-frame sliderb sequence, which is the kind of gap that is hard to see in a file listing.
Read the output as a checklist, not as a verdict. A two-frame burst at a high AnimationFramerate will flicker; a long scorebar-colour cycle at 15 FPS may look sluggish. Missing frames are worth fixing first. Then test the element in-game: streams for hit bursts, a long slider for the ball.
If you want reference folders to practise on, complete skins from osuskins.org unpack to a normal directory the script can scan. Run it before you upload the .osk so you are not packing a broken sequence by mistake.
Top comments (0)