@mks.haro/axicode

Compact binary encoder/decoder for Guild Wars 2 builds and team compositions. Produces shareable strings in the AxiCode format used by AxiForge.

Supports two code types:

• Build codes — a single character build: <AxiForge:Berserker:5p<)jKY1/i5qHKz...>
• Comp codes — a full team composition with multiple builds and party lines: <AxiForge:Comp:eJyrVipTsjLUUcpT...>

Installation

npm install @mks.haro/axicode

Usage

const {
  encodeShareCode, decodeShareCode, isValidShareCode,
  encodeCompCode, decodeCompCode, isValidCompCode,
} = require("@mks.haro/axicode");

Encoding a build

Pass a build object to encodeShareCode to get a share code string:

const code = encodeShareCode({
  profession: "Warrior",
  gameMode: "pve",
  specializations: [
    {
      id: 4, name: "Strength", elite: false,
      majorChoices: { 1: 1444, 2: 1449, 3: 1437 },
      majorTraitsByTier: {
        1: [{ id: 1444 }, { id: 1447 }, { id: 2000 }],
        2: [{ id: 1449 }, { id: 1448 }, { id: 1453 }],
        3: [{ id: 1437 }, { id: 1440 }, { id: 1454 }],
      },
    },
    // ... two more specializations
  ],
  skills: {
    heal: { id: 14402 },
    utility: [{ id: 14404 }, { id: 14410 }, { id: 14405 }],
    elite: { id: 14355 },
  },
  equipment: {
    statPackage: "Berserker's",
    weapons: { mainhand1: "greatsword", offhand1: "", mainhand2: "axe", offhand2: "" },
    runes: { head: "24836", shoulders: "24836", chest: "24836", hands: "24836", legs: "24836", feet: "24836" },
    sigils: { mainhand1: ["24615", "24868"], offhand1: [], mainhand2: ["24615"], offhand2: [] },
    relic: "Relic of the Thief",
    food: "Bowl of Sweet and Spicy Butternut Squash Soup",
    utility: "Superior Sharpening Stone",
    enrichment: "",
    infusions: {
      head: "49432", shoulders: "49432", chest: "49432", hands: "49432", legs: "49432", feet: "49432",
      back: ["49432", "49432"], ring1: ["49432", "49432", "49432"], ring2: ["49432", "49432", "49432"],
      accessory1: "49432", accessory2: "49432",
      mainhand1: ["49432", "49432"], offhand1: [], mainhand2: ["49432", "49432"], offhand2: [],
    },
  },
  // Profession-specific fields (include as needed)
  selectedLegends: ["", ""],           // Revenant
  selectedPets: { terrestrial1: 0, terrestrial2: 0 }, // Ranger
  activeAttunement: "",                // Elementalist
  activeKit: 0,                        // Engineer
  activeWeaponSet: 1,                  // Warrior
  antiquaryArtifacts: { f2: 0, f3: 0, f4: 0 }, // Thief (Antiquary)
});

console.log(code);
// => "<AxiForge:Berserker:x1y2z3...>"

Decoding a build

const build = decodeShareCode("<AxiForge:Berserker:x1y2z3...>");

console.log(build.profession);              // "Warrior"
console.log(build.gameMode);                // "pve"
console.log(build.equipment.statPackage);   // "Berserker's"
console.log(build.skills.healId);           // 14402
console.log(build.equipment.weapons);       // { mainhand1: "greatsword", ... }

Validating a share code

isValidShareCode("<AxiForge:Berserker:x1y2z3...>"); // true
isValidShareCode("not a share code");                // false
isValidShareCode("[&DQYlPSkvMBc=]");                 // false (GW2 chat link, not AxiCode)

API

encodeShareCode(build) → string

Encodes a build object into an AxiCode share string. The output format is <AxiForge:{label}:{payload}>, where the label is the elite specialization name (or profession name for core builds).

decodeShareCode(code) → object

Decodes an AxiCode share string back into a build object. Throws if the format is invalid or the payload is corrupted.

Returned object shape:

| Field | Type | Description | |-------|------|-------------| | profession | string | Profession name (e.g. "Warrior") | | gameMode | string | "pve", "pvp", or "wvw" | | specializations | array | Three specs, each with id and traitChoices (1=top, 2=mid, 3=bottom, 0=none) | | skills | object | { healId, utilityIds: [3], eliteId } | | underwaterSkills | object | Same shape as skills, zeroed if unused | | equipment | object | Stat package, weapons, runes, sigils, relic, food, utility, enrichment, infusions | | selectedLegends | array | Revenant legend strings | | selectedPets | object | Ranger pet IDs | | activeAttunement | string | Elementalist attunement | | activeKit | number | Engineer active kit skill ID | | activeWeaponSet | number | Warrior active weapon set (1 or 2) | | antiquaryArtifacts | object | Thief Antiquary artifact skill IDs |

