@poe2-toolkit/ggpk 0.1.0

package/dist/statDescriptions.js

@@ -0,0 +1,192 @@
+/**
+ * StatDescriptions engine — renders GGG's numeric `(stat_id, value)` pairs into
+ * human-readable text, using GGG's own `stat_descriptions.csd` straight from the
+ * GGPK. Despite the `.csd` extension the file is plain UTF-16 text, not compiled
+ * binary. Shared across domains: passive nodes, item mods and gem stats all
+ * render through it.
+ *
+ * File format (one block per description):
+ *
+ * ```
+ *   description
+ *   \t<N> <stat_id_1> ... <stat_id_N>
+ *   \t<lineCount>
+ *   \t\t<cond_1> ... <cond_N> "text with {0} {1}" [handler index]...
+ *   \tlang "French"          <- other languages follow; English is read here
+ * ```
+ *
+ * Every stat id is indexed to the block that renders it (a multi-stat block is
+ * indexed under each of its stats); rendering picks the line whose per-stat
+ * conditions all accept the supplied values.
+ */
+/** Parse a condition token: `#` = any, `a|b` = range, `n` = exactly n. */
+function parseCondition(token) {
+    if (token === '#') {
+        return { min: -Infinity, max: Infinity };
+    }
+    if (token.includes('|')) {
+        const [lo, hi] = token.split('|');
+        return {
+            min: lo === '#' ? -Infinity : Number(lo),
+            max: hi === '#' ? Infinity : Number(hi),
+        };
+    }
+    const exact = Number(token);
+    return { min: exact, max: exact };
+}
+/** Split one description line into its conditions, text and handler tokens. */
+function parseDescriptionLine(line) {
+    const trimmed = line.trim();
+    const firstQuote = trimmed.indexOf('"');
+    const lastQuote = trimmed.lastIndexOf('"');
+    const conditions = trimmed.slice(0, firstQuote).trim().split(/\s+/).filter(Boolean).map(parseCondition);
+    const text = trimmed.slice(firstQuote + 1, lastQuote);
+    const handlers = trimmed.slice(lastQuote + 1).trim().split(/\s+/).filter(Boolean);
+    return { conditions, text, handlers };
+}
+/**
+ * Build a per-stat lookup from the raw text of a GGG `stat_descriptions.csd`
+ * file (decoded from UTF-16). The first language block (English) is kept; later
+ * `lang "..."` blocks are skipped by the outer loop, which only resumes on the
+ * next `description` marker.
+ */
+export function buildStatIndex(csd) {
+    // Drop a leading UTF-16 byte-order mark if the decoder left one in.
+    const text = csd.charCodeAt(0) === 0xfeff ? csd.slice(1) : csd;
+    const lines = text.split(/\r\n|\n/);
+    const byStat = new Map();
+    let i = 0;
+    while (i < lines.length) {
+        if (lines[i].trim() !== 'description') {
+            i += 1;
+            continue;
+        }
+        i += 1;
+        // "\t<N> <id1> ... <idN>"
+        const header = lines[i].trim().split(/\s+/);
+        const statCount = Number(header[0]);
+        const statIds = header.slice(1, 1 + statCount);
+        i += 1;
+        // English line count (first language block, before any `lang`).
+        const lineCount = Number(lines[i].trim());
+        i += 1;
+        const variants = [];
+        for (let k = 0; k < lineCount && i < lines.length; k += 1, i += 1) {
+            variants.push(parseDescriptionLine(lines[i]));
+        }
+        for (const id of statIds) {
+            if (!byStat.has(id)) {
+                byStat.set(id, { statIds, variants });
+            }
+        }
+    }
+    return { byStat };
+}
+/** GGG value handlers — transform a raw stat value for display. */
+function applyHandlers(values, handlers) {
+    const out = [...values];
+    for (let h = 0; h + 1 < handlers.length; h += 2) {
+        const name = handlers[h];
+        const index = Number(handlers[h + 1]) - 1;
+        if (index < 0 || index >= out.length) {
+            continue;
+        }
+        switch (name) {
+            case 'negate':
+                out[index] = -out[index];
+                break;
+            case 'divide_by_one_hundred':
+            case 'divide_by_one_hundred_2dp':
+            case 'divide_by_one_hundred_2dp_if_required':
+            case 'per_minute_to_per_second':
+                out[index] /= 100;
+                break;
+            case 'milliseconds_to_seconds':
+            case 'milliseconds_to_seconds_2dp':
+            case 'milliseconds_to_seconds_2dp_if_required':
+            case 'divide_by_one_thousand':
+                out[index] /= 1000;
+                break;
+            case 'divide_by_ten_0dp':
+                out[index] /= 10;
+                break;
+            default:
+                break;
+        }
+    }
+    return out;
+}
+/** Pick the variant whose per-stat conditions all accept the raw values. */
+function selectVariant(variants, rawValues) {
+    for (const variant of variants) {
+        const ok = variant.conditions.every((cond, i) => {
+            const value = rawValues[i] ?? 0;
+            return value >= cond.min && value <= cond.max;
+        });
+        if (ok) {
+            return variant;
+        }
+    }
+    return variants[0] ?? null;
+}
+/** Fill `{0}`, `{0:+d}`, `{0:d}` placeholders with rounded values. */
+function fillTemplate(text, values) {
+    return text.replace(/\{(\d+)(?::([^}]+))?\}/g, (_, index, format) => {
+        const value = values[Number(index)];
+        if (value == null) {
+            return '';
+        }
+        const rounded = Math.round(value);
+        return format === '+d' && rounded >= 0 ? `+${rounded}` : String(rounded);
+    });
+}
+/** Strip PoE bbcode: `[Cold]` -> "Cold", `[AoESkill|AoE]` -> "AoE". */
+function stripBbcode(text) {
+    return text.replace(/\[([^\]]+)\]/g, (_, inner) => {
+        const pipe = inner.lastIndexOf('|');
+        return pipe === -1 ? inner : inner.slice(pipe + 1);
+    });
+}
+/**
+ * Render a full stat block. Each stat resolves to its block; a block may render
+ * several stats together (e.g. min/max added damage), so its placeholders are
+ * filled from whichever of those stats it provides (others default to 0) and all
+ * are marked consumed so the line is not repeated.
+ */
+export function renderBlock(index, statIds, vals) {
+    const valueByStat = new Map(statIds.map((id, i) => [id, vals[i]]));
+    const consumed = new Set();
+    const lines = [];
+    const unresolved = [];
+    for (const statId of statIds) {
+        if (consumed.has(statId)) {
+            continue;
+        }
+        // Some stats are keyed with a "base_" prefix in the description file
+        // (e.g. curse_duration_+% -> base_curse_duration_+%).
+        const record = index.byStat.get(statId) ?? index.byStat.get(`base_${statId}`);
+        if (!record) {
+            unresolved.push(statId);
+            continue;
+        }
+        // The block's stat ids may carry a "base_" prefix the source stat lacks, so
+        // fall back to the prefix-stripped id when reading the value.
+        const valueFor = (id) => valueByStat.get(id) ?? valueByStat.get(id.replace(/^base_/, '')) ?? 0;
+        const rawValues = record.statIds.map(valueFor);
+        const variant = selectVariant(record.variants, rawValues);
+        if (variant?.text) {
+            lines.push(stripBbcode(fillTemplate(variant.text, applyHandlers(rawValues, variant.handlers))));
+        }
+        for (const id of record.statIds) {
+            const stripped = id.replace(/^base_/, '');
+            if (valueByStat.has(id)) {
+                consumed.add(id);
+            }
+            if (valueByStat.has(stripped)) {
+                consumed.add(stripped);
+            }
+        }
+    }
+    return { lines, unresolved };
+}
+//# sourceMappingURL=statDescriptions.js.map

package/dist/statDescriptions.js.map

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@poe2-toolkit/ggpk",
+  "version": "0.1.0",
+  "description": "Access layer for Path of Exile 2's official GGPK / patch server: fetches and decodes game tables and raw files, and decodes GGPK image and stat-description formats. The shared base every PoE2 data extractor builds on.",
+  "keywords": [
+    "path-of-exile",
+    "poe2",
+    "ggpk",
+    "patch-server",
+    "dds",
+    "datc64"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "pathofexile-dat": "^15.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}