v1

Documentation

Overview

Package v1 reads and writes Total Annihilation HPI archives (version 0x00010000). The directory tree and every file payload are scrambled with HPI's position-dependent XOR cipher and stored as multi-chunk SQSH streams.

Index

• type Reader
  • func Open(path string) (*Reader, error)
  • func (r *Reader) Close() error
  • func (r *Reader) Find(path string) *common.Entry
  • func (r *Reader) Header() *common.Header
  • func (r *Reader) List() []string
  • func (r *Reader) Open(path string) (io.ReadCloser, error)
  • func (r *Reader) OpenEntry(entry *common.Entry) (io.ReadCloser, error)
  • func (r *Reader) ReadRawFileData(entry *common.Entry) ([]byte, error)
  • func (r *Reader) ReadTrailer() ([]byte, error)
  • func (r *Reader) Root() *common.Entry
  • func (r *Reader) Version() uint32
  • func (r *Reader) Walk(fn func(*common.Entry) error) error
• type Writer
  • func CreateWriter(path string) (*Writer, error)
  • func (w *Writer) AddDirectory(archivePath, dirPath string) error
  • func (w *Writer) AddFile(archivePath, filePath string) error
  • func (w *Writer) AddFileFromBytes(archivePath string, data []byte) error
  • func (w *Writer) AddRawEntry(archivePath string, rawChunks []byte, decompSize uint32, compType uint8)
  • func (w *Writer) Close() error
  • func (w *Writer) SetTrailer(data []byte)
• type WriterEntry

Types

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader reads a Total Annihilation (v1) HPI archive.

A Reader is not safe for concurrent use: every read seeks the shared file handle, so callers serving an archive to multiple goroutines must serialize access.

func Open

func Open(path string) (*Reader, error)

Open opens a v1 HPI archive for reading.

func (*Reader) Close

func (r *Reader) Close() error

Close closes the underlying file.

func (*Reader) Find

func (r *Reader) Find(path string) *common.Entry

Find locates an entry by path.

func (*Reader) Header

func (r *Reader) Header() *common.Header

Header returns the archive header.

func (*Reader) List

func (r *Reader) List() []string

List returns the full paths of every file in the archive.

func (*Reader) Open

func (r *Reader) Open(path string) (io.ReadCloser, error)

Open opens a file from the archive by path.

func (*Reader) OpenEntry

func (r *Reader) OpenEntry(entry *common.Entry) (io.ReadCloser, error)

OpenEntry opens a file entry for reading.

func (*Reader) ReadRawFileData

func (r *Reader) ReadRawFileData(entry *common.Entry) ([]byte, error)

ReadRawFileData returns the raw on-disk bytes for a compressed file entry: the chunk size table followed by the SQSH chunk headers and their payloads. This is the exact byte sequence stored in the archive (after decryption), suitable for writing back verbatim into a new archive via AddRawEntry.

func (*Reader) ReadTrailer

func (r *Reader) ReadTrailer() ([]byte, error)

ReadTrailer returns any bytes that follow the last file's chunk data up to the end of the archive. Returns nil if there is no trailing data.

func (*Reader) Root

func (r *Reader) Root() *common.Entry

Root returns the root directory entry.

func (*Reader) Version

func (r *Reader) Version() uint32

Version reports the on-disk HPI version (always VersionV1).

func (*Reader) Walk

func (r *Reader) Walk(fn func(*common.Entry) error) error

Walk traverses every entry in the archive.

type Writer

type Writer struct {
	CompressionLevel  int   // zlib level (0–9); 0 means default
	CompressionMethod uint8 // 0=none, 1=LZ77, 2=zlib (default)

	// HeaderKey is the raw HeaderKey value stored in the HPI header. The
	// reader transforms it into the per-byte XOR key used for the directory
	// and chunk regions. A value of 0 disables encryption. Defaults to
	// common.DefaultHeaderKey when the writer is created via CreateWriter.
	HeaderKey uint8

	// ChunkEncoded controls whether each SQSH chunk's compressed payload is
	// run through the per-position add/XOR transform. Defaults to true,
	// matching every chunk shipped in retail TA archives.
	ChunkEncoded bool
	// contains filtered or unexported fields
}

Writer builds a Total Annihilation (v1) HPI archive.

func CreateWriter

func CreateWriter(path string) (*Writer, error)

CreateWriter creates a new v1 HPI archive at the given path. The writer is initialised with the Total Annihilation retail defaults: HeaderKey 0xBF, LZ77 compression, encoded chunks, and the Cavedog copyright trailer. Override any of these fields (or call SetTrailer) before adding files to change the produced archive.

func (*Writer) AddDirectory

func (w *Writer) AddDirectory(archivePath, dirPath string) error

AddDirectory recursively adds every file under dirPath, rooted at archivePath inside the archive.

func (*Writer) AddFile

func (w *Writer) AddFile(archivePath, filePath string) error

AddFile reads a file from disk and adds it to the archive.

func (*Writer) AddFileFromBytes

func (w *Writer) AddFileFromBytes(archivePath string, data []byte) error

AddFileFromBytes adds a file from an in-memory byte slice. The compression method used is determined by the Writer's CompressionMethod field.

func (*Writer) AddRawEntry

func (w *Writer) AddRawEntry(archivePath string, rawChunks []byte, decompSize uint32, compType uint8)

AddRawEntry adds a pre-compressed file entry whose chunk payload will be written verbatim. Used for lossless round-trips.

func (*Writer) Close

func (w *Writer) Close() error

Close finalises the archive and closes the underlying file.

func (*Writer) SetTrailer

func (w *Writer) SetTrailer(data []byte)

SetTrailer sets optional trailing bytes appended after the file data section.

type WriterEntry

type WriterEntry struct {
	Path string
	Data []byte

	// When IsRawPassthrough is set the writer stores RawChunks verbatim
	// instead of compressing Data. This is used for byte-perfect round-trips
	// where the original compressed representation must be preserved.
	RawChunks        []byte
	DecompSize       uint32
	CompType         uint8
	IsRawPassthrough bool
}

WriterEntry holds a file's metadata and payload for writing into an archive.