2.6 KiB

Raw Permalink Blame History

PyStorm Testing & Debugging

Fixed Issues

SFILE_FIND_DATA Structure (v1.0.1)

Problem: Segmentation fault when listing files in MPQ archives.

Root Cause: The SFILE_FIND_DATA structure was incorrectly defined with cFileName as a pointer (c_char_p) instead of a fixed-size character array.

Solution: Changed the structure definition to match StormLib's C header:

# WRONG (caused segfault):
class SFILE_FIND_DATA(Structure):
    _fields_ = [
        ("cFileName", c_char_p),  # ❌ Pointer
        ...
    ]

# CORRECT:
class SFILE_FIND_DATA(Structure):
    _fields_ = [
        ("cFileName", c_char * 260),  # ✅ Fixed array (MAX_PATH)
        ...
    ]

This is because StormLib allocates the structure on the stack with a fixed-size buffer, not a heap-allocated string.

Testing with Real MPQ Files

Using Starcraft.mpq

The debug_starcraft.py script tests PyStorm functionality with a real Starcraft MPQ archive:

source venv/bin/activate
python debug_starcraft.py

What it tests:

✅ Import PyStorm
✅ Check file exists
✅ Open archive
✅ List files (890 files found)
✅ Extract file
✅ Close archive

Note: Some MPQ files report size=0 in metadata but contain actual data. This is normal for certain archive types.

GUI Demo

Launch the MPQ Inspector GUI:

source venv/bin/activate
python mpq_inspector.py

Then use File → Open MPQ to browse and select Starcraft.mpq.

Known Issues

Metadata Size = 0

Some files in the archive report dwFileSize = 0 in the file table, but extraction still works correctly. This appears to be a characteristic of the specific MPQ format version used in Starcraft.

Double Close Warning

If you manually close an archive and let Python's garbage collector also call __del__, you might see a segfault. The fix is to set archive._closed = True after manual close, or just rely on the context manager (with statement).

Platform Notes

Linux

Library: libstorm.so (compiled from StormLib source)
Tested on: Ubuntu-like systems with Python 3.13
No issues

Windows

Library: StormLib.dll
Not yet tested

macOS

Library: libstorm.dylib
Not yet tested

Development

When working on PyStorm:

Always activate the virtual environment
Test with real MPQ files, not just synthetic ones
Use debug_starcraft.py as a regression test
The GUI (mpq_inspector.py) is the best end-to-end test

Credits

StormLib by Ladislav Zezula: https://github.com/ladislav-zezula/StormLib
Testing MPQ: Blizzard Entertainment's StarCraft

2.6 KiB Raw Permalink Blame History