enfusion-mcp 0.5.0 → 0.6.0

package/README.md

@@ -1,188 +1,194 @@
-# enfusion-mcp
-
-MCP server for Arma Reforger modding. Describe what you want to build, and Claude handles everything — API research, code generation, project scaffolding, Workbench control, and in-editor testing. Zero modding experience required.
-
-## Install
-
-### Claude Code (Windows)
-
-```bash
-claude mcp add --scope user enfusion-mcp -- cmd /c npx -y enfusion-mcp
-```
-
-### Claude Code (macOS / Linux)
-
-```bash
-claude mcp add --scope user enfusion-mcp -- npx -y enfusion-mcp
-```
-
-Restart Claude Code. Verify with `/mcp`.
-
-### Claude Desktop
-
-Add to your `claude_desktop_config.json`:
-
-**Windows:**
-
-```json
-{
-  "mcpServers": {
-    "enfusion-mcp": {
-      "command": "cmd",
-      "args": ["/c", "npx", "-y", "enfusion-mcp"]
-    }
-  }
-}
-```
-
-**macOS / Linux:**
-
-```json
-{
-  "mcpServers": {
-    "enfusion-mcp": {
-      "command": "npx",
-      "args": ["-y", "enfusion-mcp"]
-    }
-  }
-}
-```
-
-### Workbench Plugin
-
-The live Workbench tools (`wb_*`) require handler scripts running inside Workbench. These ship with the package in `mod/Scripts/WorkbenchGame/EnfusionMCP/` and are installed automatically when Claude launches Workbench via `wb_launch`.
-
-## Usage
-
-Just ask Claude to make a mod:
-
-- *"Create a HUD widget that shows player health and stamina"*
-- *"Make a zombie survival game mode with wave spawning"*
-- *"Create a custom faction called CSAT with desert camo soldiers"*
-- *"Add an interactive object that heals the player when used"*
-- *"Override the damage system to add armor mechanics"*
-
-Or use the guided prompts for structured workflows:
-
-| Prompt | Description |
-|--------|-------------|
-| `/create-mod` | Full guided mod creation — from idea to built addon |
-| `/modify-mod` | Modify or extend an existing mod project |
-
-Claude will:
-
-1. **Assess complexity** — simple mods are built in one pass; large mods (e.g., a DayZ-style overhaul) get broken into phases with a plan you approve before any code is written
-2. **Research** the Enfusion API (8,693 indexed classes) and the Arma Reforger wiki (250+ guides and tutorials) to find the right approach
-3. **Scaffold** the full addon — `.gproj`, scripts, prefabs, configs, UI layouts
-4. **Launch Workbench** if it's not already running
-5. **Load the project**, reload scripts, register resources
-6. **Validate and build** the addon
-7. **Enter play mode** so you can test in-game
-
-For complex mods, a `MODPLAN.md` is written to the project root tracking the full vision, completed phases, and what's next — so any future session can pick up right where the last one left off via `/modify-mod`.
-
-## Tools
-
-### Offline Tools
-
-Work without Workbench running — API search, mod scaffolding, code generation, validation, and building.
-
-| Tool | What it does |
-|------|-------------|
-| `api_search` | Search 8,693 Enfusion/Arma Reforger API classes and methods |
-| `wiki_search` | Search 250+ tutorials and guides from the Enfusion engine docs and BI Community Wiki |
-| `project_browse` | List files in a mod project directory |
-| `project_read` | Read any project file |
-| `project_write` | Write or update project files |
-| `mod_create` | Scaffold a complete addon with directory structure and `.gproj` |
-| `script_create` | Generate Enforce Script (`.c`) files — 7 types: component, gamemode, action, entity, manager, modded, basic |
-| `prefab_create` | Generate Entity Template (`.et`) prefabs — 7 types: character, vehicle, weapon, spawnpoint, gamemode, interactive, generic |
-| `layout_create` | Generate UI layout (`.layout`) files — 5 types: hud, menu, dialog, list, custom |
-| `config_create` | Generate config files — factions, missions, entity catalogs, editor placeables |
-| `server_config` | Generate dedicated server config for local testing |
-| `mod_validate` | Validate project structure, scripts, prefabs, configs, and naming |
-| `mod_build` | Build the addon using the Workbench CLI |
-
-### Live Workbench Tools
-
-Control a running Workbench instance over TCP. Requires the handler scripts installed (see setup above).
-
-| Tool | What it does |
-|------|-------------|
-| `wb_launch` | Start Workbench if not running, wait for NET API |
-| `wb_connect` | Test connection to Workbench |
-| `wb_state` | Full state snapshot — mode, world, entity count, selection |
-| `wb_play` | Switch to game mode (Play in Editor) |
-| `wb_stop` | Return to edit mode |
-| `wb_save` | Save the current world |
-| `wb_undo_redo` | Undo or redo the last action |
-| `wb_open_resource` | Open a resource in its editor |
-| `wb_reload` | Reload scripts or plugins without restarting |
-| `wb_execute_action` | Run any Workbench menu action by path |
-| `wb_entity_create` | Create entity from prefab at a position |
-| `wb_entity_delete` | Delete entity by name |
-| `wb_entity_list` | List and search entities in the world |
-| `wb_entity_inspect` | Get entity details — properties, components, children |
-| `wb_entity_modify` | Move, rotate, rename, reparent, set properties |
-| `wb_entity_select` | Select, deselect, clear, get current selection |
-| `wb_component` | Add, remove, list entity components |
-| `wb_terrain` | Query terrain height and world bounds |
-| `wb_layers` | Create, delete, rename layers, set visibility/active |
-| `wb_resources` | Register resources, rebuild database |
-| `wb_prefabs` | Create templates, save, GUID lookup |
-| `wb_clipboard` | Copy, cut, paste, duplicate entities |
-| `wb_script_editor` | Read/write lines in the open script file |
-| `wb_localization` | String table CRUD for localization |
-| `wb_projects` | List loaded projects, open `.gproj` files |
-| `wb_validate` | Material and texture validation |
-
-### Mod Patterns
-
-10 built-in templates for `mod_create`:
-
-`game-mode` `custom-faction` `custom-action` `spawn-system` `custom-component` `modded-behavior` `admin-tool` `custom-vehicle` `weapon-reskin` `hud-widget`
-
-### MCP Resources
-
-| URI | Description |
-|-----|-------------|
-| `enfusion://class/{className}` | Full class docs with inheritance, methods, ancestors/descendants |
-| `enfusion://pattern/{patternName}` | Mod pattern definition with all templates |
-| `enfusion://group/{groupName}` | API group with class list |
-
-## Configuration
-
-All optional. Sensible defaults are used when nothing is set.
-
-| Environment Variable | Description | Default |
-|---------------------|-------------|---------|
-| `ENFUSION_PROJECT_PATH` | Default mod output directory | `~/Documents/My Games/ArmaReforgerWorkbench/addons` |
-| `ENFUSION_WORKBENCH_PATH` | Path to Arma Reforger Tools | `C:\Program Files (x86)\Steam\steamapps\common\Arma Reforger Tools` |
-| `ENFUSION_WORKBENCH_HOST` | NET API host | `127.0.0.1` |
-| `ENFUSION_WORKBENCH_PORT` | NET API port | `5775` |
-
-Config can also be loaded from `~/.enfusion-mcp/config.json`. Environment variables take priority.
-
-## Requirements
-
-- **Node.js 20+**
-- **Arma Reforger Tools** (Steam) — needed for `mod_build` and all `wb_*` tools
-
-## Development
-
-```bash
-git clone https://github.com/Articulated7/enfusion-mcp.git
-cd enfusion-mcp
-npm install
-npm run scrape   # Build API index from Workbench docs
-npm run build
-npm test         # 163 tests
-```
-
-## Documentation
-
-Full documentation is on the [GitHub Wiki](https://github.com/Articulated7/enfusion-mcp/wiki).
-
-## License
-
-MIT
+# enfusion-mcp
+
+MCP server for Arma Reforger modding. Describe what you want to build, and Claude handles everything — API research, code generation, project scaffolding, Workbench control, and in-editor testing. Zero modding experience required.
+
+## Install
+
+### Claude Code (Windows)
+
+```bash
+claude mcp add --scope user enfusion-mcp -- cmd /c npx -y enfusion-mcp
+```
+
+### Claude Code (macOS / Linux)
+
+```bash
+claude mcp add --scope user enfusion-mcp -- npx -y enfusion-mcp
+```
+
+Restart Claude Code. Verify with `/mcp`.
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+**Windows:**
+
+```json
+{
+  "mcpServers": {
+    "enfusion-mcp": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "enfusion-mcp"]
+    }
+  }
+}
+```
+
+**macOS / Linux:**
+
+```json
+{
+  "mcpServers": {
+    "enfusion-mcp": {
+      "command": "npx",
+      "args": ["-y", "enfusion-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Verify with `/mcp`.
+
+### Workbench Plugin
+
+The live Workbench tools (`wb_*`) require handler scripts running inside Workbench. These ship with the package in `mod/Scripts/WorkbenchGame/EnfusionMCP/` and are installed automatically when Claude launches Workbench via `wb_launch`.
+
+## Usage
+
+Just ask Claude to make a mod:
+
+- *"Create a HUD widget that shows player health and stamina"*
+- *"Make a zombie survival game mode with wave spawning"*
+- *"Create a custom faction called CSAT with desert camo soldiers"*
+- *"Add an interactive object that heals the player when used"*
+- *"Override the damage system to add armor mechanics"*
+
+Or use the guided prompts for structured workflows:
+
+| Prompt | Description |
+|--------|-------------|
+| `/create-mod` | Full guided mod creation — from idea to built addon |
+| `/modify-mod` | Modify or extend an existing mod project |
+
+Claude will:
+
+1. **Assess complexity** — simple mods are built in one pass; large mods (e.g., a DayZ-style overhaul) get broken into phases with a plan you approve before any code is written
+2. **Research** the Enfusion API (8,693 indexed classes), the Arma Reforger wiki (250+ guides), and base game assets (read directly from `.pak` archives) to find the right approach
+3. **Scaffold** the full addon — `.gproj`, scripts, prefabs, configs, UI layouts
+4. **Launch Workbench** if it's not already running
+5. **Load the project**, reload scripts, register resources
+6. **Validate and build** the addon
+7. **Enter play mode** so you can test in-game
+
+For complex mods, a `MODPLAN.md` is written to the project root tracking the full vision, completed phases, and what's next — so any future session can pick up right where the last one left off via `/modify-mod`.
+
+## Tools
+
+### Offline Tools
+
+Work without Workbench running — API search, mod scaffolding, code generation, validation, and building.
+
+| Tool | What it does |
+|------|-------------|
+| `api_search` | Search 8,693 Enfusion/Arma Reforger API classes and methods |
+| `wiki_search` | Search 250+ tutorials and guides from the Enfusion engine docs and BI Community Wiki |
+| `game_browse` | Browse base game files — loose files and `.pak` archives transparently |
+| `game_read` | Read base game files — scripts, prefabs, configs from loose files or `.pak` |
+| `asset_search` | Search game assets by name across loose files and `.pak` archives |
+| `project_browse` | List files in a mod project directory |
+| `project_read` | Read any project file |
+| `project_write` | Write or update project files |
+| `mod_create` | Scaffold a complete addon with directory structure and `.gproj` |
+| `script_create` | Generate Enforce Script (`.c`) files — 7 types: component, gamemode, action, entity, manager, modded, basic |
+| `prefab_create` | Generate Entity Template (`.et`) prefabs — 7 types: character, vehicle, weapon, spawnpoint, gamemode, interactive, generic |
+| `layout_create` | Generate UI layout (`.layout`) files — 5 types: hud, menu, dialog, list, custom |
+| `config_create` | Generate config files — factions, missions, entity catalogs, editor placeables |
+| `server_config` | Generate dedicated server config for local testing |
+| `mod_validate` | Validate project structure, scripts, prefabs, configs, and naming |
+| `mod_build` | Build the addon using the Workbench CLI |
+
+### Live Workbench Tools
+
+Control a running Workbench instance over TCP. Requires the handler scripts installed (see setup above).
+
+| Tool | What it does |
+|------|-------------|
+| `wb_launch` | Start Workbench if not running, wait for NET API |
+| `wb_connect` | Test connection to Workbench |
+| `wb_state` | Full state snapshot — mode, world, entity count, selection |
+| `wb_play` | Switch to game mode (Play in Editor) |
+| `wb_stop` | Return to edit mode |
+| `wb_save` | Save the current world |
+| `wb_undo_redo` | Undo or redo the last action |
+| `wb_open_resource` | Open a resource in its editor |
+| `wb_reload` | Reload scripts or plugins without restarting |
+| `wb_execute_action` | Run any Workbench menu action by path |
+| `wb_entity_create` | Create entity from prefab at a position |
+| `wb_entity_delete` | Delete entity by name |
+| `wb_entity_list` | List and search entities in the world |
+| `wb_entity_inspect` | Get entity details — properties, components, children |
+| `wb_entity_modify` | Move, rotate, rename, reparent, set/clear/get/list properties |
+| `wb_entity_select` | Select, deselect, clear, get current selection |
+| `wb_component` | Add, remove, list entity components |
+| `wb_terrain` | Query terrain height and world bounds |
+| `wb_layers` | Create, delete, rename layers, set visibility/active |
+| `wb_resources` | Register resources, rebuild database |
+| `wb_prefabs` | Create templates, save, GUID lookup |
+| `wb_clipboard` | Copy, cut, paste, duplicate entities |
+| `wb_script_editor` | Read/write lines in the open script file |
+| `wb_localization` | String table CRUD for localization |
+| `wb_projects` | List loaded projects, open `.gproj` files |
+| `wb_validate` | Material and texture validation |
+
+### Mod Patterns
+
+10 built-in templates for `mod_create`:
+
+`game-mode` `custom-faction` `custom-action` `spawn-system` `custom-component` `modded-behavior` `admin-tool` `custom-vehicle` `weapon-reskin` `hud-widget`
+
+### MCP Resources
+
+| URI | Description |
+|-----|-------------|
+| `enfusion://class/{className}` | Full class docs with inheritance, methods, ancestors/descendants |
+| `enfusion://pattern/{patternName}` | Mod pattern definition with all templates |
+| `enfusion://group/{groupName}` | API group with class list |
+
+## Configuration
+
+All optional. Sensible defaults are used when nothing is set.
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `ENFUSION_PROJECT_PATH` | Default mod output directory | `~/Documents/My Games/ArmaReforgerWorkbench/addons` |
+| `ENFUSION_WORKBENCH_PATH` | Path to Arma Reforger Tools | `C:\Program Files (x86)\Steam\steamapps\common\Arma Reforger Tools` |
+| `ENFUSION_GAME_PATH` | Path to the Arma Reforger game install (used as CWD when launching Workbench so base-game addons resolve correctly) | Auto-detected from sibling of `ENFUSION_WORKBENCH_PATH` |
+| `ENFUSION_WORKBENCH_HOST` | NET API host | `127.0.0.1` |
+| `ENFUSION_WORKBENCH_PORT` | NET API port | `5775` |
+
+Config can also be loaded from `~/.enfusion-mcp/config.json`. Environment variables take priority.
+
+## Requirements
+
+- **Node.js 20+**
+- **Arma Reforger Tools** (Steam) — needed for `mod_build` and all `wb_*` tools
+
+## Development
+
+```bash
+git clone https://github.com/Articulated7/enfusion-mcp.git
+cd enfusion-mcp
+npm install
+npm run scrape   # Build API index from Workbench docs
+npm run build
+npm test         # 187 tests
+```
+
+## Documentation
+
+Full documentation is on the [GitHub Wiki](https://github.com/Articulated7/enfusion-mcp/wiki).
+
+## License
+
+MIT

package/dist/pak/reader.d.ts

@@ -0,0 +1,28 @@
+export interface PakFileEntry {
+    kind: "file";
+    name: string;
+    /** Byte offset of this file's data within the DATA chunk payload */
+    offset: number;
+    compressedLen: number;
+    decompressedLen: number;
+    compressed: boolean;
+}
+export interface PakDirEntry {
+    kind: "dir";
+    name: string;
+    children: Map<string, PakDirEntry | PakFileEntry>;
+}
+export interface PakIndex {
+    root: PakDirEntry;
+    /** Absolute byte position in the .pak file where the DATA payload starts */
+    dataStart: number;
+    /** Path to the .pak file on disk */
+    pakPath: string;
+}
+/**
+ * Parse a .pak file's metadata without reading the DATA payload.
+ * Reads chunk headers to locate the DATA and FILE sections, then parses
+ * the FILE chunk's recursive entry tree into an in-memory directory structure.
+ */
+export declare function parsePakIndex(pakPath: string): PakIndex;
+//# sourceMappingURL=reader.d.ts.map

package/dist/pak/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/pak/reader.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,WAAW,CAAC;IAClB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAYD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CA+DvD"}

package/dist/pak/reader.js

@@ -0,0 +1,141 @@
+import { openSync, readSync, closeSync, fstatSync } from "node:fs";
+import { logger } from "../utils/logger.js";
+// ── Chunk magic constants ────────────────────────────────────────────────────
+const MAGIC_FORM = 0x464f524d; // "FORM"
+const MAGIC_PAC1 = 0x50414331; // "PAC1"
+const MAGIC_HEAD = 0x48454144; // "HEAD"
+const MAGIC_DATA = 0x44415441; // "DATA"
+const MAGIC_FILE = 0x46494c45; // "FILE"
+// ── Parser ───────────────────────────────────────────────────────────────────
+/**
+ * Parse a .pak file's metadata without reading the DATA payload.
+ * Reads chunk headers to locate the DATA and FILE sections, then parses
+ * the FILE chunk's recursive entry tree into an in-memory directory structure.
+ */
+export function parsePakIndex(pakPath) {
+    const fd = openSync(pakPath, "r");
+    try {
+        const fileSize = fstatSync(fd).size;
+        // ── FORM chunk ───────────────────────────────────────────────────────
+        // Layout: "FORM" (4B) + u32BE size + "PAC1" (4B) = 12 bytes
+        const formBuf = readAt(fd, 0, 12);
+        const formMagic = formBuf.readUInt32BE(0);
+        if (formMagic !== MAGIC_FORM) {
+            throw new Error(`Not a PAK file: missing FORM header (got 0x${formMagic.toString(16)})`);
+        }
+        const pac1 = formBuf.readUInt32BE(8);
+        if (pac1 !== MAGIC_PAC1) {
+            throw new Error(`Not a PAK file: expected PAC1 identifier (got 0x${pac1.toString(16)})`);
+        }
+        // ── Walk chunks after FORM header ────────────────────────────────────
+        // Chunks start at offset 12 (after FORM header).
+        // Each chunk: magic (4B BE) + size (4B BE) + payload (size bytes).
+        let pos = 12;
+        let dataStart = -1;
+        let fileChunkOffset = -1;
+        let fileChunkLen = 0;
+        while (pos + 8 <= fileSize) {
+            const hdr = readAt(fd, pos, 8);
+            const magic = hdr.readUInt32BE(0);
+            const chunkLen = hdr.readUInt32BE(4);
+            if (magic === MAGIC_HEAD) {
+                // Skip HEAD chunk entirely
+                pos += 8 + chunkLen;
+            }
+            else if (magic === MAGIC_DATA) {
+                // Record where the DATA payload begins (right after its 8-byte header)
+                dataStart = pos + 8;
+                pos += 8 + chunkLen;
+            }
+            else if (magic === MAGIC_FILE) {
+                fileChunkOffset = pos + 8;
+                fileChunkLen = chunkLen;
+                break; // FILE is the last chunk we care about
+            }
+            else {
+                // Unknown chunk — skip it
+                logger.debug(`PAK unknown chunk 0x${magic.toString(16)} at offset ${pos}, skipping`);
+                pos += 8 + chunkLen;
+            }
+        }
+        if (dataStart < 0) {
+            throw new Error("PAK file missing DATA chunk");
+        }
+        if (fileChunkOffset < 0) {
+            throw new Error("PAK file missing FILE chunk");
+        }
+        // ── Parse FILE chunk ─────────────────────────────────────────────────
+        const fileBuf = readAt(fd, fileChunkOffset, fileChunkLen);
+        const root = parseFileTree(fileBuf);
+        return { root, dataStart, pakPath };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+// ── FILE tree parser ─────────────────────────────────────────────────────────
+/**
+ * Parse the recursive file entry tree from the FILE chunk payload.
+ * Uses an iterative approach with an explicit stack to avoid deep recursion.
+ */
+function parseFileTree(buf) {
+    const state = { offset: 0 };
+    // The FILE chunk contains a single root entry (always a directory)
+    const root = parseEntry(buf, state);
+    if (root.kind !== "dir") {
+        throw new Error("PAK FILE chunk root entry is not a directory");
+    }
+    return root;
+}
+function parseEntry(buf, state) {
+    const entryKind = buf.readUInt8(state.offset);
+    state.offset += 1;
+    const nameLen = buf.readUInt8(state.offset);
+    state.offset += 1;
+    const name = buf.toString("utf8", state.offset, state.offset + nameLen);
+    state.offset += nameLen;
+    if (entryKind === 0) {
+        // Directory
+        const childCount = buf.readUInt32LE(state.offset);
+        state.offset += 4;
+        const children = new Map();
+        for (let i = 0; i < childCount; i++) {
+            const child = parseEntry(buf, state);
+            children.set(child.name, child);
+        }
+        return { kind: "dir", name, children };
+    }
+    else {
+        // File
+        const offset = buf.readUInt32LE(state.offset);
+        state.offset += 4;
+        const compressedLen = buf.readUInt32LE(state.offset);
+        state.offset += 4;
+        const decompressedLen = buf.readUInt32LE(state.offset);
+        state.offset += 4;
+        // Skip unknown (u32LE) + unk2 (u16LE)
+        state.offset += 6;
+        const compressed = buf.readUInt8(state.offset) !== 0;
+        state.offset += 1;
+        // Skip compression_level (u8) + timestamp (u32LE)
+        state.offset += 5;
+        return {
+            kind: "file",
+            name,
+            offset,
+            compressedLen,
+            decompressedLen,
+            compressed,
+        };
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function readAt(fd, position, length) {
+    const buf = Buffer.alloc(length);
+    const bytesRead = readSync(fd, buf, 0, length, position);
+    if (bytesRead < length) {
+        throw new Error(`Unexpected EOF: wanted ${length} bytes at offset ${position}, got ${bytesRead}`);
+    }
+    return buf;
+}
+//# sourceMappingURL=reader.js.map

package/dist/pak/reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../src/pak/reader.ts"],"names":[],"mappings":"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"}

package/dist/pak/vfs.d.ts

@@ -0,0 +1,56 @@
+export interface VfsEntry {
+    name: string;
+    isDirectory: boolean;
+    /** Decompressed size for files, 0 for directories */
+    size: number;
+}
+/**
+ * Virtual filesystem that merges all .pak files in the game's addons/ directory
+ * into a single unified file tree. Supports directory listing, file existence
+ * checks, and on-demand file reading with automatic zlib decompression.
+ *
+ * Instantiated lazily as a singleton and cached for the session lifetime.
+ */
+export declare class PakVirtualFS {
+    private static instance;
+    private static instanceGamePath;
+    /** Flat lookup: normalized virtual path → file reference */
+    private fileIndex;
+    /** Merged directory tree for browsing */
+    private root;
+    /**
+     * Get or create the singleton VFS for the given game path.
+     * Returns null if no .pak files are found.
+     */
+    static get(gamePath: string): PakVirtualFS | null;
+    private constructor();
+    /**
+     * List entries in a virtual directory.
+     * Path uses forward slashes, no leading slash (e.g., "Prefabs/Weapons").
+     * Empty string = root.
+     */
+    listDir(virtualPath: string): VfsEntry[];
+    /** Check if a path exists (file or directory). */
+    exists(virtualPath: string): boolean;
+    /**
+     * Read a file's raw bytes from the pak archive.
+     * Opens the .pak, seeks to the correct offset, reads, decompresses if needed.
+     */
+    readFile(virtualPath: string): Buffer;
+    /** Read a file as UTF-8 text. */
+    readTextFile(virtualPath: string): string;
+    /** Get decompressed file size without reading/inflating. Returns -1 if not found. */
+    fileSize(virtualPath: string): number;
+    /** Get all file paths in the VFS (for building the asset search index). */
+    allFilePaths(): string[];
+    /** Get the number of indexed files. */
+    get fileCount(): number;
+    /**
+     * Merge a parsed pak tree into the unified directory tree.
+     * Returns the number of file entries added.
+     */
+    private mergeTree;
+    /** Resolve a virtual path to a directory entry, or null if not found. */
+    private resolveDir;
+}
+//# sourceMappingURL=vfs.d.ts.map

package/dist/pak/vfs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfs.d.ts","sourceRoot":"","sources":["../../src/pak/vfs.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;CACd;AAUD;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA6B;IACpD,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAuB;IAEtD,4DAA4D;IAC5D,OAAO,CAAC,SAAS,CAA8B;IAC/C,yCAAyC;IACzC,OAAO,CAAC,IAAI,CAA+D;IAE3E;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IA0BjD,OAAO;IAwBP;;;;OAIG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,EAAE;IAexC,kDAAkD;IAClD,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAMpC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IA8BrC,iCAAiC;IACjC,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAIzC,qFAAqF;IACrF,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAMrC,2EAA2E;IAC3E,YAAY,IAAI,MAAM,EAAE;IAIxB,uCAAuC;IACvC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAID;;;OAGG;IACH,OAAO,CAAC,SAAS;IAqCjB,yEAAyE;IACzE,OAAO,CAAC,UAAU;CAenB"}