[!TIP] 本文档由 AI 阅读代码后生成。中文版本已经过本人初步审校。英文版本基于中文版本由 AI 翻译生成。如有问题或更好的文档，欢迎提交 Issue。
This document is generated by AI after reading the code. The Chinese version has been preliminarily reviewed by the author. The English version is AI-translated based on the Chinese version. If you have any issues or a better version of the documentation, please feel free to submit an Issue.

简体中文 | English

@lol-archiver/lol-wad-extract

一个英雄联盟 WAD 归档文件提取工具。提供了计算 WAD 内部路径哈希，以及按需提取、自动解压文件的能力。

基础示例

import { hashWAD, extractWAD } from '@lol-archiver/lol-wad-extract';


// --- 计算 WAD 内文件路径的哈希值 ---
const hash = hashWAD('data/characters/morgana/morgana.bin');
console.log(hash); // 例如 123456789012345n (bigint)


// --- 提取 WAD 中的文件 ---
const extracted = await extractWAD(
  './Game/DATA/FINAL/Champions/Morgana.wad.client',
  [
    {
      fileInpack: 'data/characters/morgana/morgana.bin',
      fileSave: './saved/morgana.bin'
    },
    {
      fileInpack: 'assets/characters/morgana/hud/morgana_circle_0.tex'
    }
  ],
  { fileZSTD: '/usr/bin/zstd' } // 使用自定义 zstd
);

console.log(extracted[0].saved); // true (指定fileSave，文件写入后为true)
console.log(extracted[1].buffer); // 原始 Buffer（若未保存到磁盘）

核心概念

@lol-archiver/lol-wad-extract 包含两个核心函数：

• hashWAD – 根据英雄联盟 WAD 文件的哈希规则，将内部虚拟路径转换为对应的 64 位哈希值。这是定位 WAD 内文件条目的关键。
• extractWAD – 读取 WAD 文件，根据给定的路径列表找到对应条目，完成解压并可选地将文件写出到磁盘。

WAD 文件本身是一种包含多个文件的归档格式，每个条目都通过其路径的哈希值进行索引。本库会遍历 WAD 的条目表，仅提取你指定的那些文件，避免全量读取。

安装

npm install @lol-archiver/lol-wad-extract

该包仅支持 Node.js 环境，它依赖 fs、child_process 和 zlib 等原生模块。

API 参考

hashWAD(string, format?)

计算 WAD 内部文件路径的 XXHash 哈希值。

• 参数:
  • string {string} – WAD 内的文件路径（例如 data/images/champion.png）。内部会统一转为小写，请确保传入的路径与 WAD 中存储的格式一致。
  • format {string} 可选 – 返回值的格式，可选值：
    • 'bigint' (默认) – 返回 bigint 类型的哈希。
    • 'hexpad' – 返回至少 10 位固定宽度的十六进制字符串（前补零）。
• 返回值: {bigint | string} – 对应的哈希值。

const hashBigint = hashWAD('data/characters/morgana/morgana.bin');
console.log(hashBigint); // 16965086179359362018n

const hashHex = hashWAD('data/characters/morgana/morgana.bin', 'hexpad');
console.log(hashHex); // 'eb7017fec89a8be2'

extractWAD(fileWAD, configsExtractRaw, options?)

从 WAD 归档中提取指定文件。

• 参数:
  • fileWAD {string} – WAD 文件的路径。
  • configsExtractRaw {RawExtractConfig[]} – 要提取的文件列表，每个对象的属性：
    • fileInpack {string} – 文件在 WAD 内的虚拟路径。
    • fileSave {string} – 文件提取后保存到磁盘的目标路径。
  • options {ExtractOption} 可选 – 提取选项：
    • fileZSTD {string} – 外部 zstd 可执行文件的路径。若提供，则 Zstandard 解压通过 spawnSync 调用该程序完成；否则使用 Node.js 内置的 zstdDecompressSync。
    • maxBufferUnzstd {number} – 调用外部 zstd 时允许的最大缓冲区大小（字节），默认值为 buffer.length * 16。超过此大小会报错。
• 返回值: {Promise<ExtractConfig[]>} – 返回一个成功提取的配置（包含 buffer与saved ）数组。

const result = await extractWAD(
  './Game/DATA/FINAL/Champions/Morgana.wad.client',
  [
    {
      fileInpack: 'data/characters/morgana/morgana.bin',
      fileSave: './saved/morgana.bin'
    },
    { 
      fileInpack: 'assets/characters/morgana/hud/morgana_circle_0.tex'
    }
  ],
  { fileZSTD: '/usr/bin/zstd' } // 使用自定义 zstd
);

console.log(result.length); // 2（如果两个文件都找到）

类型定义

// 提取选项
interface ExtractOption {
  /** 外部 zstd 可执行文件路径 */
  fileZSTD: string;

  /** 外部 zstd 解压时允许的最大缓冲大小（字节） */
  maxBufferUnzstd?: number;
}

// 原始提取配置（用户输入）
interface RawExtractConfig {
  /** WAD 内的文件路径 */
  fileInpack: string;
  
  /** 提取后保存的磁盘路径 */
  fileSave: string;
}

// 最终提取配置（包含提取结果）
interface ExtractConfig {
  fileInpack: string;
  fileSave: string;
  
  /** 文件的 WAD 内哈希（由库计算） */
  hashInpack?: string;
  /** 解压后的数据 Buffer（若提取失败则不存在） */
  buffer?: Buffer;
  /** 是否已成功写入磁盘 */
  saved?: boolean;
}

注意事项

外部 Zstandard 依赖

若 WAD 中包含 Zstandard 压缩，你有两种处理方式：

1. 使用内置解压：使用 Node.js 支持 zstdDecompressSync（node:zlib），此时无需任何外部依赖。
2. 使用外部 zstd：通过 options.fileZSTD 指定 zstd 的路径。这在你希望利用原生性能时很有用。

哈希计算

hashWAD 基于 XXHash64 算法，输入字符串会先转换为全小写。该算法与 Riot 游戏客户端中计算 WAD 条目哈希的方式一致。

传递相同的fileInpack

如果extractWAD的configsExtractRaw参数中传入相同的fileInpack，则只有最后一个传递的配置生效

错误代码

| 代码 | 位置 | 描述 | 上下文数据 | | :------------------ | :-------------------------------- | :------------------------------------------- | :------------------------------------- | | spawn-zstd-error | lol-wad-extract/unzstd | 运行ZSTD时发送错误 | { buffer, fileZSTD, maxBuffer } | | invalid-string | lol-wad-extract/hashWAD(1:string) | hashWAD() 的 string 参数必须为字符串类型 | { string, isHex } | | unused-extract-type | lol-wad-extract/extractWAD | 未使用的解压类型 | { type, hash, offset, compressedSize } |