From acb97f94c600eb15163ae5df79f6d5c6ae5c9e41 Mon Sep 17 00:00:00 2001 From: thomas-bassett Date: Mon, 2 Feb 2026 13:03:58 +0000 Subject: [PATCH] Document card variants and update example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expand the Card reference to document new and old variants structures (add Detailed Variants table and guidance), reorganize Pokémon card property tables, and add sections for Attacks, Abilities, and Resistances. Update the example JSON to include variants_detailed and refreshed timestamps/pricing fields. Also add /.idea/ to .gitignore. --- .gitignore | 1 + package-lock.json | 17 -- src/content/docs/reference/card.mdx | 302 +++++++++++++++++----------- 3 files changed, 188 insertions(+), 132 deletions(-) diff --git a/.gitignore b/.gitignore index 6240da8..b9863da 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ pnpm-debug.log* # macOS-specific files .DS_Store +/.idea/ diff --git a/package-lock.json b/package-lock.json index 63a0124..96a16bf 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6139,23 +6139,6 @@ "node": ">=4" } }, - "node_modules/prettier": { - "version": "3.5.3", - "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.5.3.tgz", - "integrity": "sha512-QQtaxnoDJeAkDvDKWCLiwIXkTgRhwYDEQCghU9Z6q03iyek/rxRh/2lC3HB7P8sWT2xC/y5JDctPLBIGzHKbhw==", - "license": "MIT", - "optional": true, - "peer": true, - "bin": { - "prettier": "bin/prettier.cjs" - }, - "engines": { - "node": ">=14" - }, - "funding": { - "url": "https://github.com/prettier/prettier?sponsor=1" - } - }, "node_modules/prismjs": { "version": "1.30.0", "resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.30.0.tgz", diff --git a/src/content/docs/reference/card.mdx b/src/content/docs/reference/card.mdx index 68ca55c..97b8636 100644 --- a/src/content/docs/reference/card.mdx +++ b/src/content/docs/reference/card.mdx @@ -2,7 +2,10 @@ title: The Card object description: A comprehensive guide to Pokémon TCG card objects in the API --- -import { Aside, Tabs, TabItem, CardGrid, LinkCard } from '@astrojs/starlight/components' + + + +import {Aside, CardGrid, LinkCard} from '@astrojs/starlight/components' The Card object is the core data structure used throughout the TCGdx API. It represents a single Pokémon Trading Card Game card with all its properties, variants, and associated metadata. @@ -42,6 +45,29 @@ Properties shared by all cards regardless of category: ### Variants +variants has two structures best described as a new and old, the older structure is a selection of booleans +and a newer structure in the form of the detailed variants. new contributions should use the detailed variants structure. + +both are returned in the api currently as two fields, `variants` and `variants_detailed`. the old structure will be converted +to `variants_detailed` during compilation and `variants_detailed` will be converted to `variants` for backwards compatibility. + +the older `variants` structure is planned to be removed in `V3` of the api. + +#### Detailed Variants +New structure: + +| Property | Type | Required | Description | +|-----------------------|-----------------|----------|-------------------------------------------------------------------------| +| `variants[].type` | String | ✅ | Variant type (normal, holo, etc.) | +| `variants[].subtype` | String | ❌ | Variant subtype ( shadowless, unlimited, etc.) | +| `variants[].size` | String | ❌ | Physical size (standard, jumbo, etc.) defaults to standard | +| `variants[].stamps[]` | Array of String | ❌ | Special stamps or marks on the card (1st Edition, Staff, etc.) | +| `variants[].foil` | String | ❌ | Foils type (pokeball,masterball, etc.) | +| `variants[].language` | String | ❌ | if supplied this variants will only be avilable for the selected lang's | + +#### Variants +Old structure to be phased out with `V3`: + | Property | Type | Required | Description | |-------------------------|---------|----------|-------------------------------------| | `variants.normal` | Boolean | ✅ | Standard non-foil version available | @@ -118,20 +144,55 @@ European market data with separate pricing for foil and non-foil variants: Additional properties for Pokémon cards (includes all [common properties](#common-properties)): -| Property | Type | Required | Description | -|---------------|-----------------|----------|--------------------------------------------| -| `category` | "Pokemon" | ✅ | Always "Pokemon" for these cards | -| `dexId` | Array of Number | ❌ | National Pokédex ID(s) of the Pokémon | -| `hp` | Number | ❌ | Hit Points of the Pokémon | -| `types` | Array of String | ❌ | Pokémon types (Fire, Water, Grass, etc.) | -| `evolveFrom` | String | ❌ | Name of the Pokémon it evolves from | -| `description` | String | ❌ | Flavor text description | -| `level` | String | ❌ | Pokémon level (for LV.X cards, level is X) | -| `stage` | String | ❌ | Evolution stage (Basic, Stage1, Stage2) | -| `suffix` | String | ❌ | Additional card identifiers | -| `item` | Object | ❌ | Held item information | -| `item.name` | String | ✅ | Item name | -| `item.effect` | String | ✅ | Item effect description | +| Property | Type | Required | Description | +|------------------|------------------------------------------------|----------|--------------------------------------------| +| `category` | "Pokemon" | ✅ | Always "Pokemon" for these cards | +| `dexId` | Array of Number | ❌ | National Pokédex ID(s) of the Pokémon | +| `hp` | Number | ❌ | Hit Points of the Pokémon | +| `types` | Array of String | ❌ | Pokémon types (Fire, Water, Grass, etc.) | +| `evolveFrom` | String | ❌ | Name of the Pokémon it evolves from | +| `description` | String | ❌ | Flavor text description | +| `level` | String | ❌ | Pokémon level (for LV.X cards, level is X) | +| `stage` | String | ❌ | Evolution stage (Basic, Stage1, Stage2) | +| `suffix` | String | ❌ | Additional card identifiers | +| `item` | Object | ❌ | Held item information | +| `item.name` | String | ✅ | Item name | +| `item.effect` | String | ✅ | Item effect description | +| `attacks` | Array of [Object](#attacks) | ❌ | List of attacks the Pokémon can perform | +| `abilities` | Array of [Object](#abilities) | ❌ | List of abilities the Pokémon has | +| `weaknesses` | Array of [Object](#Resistances and Weaknesses) | ❌ | Pokémon weaknesses | +| `resistances` | Array of [Object](#Resistances and Weaknesses) | ❌ | Pokémon resistances | +| `retreat` | Number | ❌ | Retreat cost in energys | +| `regulationMark` | String | ❌ | Regulation mark for standard play | +| `legal.standard` | Boolean | ❌ | Is the card legal in Standard format | +| `legal.expanded` | Boolean | ❌ | Is the card legal in Expanded format | + +### Attacks +Pokémon cards may have multiple attacks, each with the following structure: + +| Property | Type | Required | Description | +|----------|------------------|----------|--------------------------------------| +| `cost` | Array of String | ❌ | Energy types required for the attack | +| `name` | String | ✅ | Name of the attack | +| `effect` | String | ❌ | Description of the attack effect | +| `damage` | Number or String | ❌ | Damage dealt by the attack | + +### Abilities +Pokémon cards may have abilities with the following structure: + +| Property | Type | Required | Description | +|----------|--------|----------|-----------------------------------------------| +| `name` | String | ✅ | Name of the ability | +| `effect` | String | ✅ | Description of the ability effect | +| `type` | String | ✅ | Type of ability (Poké-POWER, Poké-BODY, etc.) | + +### Resistances and Weaknesses +Both resistances and weaknesses share the same structure: + +| Property | Type | Required | Description | +|----------|--------|----------|-----------------------------------| +| `type` | String | ✅ | Type of resistance or weakness | +| `value` | String | ❌ | Multiplier or value of the effect | ## Trainer Cards @@ -166,106 +227,117 @@ Complete Pokémon card response: ```json { - "category": "Pokemon", - "id": "swsh3-136", - "illustrator": "tetsuya koizumi", - "image": "https://assets.tcgdex.net/en/swsh/swsh3/136", - "localId": "136", - "name": "Furret", - "rarity": "Uncommon", - "set": { - "cardCount": { - "official": 189, - "total": 201 - }, - "id": "swsh3", - "logo": "https://assets.tcgdex.net/en/swsh/swsh3/logo", - "name": "Darkness Ablaze", - "symbol": "https://assets.tcgdex.net/univ/swsh/swsh3/symbol" - }, - "variants": { - "firstEdition": false, - "holo": false, - "normal": true, - "reverse": true, - "wPromo": false - }, - "dexId": [ - 162 - ], - "hp": 110, - "types": [ - "Colorless" - ], - "evolveFrom": "Sentret", - "description": "It makes a nest to suit its long and skinny body. The nest is impossible for other Pokémon to enter.", - "stage": "Stage1", - "attacks": [ - { - "cost": [ - "Colorless" - ], - "name": "Feelin' Fine", - "effect": "Draw 3 cards." - }, - { - "cost": [ - "Colorless" - ], - "name": "Tail Smash", - "effect": "Flip a coin. If tails, this attack does nothing.", - "damage": 90 - } - ], - "weaknesses": [ - { - "type": "Fighting", - "value": "×2" - } - ], - "retreat": 1, - "regulationMark": "D", - "legal": { - "standard": false, - "expanded": true - }, - "updated": "2024-02-04T22:55:32+02:00", - "pricing": { - "cardmarket": { - "updated": "2025-08-05T00:42:15.000Z", - "unit": "EUR", - "avg": 0.08, - "low": 0.02, - "trend": 0.08, - "avg1": 0.03, - "avg7": 0.08, - "avg30": 0.08, - "avg-holo": 0.27, - "low-holo": 0.03, - "trend-holo": 0.21, - "avg1-holo": 0.19, - "avg7-holo": 0.19, - "avg30-holo": 0.26 - }, - "tcgplayer": { - "updated": "2025-08-05T20:07:54.000Z", - "unit": "USD", - "normal": { - "lowPrice": 0.02, - "midPrice": 0.17, - "highPrice": 25.09, - "marketPrice": 0.09, - "directLowPrice": 0.04 - }, - "reverse": { - "lowPrice": 0.09, - "midPrice": 0.26, - "highPrice": 5.17, - "marketPrice": 0.23, - "directLowPrice": 0.23 - } - } - } + "category": "Pokemon", + "id": "swsh3-136", + "illustrator": "tetsuya koizumi", + "image": "https://assets.tcgdex.net/en/swsh/swsh3/136", + "localId": "136", + "name": "Furret", + "rarity": "Uncommon", + "set": { + "cardCount": { + "official": 189, + "total": 201 + }, + "id": "swsh3", + "logo": "https://assets.tcgdex.net/en/swsh/swsh3/logo", + "name": "Darkness Ablaze", + "symbol": "https://assets.tcgdex.net/univ/swsh/swsh3/symbol" + }, + "variants": { + "firstEdition": false, + "holo": false, + "normal": true, + "reverse": true, + "wPromo": false + }, + "variants_detailed": [ + { + "type": "normal", + "size": "standard" + }, + { + "type": "reverse", + "size": "standard" + } + ], + "dexId": [162], + "hp": 110, + "types": [ + "Colorless" + ], + "evolveFrom": "Sentret", + "description": "It makes a nest to suit its long and skinny body. The nest is impossible for other Pokémon to enter.", + "stage": "Stage1", + "attacks": [ + { + "cost": [ + "Colorless" + ], + "name": "Feelin' Fine", + "effect": "Draw 3 cards." + }, + { + "cost": [ + "Colorless" + ], + "name": "Tail Smash", + "effect": "Flip a coin. If tails, this attack does nothing.", + "damage": 90 + } + ], + "weaknesses": [ + { + "type": "Fighting", + "value": "×2" + } + ], + "retreat": 1, + "regulationMark": "D", + "legal": { + "standard": false, + "expanded": true + }, + "updated": "2025-08-16T20:39:55Z", + "pricing": { + "cardmarket": { + "updated": "2026-02-02T01:47:49.000Z", + "unit": "EUR", + "idProduct": 483559, + "avg": 0.13, + "low": 0.02, + "trend": 0.08, + "avg1": 0.08, + "avg7": 0.07, + "avg30": 0.09, + "avg-holo": 0.32, + "low-holo": 0.03, + "trend-holo": 0.28, + "avg1-holo": 0.34, + "avg7-holo": 0.28, + "avg30-holo": 0.28 + }, + "tcgplayer": { + "updated": "2026-02-01T20:04:46.000Z", + "unit": "USD", + "normal": { + "productId": 219333, + "lowPrice": 0.01, + "midPrice": 0.18, + "highPrice": 25.18, + "marketPrice": 0.17, + "directLowPrice": 0.14 + }, + "reverse-holofoil": { + "productId": 219333, + "lowPrice": 0.14, + "midPrice": 0.3, + "highPrice": 5.18, + "marketPrice": 0.3, + "directLowPrice": null + } + } + } } ```