Card IDs

Every numeric card value in the SDK is a my-swu.com card ID: the same numeric ID my-swu.com uses to identify an individual card. The simulator serves those IDs from its canonical card-data cache.

They are not SWU collector numbers, set card numbers, indexes in a deck list, or match-local object IDs.

Where They Appear

Use my-swu.com card IDs for deck and card-choice fields:

Field	Meaning
leader	One my-swu.com leader card ID.
leaders	Twin Suns my-swu.com leader card IDs.
base	One my-swu.com base card ID.
cards	my-swu.com main-deck card IDs.
sideboard	my-swu.com sideboard card IDs.
cardId / cardIds	my-swu.com card IDs in commands, events, and snapshots.

Runtime IDs are different. unitId, upgradeId, and abilityId are handles created inside one match. matchId, eventId, and seatToken identify server resources or credentials. Do not pass those where a card ID is expected.

Resolving Card Ids

External deck tools often export cards as a set code plus printed card number, such as SOR_001. Use cards.resolveId() to convert that reference into one my-swu.com card ID:

const krennicCardId = await simulatorClient.cards.resolveId({
  setCode: 'SOR',
  cardNumber: 1,
  cardTypes: ['leader'],
})

Some set numbers are shared by different card types, especially leaders and tokens. Pass cardTypes when the deck section tells you the expected type:

Deck section	cardTypes
leader / secondleader	['leader']
base	['base']
deck / sideboard	['unit', 'event', 'upgrade']

For bulk imports, cards.resolveIds() returns one resolution per input. A resolution has cardId only when exactly one my-swu.com card matches; otherwise inspect matches to show not-found or ambiguous references.

const cardIdResolutions = await simulatorClient.cards.resolveIds([
  {
    setCode: 'SOR',
    cardNumber: 1,
    cardTypes: ['leader'],
  },
  {
    setCode: 'SOR',
    cardNumber: 25,
    cardTypes: ['base'],
  },
])

for (const resolution of cardIdResolutions) {
  if (resolution.cardId == null) {
    console.warn(resolution.reference, resolution.matches)
  }
}

JSON Deck Imports

The SDK can convert my-swu JSON deck exports, where each card id has SET_001 form, into simulator deck input:

const deckInput = await simulatorClient.cards.convertDeckJson({
  metadata: { name: 'Import Test', author: 'tester' },
  leader: { id: 'SOR_001', count: 1 },
  base: { id: 'SOR_025', count: 1 },
  deck: [{ id: 'SOR_010', count: 3 }],
  sideboard: [{ id: 'SOR_047', count: 2 }],
})

await simulatorClient.matches.create({
  format: 'premier',
  hostDeck: deckInput,
})

convertDeckJson() accepts either a parsed object or a JSON string. It ignores metadata and reserve, expands each count, filters by deck section, and throws if a reference is not found or remains ambiguous.

Deck validation canonicalizes print IDs before checking copy limits, so alternate prints count with the same canonical card identity when format rules need that behavior.

Resolving Names

Use cards.get() when an app needs to display my-swu.com card names for IDs:

const exampleCardMetadata = await simulatorClient.cards.get([
  46102, // Leia Organa - Someone Who Loves You
  308, // Echo Base
])

console.log(exampleCardMetadata.map(card => card.title))

When working inside this repository, the same card data is cached in data/cards/<id>.json. Treat that local cache as a mirror of the canonical card data used by the simulator server.