chore: Abstract and cleanup pack/unpack/dump logic.

Author: Flenarn

tools/cache/lib/configSource.ts

@@ -0,0 +1,87 @@
+export type SourceField = {
+    key: string;
+    value: string;
+    line: number;
+};
+
+export type SourceSection = {
+    name: string;
+    line: number;
+    fields: SourceField[];
+};
+
+export function parseBracketedConfigSource(content: string): SourceSection[] {
+    const lines = content.split('\n');
+    const sections: SourceSection[] = [];
+    let current: SourceSection | null = null;
+
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        const trimmed = line.trim();
+
+        if (trimmed.length === 0 || trimmed.startsWith('//')) {
+            continue;
+        }
+
+        if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+            current = {
+                name: trimmed.substring(1, trimmed.length - 1),
+                line: i + 1,
+                fields: []
+            };
+            sections.push(current);
+            continue;
+        }
+
+        if (!current) {
+            continue;
+        }
+
+        const eq = line.indexOf('=');
+        if (eq === -1) {
+            continue;
+        }
+
+        const key = line.substring(0, eq).trim();
+        const value = line.substring(eq + 1).trim();
+        if (key.length === 0) {
+            continue;
+        }
+
+        current.fields.push({ key, value, line: i + 1 });
+    }
+
+    return sections;
+}
+
+export function resolveSectionId(name: string, nameToId: Map<string, number>, fallbackPrefix: string): number | null {
+    const mapped = nameToId.get(name);
+    if (mapped !== undefined) {
+        return mapped;
+    }
+
+    if (name.startsWith(fallbackPrefix)) {
+        const parsed = parseInt(name.substring(fallbackPrefix.length));
+        if (!isNaN(parsed)) {
+            return parsed;
+        }
+    }
+
+    return null;
+}
+
+export function parseConfigBoolean(value: string): boolean {
+    const normalized = value.trim().toLowerCase();
+    return normalized === 'yes' || normalized === 'true' || normalized === '1';
+}
+
+export function parseConfigInteger(value: string): number {
+    if (value.startsWith('0x') || value.startsWith('0X')) {
+        const parsedHex = parseInt(value, 16);
+        return isNaN(parsedHex) ? 0 : parsedHex;
+    }
+
+    const parsed = parseInt(value);
+    return isNaN(parsed) ? 0 : parsed;
+}

tools/cache/lib/dumpTools.ts

@@ -0,0 +1,18 @@
+import fs from 'fs';
+import path from 'path';
+
+import { ensureDir } from '#tools/cache/lib/js5Tools.js';
+
+export function writeTextDump(outPath: string, lines: string[]): void {
+    ensureDir(path.dirname(outPath));
+    fs.writeFileSync(outPath, lines.join('\n'), 'utf-8');
+}
+
+export function writeBinaryDump(outPath: string, bytes: Uint8Array): void {
+    ensureDir(path.dirname(outPath));
+    fs.writeFileSync(outPath, bytes);
+}
+
+export function formatRgbHex(value: number): string {
+    return `0x${value.toString(16).toUpperCase().padStart(6, '0')}`;
+}

tools/cache/lib/js5Tools.ts

@@ -4,6 +4,7 @@ import Packet from '#/io/Packet.js';
 import { getGroup } from '#/util/OpenRS2.js';
 import { unpackJs5Group } from '#/io/Js5Group.js';
 import { CompressionType } from '#/io/CompressionType.js';
+import { parseJs5ArchiveIndex as parseJs5ArchiveIndexCore, splitGroupFiles } from '#/io/Js5ArchiveIndex.js';
 
 export function readJs5Id(packet: Packet, format: number): number {
     if (format >= 7) {
@@ -117,6 +118,14 @@ export async function readGroupBytes(
 }
 
 export function ensureDir(dirPath: string): void {
+    if (fs.existsSync(dirPath)) {
+        const stat = fs.statSync(dirPath);
+        if (stat.isDirectory()) {
+            return;
+        }
+        throw new Error(`Path exists and is not a directory: ${dirPath}`);
+    }
+
     fs.mkdirSync(dirPath, { recursive: true });
 }
 
@@ -150,11 +159,85 @@ export function parsePackFile(packPath: string): Map<string, number> {
     return nameToId;
 }
 
+export function parsePackFileById(packPath: string): Map<number, string> {
+    if (!fs.existsSync(packPath)) {
+        return new Map();
+    }
+
+    const content = fs.readFileSync(packPath, 'utf-8');
+    const idToName = new Map<number, string>();
+
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0 || trimmed.startsWith('#')) {
+            continue;
+        }
+
+        const eq = trimmed.indexOf('=');
+        if (eq === -1) {
+            continue;
+        }
+
+        const id = parseInt(trimmed.substring(0, eq));
+        const name = trimmed.substring(eq + 1);
+
+        if (!isNaN(id) && name.length > 0) {
+            idToName.set(id, name);
+        }
+    }
+
+    return idToName;
+}
+
 export type Js5ArchiveIndex = {
     groupIds: number[];
     fileIdsByGroup: Map<number, number[]>;
 };
 
+export async function loadArchiveFileIds(indexArchive: number, archive: number, openrs2: boolean = true): Promise<number[]> {
+    const indexPacked = await loadIndexPacked(indexArchive, `data/cache/255/${indexArchive}.dat`, openrs2);
+    const indexData = unpackJs5Group(indexPacked);
+    const { fileIdsByGroup } = parseJs5ArchiveIndexCore(indexData);
+    const fileIds = fileIdsByGroup.get(archive);
+
+    if (!fileIds) {
+        throw new Error(`Archive ${archive} not found in index ${indexArchive}`);
+    }
+
+    return fileIds;
+}
+
+export type LoadedArchiveGroup = {
+    fileIds: number[];
+    groupPacked: Uint8Array;
+    groupUnpacked: Uint8Array;
+    files: Map<number, Uint8Array>;
+};
+
+export async function loadArchiveGroupFiles(
+    indexArchive: number,
+    archive: number,
+    groupsDir: string,
+    openrs2: boolean = true
+): Promise<LoadedArchiveGroup> {
+    const fileIds = await loadArchiveFileIds(indexArchive, archive, openrs2);
+    const groupPacked = await readGroupBytes(indexArchive, archive, groupsDir, openrs2);
+
+    if (!groupPacked) {
+        throw new Error(`Missing group data for index ${indexArchive}, archive ${archive}`);
+    }
+
+    const groupUnpacked = unpackJs5Group(groupPacked);
+    const files = splitGroupFiles(groupUnpacked, fileIds);
+
+    return {
+        fileIds,
+        groupPacked,
+        groupUnpacked,
+        files
+    };
+}
+
 export function parseJs5ArchiveIndex(indexData: Uint8Array): Js5ArchiveIndex {
     const packet = new Packet(indexData);