Metadata-Version: 2.4
Name: riscos-dumpsprites
Version: 0.1.0
Summary: Display information about RISC OS sprite files
Home-page: https://github.com/gerph/riscos-dumpsprite
Author: Charles Ferguson
Author-email: gerph@gerph.org
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-python
Dynamic: summary

# riscos-dumpsprites

`riscos-dumpsprites` is a Python command line tool for inspecting RISC OS Sprite files.

It supports two output modes:

- A column summary of all sprites in a sprite file.
- A field-by-field report for a single named sprite.
- Machine-readable JSON output for either form.
- Validation reporting for malformed or suspicious sprite structures.

## Usage

Summarise the contents of a sprite file:

```bash
./riscos-dumpsprites sprites/wavytile,ff9
```

Describe a single sprite:

```bash
./riscos-dumpsprites sprites/basi3p02,ff9 basi3p02
```

Emit JSON:

```bash
./riscos-dumpsprites --json sprites/manysprites,ff9
./riscos-dumpsprites --json sprites/basi3p02,ff9 basi3p02
```

Validate a file:

```bash
./riscos-dumpsprites --check sprites/wavytile,ff9
```

Show richer text output:

```bash
./riscos-dumpsprites --verbose sprites/manysprites,ff9
```

Filter the sprite list:

```bash
./riscos-dumpsprites --name 'basi4*' sprites/manysprites,ff9
./riscos-dumpsprites --type 32bpp+a --has-mask sprites/manysprites,ff9
./riscos-dumpsprites --mode 27 sprites/wavytile,ff9
```

Extract a single sprite into its own sprite file:

```bash
./riscos-dumpsprites sprites/wavytile,ff9 tile_1r --extract tile_1r,ff9
```

The parser understands both old-format sprite mode words and the newer sprite mode word format, including alpha-channel and CMYK-related sprite type handling.
Detailed reports and JSON output include decoded palette entries. Text output previews the first 16 palette entries for large palettes.
For documented old-format mode numbers, the tool also reports standard mode metadata such as text resolution, graphics resolution, OS units, and logical colour count.
Summary output distinguishes sprites with no mask, classic 1bpp masks, and 8bpp alpha masks.

## Development

Run the test suite with:

```bash
python3 -m unittest discover -s tests
```

Sample sprite files used for testing live in [`sprites/`](sprites/).

## Publishing

To publish a new version to PyPI:

1. Update the version in `pyproject.toml`.
2. Build and publish using `make`:
   ```bash
   make publish
   ```
   *Note: This requires `twine` to be configured with your PyPI credentials.*

## References

- <https://www.riscos.com/support/developers/prm/sprites.html>
- <https://www.riscos.com/support/developers/prm/video.html>
- <https://www.riscos.com/support/developers/riscos6/graphics/sprites/cmyk.html>
- <https://www.riscos.com/support/developers/riscos6/graphics/sprites/alphachannel.html>
