pw-guild-icon-parser/README.md

Parser for Perfect World guild icon lists - converts PNG icons to DDS atlas format with DXT5 compression

# PW Guild Icon Parser

A TypeScript npm package for parsing and managing Perfect World guild icon lists. Converts PNG icons to DDS atlas format with DXT5 compression.

## Features

- Validates PNG icons (must be 16x16 pixels)
- Converts PNG to DDS DXT5 format with alpha channel support
- Builds icon atlas (62x62 grid of 16x16 icons = 992x992 pixels)
- Preserves existing icons when adding new ones
- Updates icon list text file automatically

## Installation

```bash
npm install pw-guild-icon-parser
```

## Usage

```typescript
import { addIcon } from 'pw-guild-icon-parser';

await addIcon({
  fid: 2,
  serverId: 100,
  pngPath: './path/to/icon.png',
  txtPath: './data/iconlist_guild.txt',
  ddsPath: './data/iconlist_guild.dds'
});
// Creates: 100_2.dds in the TXT file
```

## Requirements

- PNG files must be exactly 16x16 pixels (valid PNG format)
- The icon list file (`iconlist_guild.txt`) must follow the format:
  - Line 1: Icon width (16)
  - Line 2: Icon height (16)
  - Line 3: Number of icons in width (62) - the game calculates: DDS width = line3 * line1
  - Line 4: Number of icons in height (62) - the game calculates: DDS height = line4 * line2
  - Line 5+: Icon names (format: `serverid_fid.dds`)

**Note:** The default icon `0_0.dds` is automatically added as the first icon if it doesn't exist. The file maintains the grid dimensions (62) not pixel dimensions (992).

## API

### `addIcon(options: AddIconOptions)`

Adds a new icon to the guild icon list.

**Parameters:**
- `fid: number` - Faction ID
- `serverId: number` - Server ID
- `pngPath: string` - Path to 16x16 PNG file (valid PNG format)
- `txtPath: string` - Path to iconlist_guild.txt
- `ddsPath: string` - Path to iconlist_guild.dds (will be created/updated)

**Throws:** Error if PNG is invalid, grid is full, or file operations fail

## Compatibility

- Works with Next.js and other compiled environments
- Pure TypeScript/JavaScript implementation
- Uses Sharp for image processing (cross-platform)

## License

MIT