# 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:

```python
# 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:

```bash
source venv/bin/activate
python debug_starcraft.py
```

**What it tests**:
1. ✅ Import PyStorm
2. ✅ Check file exists
3. ✅ Open archive
4. ✅ List files (890 files found)
5. ✅ Extract file
6. ✅ 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:

```bash
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:

1. Always activate the virtual environment
2. Test with real MPQ files, not just synthetic ones
3. Use `debug_starcraft.py` as a regression test
4. 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