DEV Community

liangqi zhao
liangqi zhao

Posted on Fully Autonomous

Check numbered sprite frame filenames for gaps and duplicate indices with Python

#coding #gamedev #python #tutorial

By Allen Zhao for MotifDeck. This post and example were prepared with AI assistance.

A handoff folder may contain a mixture of walk, idle and attack frames. Before importing a sequence into a game engine, a quick filename report can surface skipped numbers and two names that resolve to the same numeric index. A gap is not necessarily an error: an artist may deliberately keep only selected frames. This check simply makes the decision visible.

What the checker accepts

It reads files directly inside one folder and groups names that end in digits followed by .png. For example, walk_001.png and walk_003.png belong to walk_, and walk_03.PNG has the same numeric index as walk_003.png. Prefixes are grouped without regard to letter case; files without the pattern are ignored. It does not open images or alter files.

Save this as check_frames.py:

from pathlib import Path
import re
import sys

def inspect(paths):
    groups = {}
    for path in paths:
        match = re.fullmatch(r'(.+?)(\d+)\.png', path.name, re.IGNORECASE)
        if match:
            groups.setdefault(match.group(1).casefold(), []).append((int(match.group(2)), path.name))
    results = []
    for prefix, entries in sorted(groups.items()):
        by_num = {}
        for num, name in entries:
            by_num.setdefault(num, []).append(name)
        numbers = sorted(by_num)
        if numbers[-1] - numbers[0] > 100_000:
            raise ValueError(f"{prefix}: range exceeds 100,000; inspect filenames manually")
        missing = sorted(set(range(numbers[0], numbers[-1] + 1)) - set(numbers))
        duplicates = {num: names for num, names in by_num.items() if len(names) > 1}
        results.append((prefix, missing, duplicates))
    return results

if __name__ == '__main__':
    folder = Path(sys.argv[1]) if len(sys.argv) == 2 else None
    if folder is None or not folder.is_dir():
        raise SystemExit('Usage: python check_frames.py DIRECTORY')
    found = inspect(p for p in folder.iterdir() if p.is_file())
    if not found:
        raise SystemExit('No numbered PNG filenames found')
    for prefix, missing, duplicates in found:
        print(f'{prefix}: missing={missing}, duplicate_numbers={duplicates}')
Enter fullscreen mode Exit fullscreen mode

Run it with Python 3:

python check_frames.py ./frames
Enter fullscreen mode Exit fullscreen mode

For walk_001.png, walk_003.png and walk_03.PNG, the report lists missing index 2 and two names for index 3. An idle_2.png file is reported as its own group. If the numeric span exceeds 100,000 the checker stops rather than allocating an unbounded range. Verify whether a missing index is intentional before renaming or adding anything. The script does not validate file contents, frame timing, alignment or whether a file is safe to import.

I checked the grouping, missing-index, duplicate-index and range-limit cases with synthetic filename inputs. Adapt the naming pattern and case rules to your engine and team conventions.

Disclosure: I am affiliated with MotifDeck, an AI game-art workspace. Its limited free plan supports previews; generated-file downloads require a paid unlock. This standalone example is generic and is not a claim about MotifDeck's export format.

Top comments (0)