Appearance
gamefile.jsonConfigure a card game with JSON — no engine code
A guide for TCG Arena game creators.
A guide for TCG Arena game creators.
A gamefile.json describes a game end to end: its name, how a legal deck is built, what happens on each turn, which board sections exist (hand, graveyard, token zone...), and how they're laid out visually. The engine reads this file and renders the matching game — you never touch the engine's code.
Reference example — every snippet in this guide comes from a real Magic: The Gathering configuration. Ask a maintainer for a full example file to keep next to this guide.
| Key | Contains |
|---|---|
name | The game's display name |
deckBuilding | Playable formats and deck-construction rules |
gameplay | One block per format: mulligan, turn structure, tokens, board layout |
defaultRessources | Default background images and a link to prebuilt decks |
cards | Where card data and the card-back image come from |
The smallest valid file — a single section, nothing optional:
{
"name": "My Card Game",
"deckBuilding": {
"mainFilters": ["type", "cost"],
"formats": [
{ "title": "Standard format", "gameplay": "Standard" }
]
},
"gameplay": {
"Standard": {
"mulligan": { "startingHandSize": 5 },
"newTurn": { "drawOnStart": true },
"sections": {
"layout": {
"direction": "column",
"content": [{ "section": "Board" }]
},
"sectionsDict": {
"Board": { "isHidden": "no", "height": "MEDIUM", "alignment": "CENTER" }
}
}
}
},
"cards": {
"dataUrl": "https://example.com/cards.json",
"cardBack": "https://example.com/card-back.jpg"
}
}Top-level fields that identify the game and its global behaviour.
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
name | S | required | Name of the game, shown in the game picker. | "Star wars unlimited" |
menuBackgroundImage | S | optional | URL of a background image for the menu screen. | "https://example.com/bg.jpg" |
cardRotation | N | optional | Default rotation in degrees applied to cards, e.g. 90 for a game with landscape-oriented cards (Pokémon, Yu-Gi-Oh). Can also be set per format inside gameplay.<format>. | 90 |
customHelp | S | optional | Free-text help shown to players, for game-specific mechanics that aren't obvious from the UI. Supports \n for line breaks. | "Drag a card onto the mana zone to add it as a resource." |
translationsUrl | S | optional | URL of a JSON file with UI and card text translations. | "https://example.com/translations.json" |
Where the game's content lives — background images, prebuilt decks, and the card data itself.
Where the game's content lives.
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
defaultRessources.backgrounds | [] | optional | Background images offered to the player by default. | ["https://example.com/bg1.jpg"] |
defaultRessources.decksUrl | S | optional | URL of decks.json, the array of prebuilt starter decks — see the Card & deck files panel. | "https://example.com/decks.json" |
cards.dataUrl | S | required | URL of the JSON file containing all cards for this game. | "https://example.com/cards.json" |
cards.cardBack | S | required | Image shown for a face-down card. | "https://example.com/back.jpg" |
cards.cardBackColor | S | optional | Fallback color shown around/behind the card back image, and used for the card-pile height effect. | "#c8bdb3" |
cards.extraCardBacks | {} | optional | Alternate card-back images per card type, e.g. a distinct back for "Legend" cards. | { "Legend": "https://example.com/legend-back.png" } |
cards.version | N | optional | Only worth setting for a very large card file (~20MB+): incrementing it lets returning players skip re-downloading cards.json when nothing changed. Not needed for a typical-sized game. | 28 |
Four panels cover the rest of the format, each focused on one part of the file: