GW2.ChatCode (ex_gw2 v0.1.0)

Copy Markdown View Source

Encodes and decodes Guild Wars 2 chat codes.

Chat codes are the strings Guild Wars 2 places in chat when you link game data, such as items or wardrobe templates. They are wrapped in the familiar [&...] format and contain Base64-encoded binary payloads.

This module provides the public entry point for converting between those chat code strings and typed Elixir structs.

Supported chat codes

The library currently supports:

Guild Wars 2 has other chat code types, such as coins, maps, skills, traits, recipes, outfits, build templates, achievements, and travel templates. Those types are not implemented yet. Decoding an unsupported chat code type returns an error tuple.

Encoding

Build one of the supported structs and pass it to encode/1:

iex> GW2.ChatCode.encode(%GW2.ChatCode.Item{id: 43766, quantity: 9})
{:ok, "[&Agn2qgAA]"}

Decoding

Pass a chat code string to decode/1 to get a typed struct back:

iex> GW2.ChatCode.decode("[&Agn2qgAA]")
{:ok, %GW2.ChatCode.Item{id: 43766, quantity: 9, skin_id: nil, upgrade_ids: []}}

Unknown, malformed, or unsupported chat codes return an error tuple instead of raising.

Common error reasons are:

  • :invalid_code for invalid wrappers, Base64, unsupported chat code types, or malformed payloads.
  • :quantity_out_of_range when encoding an item quantity outside 0..255.
  • :invalid_id when encoding an id that cannot fit in the chat code format.
  • :invalid_dyes when encoding a wardrobe skin with an invalid dye list.

Summary

Types

parsed_struct()

A supported decoded chat code struct.

Functions

decode(code)

Decodes a chat code string into a structured value.

encode(item)

Encodes a supported chat code struct into a Guild Wars 2 chat code string.

Types

parsed_struct()

@type parsed_struct() :: GW2.ChatCode.Item.t() | GW2.ChatCode.WardrobeTemplate.t()

A supported decoded chat code struct.

Functions

decode(code)

@spec decode(binary()) :: {:ok, parsed_struct()} | {:error, atom()}

Decodes a chat code string into a structured value.

Returns {:ok, struct} for supported chat code types. Invalid Base64, missing wrappers, unknown chat code types, and malformed payloads return an error tuple.

Examples

iex> GW2.ChatCode.decode("[&AgGqtgAA]")
{:ok, %GW2.ChatCode.Item{id: 46762, quantity: 1, skin_id: nil, upgrade_ids: []}}

iex> GW2.ChatCode.decode("not a chat code")
{:error, :invalid_code}

encode(item)

@spec encode(GW2.ChatCode.Item.t()) :: {:ok, binary()} | {:error, atom()}
@spec encode(GW2.ChatCode.WardrobeTemplate.t()) :: {:ok, binary()} | {:error, atom()}
@spec encode(parsed_struct()) :: {:ok, binary()} | {:error, atom()}

Encodes a supported chat code struct into a Guild Wars 2 chat code string.

Returns {:ok, code} when the struct can be encoded, or {:error, reason} when one of its fields cannot be represented in a chat code payload.

Examples

iex> GW2.ChatCode.encode(%GW2.ChatCode.Item{id: 46762})
{:ok, "[&AgGqtgAA]"}

iex> GW2.ChatCode.encode(%GW2.ChatCode.Item{id: 1, quantity: 256})
{:error, :quantity_out_of_range}