Download the PHP package manacost-labs/hearthstone-deckstrings without Composer

Hearthstone Deckstrings

A dependency-free Hearthstone deckstring backend library for JavaScript, TypeScript, PHP, Python, and .NET. All four implementations share one public contract and the same golden fixtures, including sideboards and full clipboard exports.

Release status: 1.0.0 is the first stable cross-language release and is publicly available on npm, Packagist, PyPI, and NuGet. The install commands below are the supported production path.

Install

Package versions advance together. Version 1.0.0 defines the first stable cross-language API.

What the library owns

• version 1 deckstring encoding and decoding;
• Wild, Standard, Classic, and Twist formats;
• heroes, cards, and sideboards;
• deterministic canonical ordering;
• structured validation and stable error codes;
• parsing and formatting complete Hearthstone clipboard exports;
• defensive limits for untrusted input.

The core does not download card data, make network requests, or decide whether a deck is legal for a patch. Card names and costs can be added at the edge with an optional resolver callback.

Shared model

• cards entries are [dbfId, count];
• sideboardCards entries are [dbfId, count, ownerDbfId];
• heroes and cards are sorted by DBF ID;
• sideboard cards are sorted by owner and then DBF ID;
• duplicate heroes, cards, and sideboard (ownerDbfId, dbfId) pairs are invalid.

The normative model is spec/deck.schema.json, and the wire/error/export contract is documented in spec/README.md.

JavaScript / TypeScript

The npm package includes ESM, CommonJS, browser ESM, UMD, and bundled TypeScript declarations.

PHP

Python

The Python distribution is typed and ships a py.typed marker.

C# / .NET

NuGet releases include XML documentation, portable PDBs, Source Link metadata, and a separate .snupkg symbol package.

Validation and errors

validate/Validate returns ordinary user-input failures and does not throw:

Encoding, decoding, canonicalization, and export parsing raise an idiomatic language exception. Match its stable machine-readable code, not the human-readable message. See docs/API.md for language-specific names and the complete code list.

Card display resolver

formatExport/format_export accepts an optional callback from DBF ID to { name, cost? } (or the native equivalent). The callback may return null for an unknown card. Names must be non-blank single-line strings, and costs must be non-negative integers no larger than 2,147,483,647. The resolver is presentation-only and never changes the encoded deckstring.

Compatibility promise

Every implementation reads fixtures/deckstrings.json, fixtures/exports.json directly. A behavior change is not accepted until the shared contract and all language jobs agree. Legacy deckstrings without a sideboard marker remain supported; encoders always produce canonical output.

Development

See the release process, the roadmap.

Credits and license

This is an independent Manacost Labs repository whose complete Git history is derived from and preserves attribution to HearthSim/hearthstone-deckstrings. Manacost Labs maintains the multi-language contract, native backend implementations, packaging, and release automation. Repository migration details are recorded in docs/REPOSITORY_MIGRATION.md.

Licensed under the ISC License.