OapReader

Random-access reader for an Open Asset Package. The header, index, string table and manifest are parsed once at open time; asset blobs are located purely through the index and read (and decrypted / decompressed) on demand. A package opened from a file never loads more than the section being read, so a multi-gigabyte package can be mounted cheaply.

Properties

(OapHeader) : Gets the parsed file header.

Entries

(IReadOnlyList) : Gets the parsed index entries, in stored (sorted) order.

Count

(int): Gets the number of assets in the package.

IsSortedIndex

(bool): Gets a value indicating whether the index is sorted by asset_id.

Manifest

(ReadOnlyMemory?): Gets the package manifest bytes, or when there is no manifest.

Public Methods

Open

public static OapReader Open(byte[] bytes)

Opens a package held entirely in memory. The array is referenced, not copied.

Parameters:

  • bytes (byte[]): The complete .oap bytes.

Returns: OapReader

  • An open reader.

OpenFile

public static OapReader OpenFile(string path)

Opens a package backed by a file, reading only its metadata sections.

Parameters:

  • path (string): The absolute path to the .oap file.

Returns: OapReader

  • An open reader.

SetKey

public void SetKey(ReadOnlySpan<byte> decryptionKey)

Provides the key used to decrypt encrypted assets. Derive one from a passphrase with DeriveKey.

Parameters:

  • decryptionKey (ReadOnlySpan): A 32-byte key.

EntryAt

public OapIndexEntry EntryAt(int index)

Gets the entry at index in stored order.

Parameters:

  • index (int): The zero-based position.

Returns: OapIndexEntry

  • The index entry.

FindById

public OapIndexEntry? FindById(Guid id)

Finds an asset by its 128-bit id. Binary search when the index is sorted.

Parameters:

  • id (Guid): The asset id.

Returns: OapIndexEntry?

  • The matching entry, or when absent.

FindByPath

public OapIndexEntry? FindByPath(string virtualPath)

Finds an asset by its virtual path (linear scan; paths are a secondary key).

Parameters:

  • virtualPath (string): The path to match, compared as UTF-8.

Returns: OapIndexEntry?

  • The matching entry, or when absent.

VirtualPath

public string VirtualPath(OapIndexEntry entry)

Gets the virtual path declared for entry.

Parameters:

  • entry (OapIndexEntry): The index entry.

Returns: string

  • The path, or an empty string when the entry declares none.

Dependencies

public Guid[] Dependencies(OapIndexEntry entry)

Gets the dependency ids declared for entry.

Parameters:

  • entry (OapIndexEntry): The index entry.

Returns: Guid[]

  • The dependency ids, in declared order.

ReadAsset

public byte[] ReadAsset(OapIndexEntry entry, bool verify = true)

Reads an asset's plaintext bytes, decrypting and decompressing as needed. When verify is set the content CRC-32 is checked — a wrong decryption key surfaces here as an OapCorruptDataException.

Parameters:

  • entry (OapIndexEntry): The index entry to read.
  • verify (bool): Whether to verify the content CRC-32. (Default: true)

Returns: byte[]

  • The plaintext asset bytes.

OpenAssetStream

public Stream OpenAssetStream(OapIndexEntry entry)

Opens a readable stream over an asset's plaintext bytes. For a stored, unencrypted asset this is a bounded window over the package with no copy and no full-file load; otherwise the asset is decoded into memory first.

Parameters:

  • entry (OapIndexEntry): The index entry to read.

Returns: Stream

  • A readable stream the caller disposes.