RFC: Add pull rates to sets & cards

[Aviortheking]

Pull rates

Following conversations on the Discord I have decided to start this RFC about adding pull rates to differents endpoints in the API :

The main goal is to allow developers use publically available card drop rates for multiple tools/games like a booster opening simulator.

Set definition

in /api/v2/{lang}/sets/{setId} :

the definition of the field would be the following

a record with the key being normal or godpack (there also seems to be semigodpack for physical sets)

in each elements the slots is an array with the index being the position of the card from the first to last to appear in a normal opening (not reversed)

each slots then contain a simple object that indicate that each chances has a certain probability to appear (in percent)

for the rate it will be the rate of appearance of the specific booster pack (ex: godpack is 0.5%)

interface Set {
	...
	pullRates?: Partial<Record<'normal' | 'godpack', {
		slots: Array<Partial<Record<Card['rarity'], number>>>
		rate: number
	}>>
}

JSON of the set

see the field pullRates

{
		"cardCount": {
			"firstEd": 0,
			"holo": 0,
			"normal": 0,
			"official": 68,
			"reverse": 0,
			"total": 85
		},
		"cards": [
			{
				"id": "A1a-001",
				"image": "https://assets.tcgdex.net/en/tcgp/A1a/001",
				"localId": "001",
				"name": "Exeggcute"
			},
			...
			{
				"id": "A1a-086",
				"image": "https://assets.tcgdex.net/en/tcgp/A1a/086",
				"localId": "086",
				"name": "Mew ex"
			}
		],
		"id": "A1a",
		"legal": {
			"expanded": false,
			"standard": false
		},
		"logo": "https://assets.tcgdex.net/en/tcgp/A1a/logo",
		"name": "Mythical Island",
		"releaseDate": "2024-12-17",
		"serie": {
			"id": "tcgp",
			"name": "Pokémon TCG Pocket"
		},
		"pullRates": {
			"normal": {
				"rate": 99.95,
				"slots": [
					{
						"One Diamond": 100
					},
					{
						"One Diamond": 100
					},
					{
						"One Diamond": 100
					},
					{
						"Crown": 0.04,
						"Three Star": 0.222,
						"Two Star": 0.5,
						"One Star": 2.572,
						"Four Diamond": 1.666,
						"Three Diamond": 5,
						"Two Diamond": 90
					},
					{
						"Crown": 0.16,
						"Three Star": 0.888,
						"Two Star": 2,
						"One Star": 10.288,
						"Four Diamond": 6.664,
						"Three Diamond": 20,
						"Two Diamond": 60
					}
				]
			},
			"godpack": {
				"rate": 0.05,
				"slots": [
					{
						"Crown": 5,
						"Three Star": 5,
						"Two Star": 50,
						"One Star": 40
					}
				]
			}
		}
	}

Card definition

like the set each cards would have a pullRates key that contains a Record of pack type with the following

rate: the rate of appearance of the pack
slots: the rate of appearance of this specific card in the booster pack
total_slots: the same as slot but with a pre calculation based on the rate (not sure to keep as it's easy to repeat from the developper code by just multiplying the slot rate by the rate slots[number] * rate = totalSlots[number])

interface Card {
	...
	pullRates?: Record<string, {
		rate: number
		/**
		 * raw rate ignoring the type rate
		 */
		slots: Array<number>
		/**
		 * rate including the base rate
		 */
		totalSlots: Array<number>
	}>
}

and in `/v2/{lang}/cards/{cardId}

json of the endpoint

See the field pullRates

{
		"category": "Pokemon",
		"id": "A1a-002",
		"illustrator": "Masakazu Fukuda",
		"image": "https://assets.tcgdex.net/en/tcgp/A1a/002",
		"localId": "002",
		"name": "Exeggutor",
		"rarity": "Two Diamond",
		"set": {
			"cardCount": {
				"official": 68,
				"total": 85
			},
			"id": "A1a",
			"logo": "https://assets.tcgdex.net/en/tcgp/A1a/logo",
			"name": "Mythical Island"
		},
		"variants": {
			"firstEdition": false,
			"holo": true,
			"normal": true,
			"reverse": true,
			"wPromo": false
		},
		"pullRates": {
			"normal": {
				"rate": 99.95,
				"slots": [
					0,
					0,
					0,
					3.91304347826087,
					2.608695652173913
				],
				"total_slots": [
					0,
					0,
					0,
					3.9110869565217388,
					2.607391304347826
				]
			},
			"godpack": {
				"rate": 0.05,
				"slots": [
					0
				],
				"total_slots": [
					0
				]
			}
		},
		"hp": 130,
		"types": [
			"Grass"
		],
		"evolveFrom": "Exeggcute",
		"description": "Each of Exeggutor's three heads is thinking<br />different thoughts. The three don't seem to be<br />very interested in one another.",
		"stage": "Stage1",
		"attacks": [
			{
				"cost": [
					"Grass",
					"Colorless",
					"Colorless",
					"Colorless"
				],
				"name": "Psychic",
				"effect": "This attack does 20 more damage for each Energy attached to your opponent's Active Pokémon.",
				"damage": 80
			}
		],
		"weaknesses": [
			{
				"type": "Fire",
				"value": "+20"
			}
		],
		"retreat": 3,
		"legal": {
			"standard": false,
			"expanded": false
		},
		"updated": "2024-12-19T01:16:28+01:00"
	}