Tibia Sprites Exporter

A small, fast, and cross-platform CLI utility to extract Tibia client sprite sheets into PNG files and optionally split them into per-sprite PNGs named by their sprite ID. It gives you three focused workflows:

1. extract sprite sheets from the installed client into lossless PNG files.
2. split those sheets into individual sprite images, one file per sprite ID.
3. group sprites back together according to the appearances metadata in the client, producing ready-to-use composites.

Table of Contents

• Highlights
• Prerequisites
• Installation
• Quick Start
• Command Reference
  • extract
  • split
  • group
• Configuration and Defaults
• Output Layout
• Contributing
• Acknowledgements

Highlights

• Purpose-built exporter for the current Tibia desktop client asset pipeline.
• Streaming JSON reader that keeps memory usage flat while traversing catalog-content.json.
• Robust decompression that fixes the client-specific CIP/LZMA headers before decoding the embedded BMPs.
• Progress-aware CLI with human-friendly logging and progress bars for long-running operations.
• Composable commands that let you automate full export pipelines or target just the step you need.

Prerequisites

• Go 1.25 or newer (see go.mod).
• Access to a Tibia installation with a valid catalog-content.json and asset package directory.

Installation

Build from source

Clone the repository and build the CLI:

git clone https://github.com/tilaven/tibia-sprites-exporter.git
cd tibia-sprites-exporter
go build -trimpath -ldflags "-s -w" -o tibia-sprites-exporter ./src

Quick Start

1. Ensure the Tibia client is installed locally.
2. Locate the directory containing catalog-content.json or rely on the defaults.
   • macOS: ~/Library/Application Support/CipSoft GmbH/Tibia/packages/Tibia.app/Contents/Resources/assets
   • Windows: ~/AppData/Local/Tibia/packages/Tibia/assets
   • Linux: ~/.local/share/CipSoft GmbH/Tibia/packages/Tibia/assets
3. Run the extractor (replace paths as needed):

# Extract sprite sheets to ./output/extracted
./tibia-sprites-exporter extract

# Split the generated sheets into per-sprite files
./tibia-sprites-exporter split

# Optionally compose grouped sprites based on appearances metadata
./tibia-sprites-exporter group

All commands support --human for console-friendly logs and --debug for verbose tracing.

Command Reference

Each subcommand inherits global flags from the root command (--catalog, --output, --human, --debug, --config).

extract

Extract compressed sprite sheets from the Tibia assets package.

./tibia-sprites-exporter extract [flags]

• Streams catalog-content.json and processes each element whose type is "sprite".
• Reads the referenced compressed asset, strips the CIP header, patches the LZMA header, and decodes the contained BMP.
• Writes PNG sheets named Sprites-<firstID>-<lastID>.png into the directory specified by --output (defaults to ./output/extracted).
• Displays a progress bar when the total sprite count can be determined.

split

Split sheet PNGs created by extract into per-sprite tiles.

./tibia-sprites-exporter split --splitOutput ./output/split

• Scans the extraction output for files matching Sprites-*.png.
• Uses sprite IDs from the filename to name individual tiles (<spriteID>.png).
• Automatically chooses 64×64 tiles for small sheets and 32×32 otherwise.
• Emits progress updates and continues on errors, logging any issues with individual files.

group

Compose grouped sprite strips based on the client appearances metadata.

./tibia-sprites-exporter group --splitOutput ./output/split --groupedOutput ./output/grouped

• Locates the appearances file referenced in catalog-content.json and parses sprite group definitions.
• Reads the per-sprite PNGs generated by split and assembles composite strips (one PNG per appearance group).
• Skips empty groups and reports how many groups were exported, skipped, or failed.

Configuration and Defaults

This CLI now uses Viper for configuration. Settings can come from, in order of precedence: command-line flags > environment variables > config file > built-in defaults.

• Config file
  • By default, the tool looks for ~/.tse.yaml (you can override with --config).
  • Example ~/.tse.yaml:

    catalog: ~/Library/Application Support/CipSoft GmbH/Tibia/packages/Tibia.app/Contents/Resources/assets
    output: ./output/extracted
    debug: false
    human: true
    splitOutput: ./output/split
    groupedOutput: ./output/grouped

• Environment variables
  • Prefix: TSE_. Keys are uppercased and use underscores. Examples:
    • TSE_CATALOG=/path/to/assets
    • TSE_OUTPUT=./output/extracted
    • TSE_DEBUG=true
    • TSE_HUMAN=true
    • TSE_SPLITOUTPUT=./output/split
    • TSE_GROUPEDOUTPUT=./output/grouped
• Global flags
  • --config <path> – Optional YAML config file (defaults to ~/.tse.yaml if present).
  • --catalog, -c <path> – Directory containing catalog-content.json. A direct path to the file also works.
  • --output, -o <path> – Destination for extracted sheets (./output/extracted by default).
  • --debug – Enable debug-level logging.
  • --human – Render logs with timestamps and levels formatted for humans instead of JSON.
• Command flags
  • split --splitOutput <path> – Directory for individual sprite PNGs (./output/split).
  • group --splitOutput <path> – Where group reads individual sprites from (./output/split).
  • group --groupedOutput <path> – Destination for grouped composites (./output/grouped).

Output Layout

output/
  extracted/      # Sprites-<first>-<last>.png generated by `extract`
  split/          # <spriteID>.png tiles generated by `split`
  grouped/        # Composite strips generated by `group`

Each directory is created on demand if it does not already exist.

Contributing

Bug reports, suggestions, and pull requests are welcome. Please include reproduction steps or sample assets (where legally shareable) so maintainers can validate fixes quickly.

Acknowledgements

Tibia is a trademark of CipSoft GmbH. This exporter is a community-driven effort and is not affiliated with or endorsed by CipSoft.