isValidShareCode(text) → boolean

Returns true if the string matches the AxiCode build code wrapper format.

Encoding a comp

Pass a comp object and a map of builds to encodeCompCode:

const compCode = encodeCompCode(
  {
    name: "Raid Squad",
    gameMode: "pve",
    partyLines: [
      { id: "p1", capacity: 5, slots: ["warrior1", "warrior1", "warrior1", "warrior1", "warrior1"] },
      { id: "p2", capacity: 5, slots: ["warrior1", "warrior1", "warrior1", "warrior1", "warrior1"] },
    ],
  },
  { warrior1: warriorBuild },
);

console.log(compCode);
// => "<AxiForge:Comp:eJyrVipTsjLUUcpTslIKSsxMUQguLE1MUdJRSgcKFJSlAllJSlbRSqYFNppZ3pGG-pmmhR7eVe5BpbkZaubhQXHuTnbVsWWZcV6lauXmFdllRj5mtkqxOkoFQF3VSslKVqY6SsVAtoEOFMbW6uAQj60FAD-KJ1g>"

Builds are deduplicated — identical builds used in multiple slots are stored only once.

Decoding a comp

const comp = decodeCompCode("<AxiForge:Comp:eJyrVipTsjLUUcpT...>");

console.log(comp.name);       // "Raid Squad"
console.log(comp.gameMode);   // "pve"
console.log(comp.builds);     // Array of decoded build objects (deduplicated)
console.log(comp.partyLines); // [{ capacity: 5, slots: [build, build, ...] }, ...]

Validating a comp code

isValidCompCode("<AxiForge:Comp:eJyrVipTsjLU...>"); // true
isValidCompCode("<AxiForge:Berserker:abc123>");      // false (build code, not comp)
isValidCompCode("not a comp code");                  // false

encodeCompCode(comp, builds) → string | null

Encodes a team composition into a comp code string. Returns null if any referenced build is missing from the builds map or fails to encode.

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | comp.name | string | Comp name (max 140 characters) | | comp.gameMode | string \| null | "pve", "wvw", or null | | comp.partyLines | array | Party lines, each with capacity (number) and slots (array of build IDs) | | builds | object | Map of build ID → build object (same shape as encodeShareCode input) |

decodeCompCode(code) → object | null

Decodes a comp code string back into a comp object. Returns null if the format is invalid or the payload is corrupted.

Returned object shape:

| Field | Type | Description | |-------|------|-------------| | name | string | Comp name | | gameMode | string \| null | "pve", "wvw", or null | | builds | array | Deduplicated array of decoded build objects | | partyLines | array | Party lines, each with capacity (number) and slots (array of build objects) | | failedBuildCount | number | Number of builds that failed to decode (0 if all succeeded) |

isValidCompCode(text) → boolean

Returns true if the string matches the <AxiForge:Comp:...> wrapper format.

Supported Values

Professions: Guardian, Warrior, Engineer, Ranger, Thief, Elementalist, Mesmer, Necromancer, Revenant

Weapons: axe, dagger, mace, pistol, sword, scepter, focus, shield, torch, warhorn, greatsword, hammer, longbow, rifle, shortbow, staff, harpoon, spear, trident

Stat combos: Berserker's, Marauder's, Assassin's, Valkyrie, Dragon's, Viper's, Grieving, Sinister, Dire, Rabid, Carrion, Trailblazer's, Knight's, Soldier's, Cleric's, Minstrel's, Harrier's, Ritualist's, Seraph, Zealot's, Celestial

Game modes: pve, pvp, wvw

Format Details

Build codes use compact binary encoding with bit-level packing and Z85 encoding for the text payload. The format is <AxiForge:{label}:{payload}>, where the label is the elite specialization name (or profession name for core builds). Flags conditionally include optional sections (offhands, second weapon set, underwater, profession-specific data, per-slot runes/infusions), keeping simple builds small while supporting full equipment detail.

Comp codes use the format <AxiForge:Comp:{payload}>. The payload is a JSON schema (containing the comp name, game mode, party layout, and embedded build payloads) compressed with pako (deflate) and encoded as base64url. Identical builds are deduplicated by payload to minimize size.

License

MIT