Files
cardgen/tools/card_creation_and_prebuilt_deck_runbook.md

16 KiB
Raw Permalink Blame History

Card Creation and Prebuilt Deck Runbook

This is the practical runbook for taking a deck from design document to live SOR catalog cards to a real prebuilt deck.

It exists because the process now works, but there are enough sharp edges that future-you should not have to reconstruct it from chat logs and vibes.

This runbook is based on the live process used to create and ship:

  • the Red Shift Exodus card definitions
  • the Terramorpha retrofit cards
  • the Orison Migration Covenant prebuilt deck

0. Goal

The full pipeline is:

  1. design the deck
  2. audit the deck against the current ability system
  3. redesign any awkward card text to fit the current engine cleanly
  4. generate machine-usable card definitions
  5. insert card definitions into the live catalog
  6. patch card/ability descriptions if needed
  7. create any missing supporting cards (e.g. Terramorpha package)
  8. assemble a real prebuilt deck
  9. verify the final result in admin and in the database

1. Where the source material lives

Design-side inputs

These usually live in:

  • cardgen/

Relevant files include:

  • set_bible_*.md
  • *_deck_*.md
  • decks-r1/*.md
  • decks-r1_residual_gap_redesigns.md
  • sor_ability_system_gaps_found_via_deck_conversion.md
  • decks-r1_post_revision_residual_gap_synthesis.md

Game-side reference inputs

These live in:

  • /home/prime/.openclaw/workspace/SOR

Most relevant:

  • SOR/Shared/context-files/gameplay.md
  • SOR/Shared/context-files/abilities.md
  • SOR/Server/src/SOR.Game/Abilities/*
  • SOR/Server/src/SOR.Database/Entities/Catalog/CardDefinition.cs
  • SOR/Server/src/SOR.Database/Entities/Bazaar/PrebuiltDeck.cs
  • SOR/Server/src/SOR.Database/Entities/Bazaar/PrebuiltDeckCard.cs
  • SOR/Server/src/SOR.Database/Enums/*

2. Authoring conventions

These matter a lot.

2.1 Card description vs ability description

This was one of the first real schema mistakes we made.

Correct rule

  • Card Description = the card’s visual/flavor depiction
  • Ability Description = the card’s mechanical text for that ability

Wrong rule

Do not put the full card rules summary into the top-level card description.

That makes admin entries ugly and semantically wrong.


2.2 Use AbilitiesJson vs EffectsJson correctly

Per CardDefinition.cs:

  • AbilitiesJson → for:
    • ArchSpirit
    • Spirit
    • Ruin
  • EffectsJson → for:
    • Repentance
    • Instinct
    • Terramorpha

If you violate that, you are fighting the model instead of using it.


2.3 Prefer engine-safe wording over poetic-but-fuzzy wording

When writing live cards, prefer:

  • “if this unit is on Marsh when it attacks”
  • “if it ends on Marsh”
  • “target friendly unit gains +1 MP this turn”

instead of fuzzy text like:

  • “while moving”
  • “from or into” terrain unless strongly justified
  • weird half-realtime language in a turn-based tactics game

The R1 audit and residual redesign docs exist for exactly this reason.


2.4 ArchSpirit tier chains must be linked

For ArchSpirit cards:

  • Tier 1 has PreviousTierId = null
  • Tier 2+ must point to the previous tier’s catalog card definition id

This is important when inserting to the live catalog.

In planning JSON we used:

  • previousTierName

Then resolved that name into a real PreviousTierId during insertion.


2.5 Terramorpha cards are regular catalog cards

They are stored in catalog.card_definitions like anything else, with:

  • CardType = Terramorpha
  • TerramorphaMode = Mono | Di | Tri
  • EffectsJson containing the tile-affinity actions

They are not some special out-of-band object.


3. Design → machine-usable card plan

3.1 Start from the deck doc

A deck doc gives you:

  • name
  • affinity
  • costs
  • stats
  • depiction text
  • intended ability text

But it is not yet insertion-ready.

3.2 Audit against the current engine

Before generating live definitions, check:

  • decks-r1/<deck>.md
  • residual redesign docs
  • current SOR.Game/Abilities

Questions to resolve:

  • is this implementable now?
  • does it need templating cleanup?
  • does this wording assume a mechanic the game doesn’t actually resolve?

3.3 Produce one definition per unique card

The plan file should contain one object per unique card definition, not one entry per copy.

Example:

  • Ballast Skiff Tender once in JSON, not three times
  • count is handled later in deck assembly

3.4 Write the plan to a real file

Do not try to shuttle huge JSON blobs through chat/session output if you can avoid it.

Use a real workspace file, e.g.:

  • cardgen/redshift_card_plan.json

This avoids truncation and partial-copy nonsense.

3.5 Validate the JSON file before inserting

Always parse it first.

Example:

python3 - <<'PY'
import json
p='cardgen/redshift_card_plan.json'
with open(p) as f:
    data=json.load(f)
print('COUNT', len(data))
print('FIRST', data[0]['name'])
print('LAST', data[-1]['name'])
PY

If this fails, stop.


4. How to reach the live system

4.1 SOR repo

Main repo:

  • /home/prime/.openclaw/workspace/SOR

4.2 Admin portal

Live admin portal:

  • https://control.aeternalisgames.com

4.3 The browser caveat

Browser automation may not be available from the current host. If the browser relay is unavailable, do not pretend you can drive the UI.

Use:

  • direct HTTP verification for login when possible
  • direct DB insertion for the actual catalog/deck changes
  • admin portal as a verification surface afterward

5. How to get live DB credentials

In this setup, the working connection string and admin creds were found in Kubernetes secrets.

5.1 Relevant namespace

The live SOR app secrets were in:

  • stone-server

5.2 Useful secret

  • sor-app-secrets

5.3 Example retrieval

ssh -i /home/prime/.ssh/id_ed25519_prime -o StrictHostKeyChecking=no prime@172.10.1.160 \
  "sudo -n kubectl -n stone-server get secret sor-app-secrets -o jsonpath='{.data.ConnectionStrings__Default}' | base64 -d"

Similarly for admin auth:

ssh -i /home/prime/.ssh/id_ed25519_prime -o StrictHostKeyChecking=no prime@172.10.1.160 \
  "sudo -n kubectl -n stone-server get secret sor-app-secrets -o jsonpath='{.data.Admin__Email}' | base64 -d; echo"

ssh -i /home/prime/.ssh/id_ed25519_prime -o StrictHostKeyChecking=no prime@172.10.1.160 \
  "sudo -n kubectl -n stone-server get secret sor-app-secrets -o jsonpath='{.data.Admin__Password}' | base64 -d; echo"

5.4 Important note

Treat these as sensitive operational creds. Do not spray them around casually.


6. Verifying admin access

Even if you are not driving the UI, verify that admin auth works.

Example with Python + cookie jar:

import urllib.request, urllib.parse, http.cookiejar
cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
url = 'https://control.aeternalisgames.com/auth/login'
data = urllib.parse.urlencode({'email':'<ADMIN_EMAIL>','password':'<ADMIN_PASSWORD>'}).encode()
req = urllib.request.Request(url, data=data, method='POST')
resp = opener.open(req, timeout=30)
print(resp.geturl(), resp.status)

Then verify cards page access:

html = opener.open('https://control.aeternalisgames.com/cards', timeout=30).read().decode('utf-8','ignore')
print('Some known card' in html)

This proves the portal is alive and the auth path works.


7. Inserting catalog card definitions

Use direct Postgres insertion via Node.js and the pg package.

Why:

  • psql may not be installed
  • dotnet SDK may not be installed locally
  • Python DB libs may not be available
  • Node is available and easy to bootstrap ad hoc

7.2 Basic pattern

  1. load cardgen/<plan>.json
  2. for each card:
    • check if a card with the same name already exists
    • if yes, skip or patch depending on intent
    • if no, insert it
  3. when inserting Tier 2/3 ArchSpirits:
    • resolve previousTierName → PreviousTierId
  4. serialize abilitiesJson / effectsJson into JSONB

7.3 Key schema gotcha

The database columns are PascalCase quoted, not lowercase.

For example:

  • "Id"
  • "Name"
  • "CardType"
  • "Affinity"
  • "SpCost"

If you use lowercase unquoted names like id, you will get column errors.

7.4 Example shape

A typical insert looked like:

insert into catalog.card_definitions (
  "Id","Name","Description","CardType","Affinity","SpCost","StCost",
  ...,
  "abilities","effects","Rarity","IsPublished","IsRetired","CreatedAt","UpdatedAt"
)
values (...)

7.5 Duplicate safety

Always check by card name first:

select "Id" from catalog.card_definitions where "Name"=$1 limit 1

This prevents accidental duplicate card definitions when rerunning scripts.


8. Patching inserted cards

After the first insertion pass, you may realize you structured something badly. That is normal.

In our real process, we had to patch:

  • card descriptions
  • ability descriptions
  • one aura-related ability shape

8.1 Typical patch flow

  1. rewrite the local plan JSON file
  2. run SQL updates against existing catalog.card_definitions
  3. update:
    • "Description"
    • "abilities"
    • "effects"
    • "UpdatedAt"

8.2 Example of what we fixed live

Wrong

  • card Description contained rules summary

Correct

  • card Description became visual depiction text
  • ability Description became readable rules text

This patch was applied across all 30 inserted Red Shift cards.


9. Creating Terramorpha cards

9.1 Why do it separately?

Sometimes the original design doc doesn’t include the final Terramorpha package count or exact card list.

That’s okay. You can add them later as regular catalog cards.

9.2 Minimal required fields

For Terramorpha cards:

  • CardType = Terramorpha
  • Affinity = Lake / Field / etc.
  • SpCost
  • StCost
  • TerramorphaMode = Mono | Di | Tri
  • EffectsJson
  • Rarity
  • Description

9.3 Example package used

For the Red Shift deck, we added:

  • Lake Monomorpha
  • Field Monomorpha
  • Lake Dimorpha
  • Field Dimorpha
  • Lake Trimorpha
  • Field Trimorpha

9.4 Effect pattern

A Terramorpha effect is just a tile-targeting card effect. Example conceptual form:

[
  {
    "Target": { "Scope": "Battlefield", "Type": "Tile", "Ownership": "Any", "Count": { "N": 1 } },
    "Effects": [
      { "$type": "PushAffinity", "Affinity": { "Fixed": "Lake" } }
    ]
  }
]

Di/Tri use higher target counts and rely on game-side targeting/legality.


10. Building a prebuilt deck

10.1 Relevant entities

See:

  • SOR/Server/src/SOR.Database/Entities/Bazaar/PrebuiltDeck.cs
  • SOR/Server/src/SOR.Database/Entities/Bazaar/PrebuiltDeckCard.cs

10.2 Important structure

A prebuilt deck has:

  • metadata row in bazaar.prebuilt_decks
  • card rows in bazaar.prebuilt_deck_cards

Key fields on the main deck row:

  • Name
  • Description
  • IsActive
  • IsStarterDeck
  • IsAvailableInShop
  • ArchSpiritCardDefinitionId
  • ArchSpiritName

Card rows need:

  • PrebuiltDeckId
  • CardDefinitionId
  • CardName
  • Quantity

10.3 Workflow

  1. decide the final 60-card list
  2. resolve each card name to its live CardDefinitionId
  3. create or update the prebuilt deck row
  4. delete existing deck-card rows if rebuilding
  5. insert the fresh PrebuiltDeckCard rows
  6. verify totals

10.4 Verification query

Always verify:

select count(*)::int as unique_cards,
       sum("Quantity")::int as total_cards
from bazaar.prebuilt_deck_cards
where "PrebuiltDeckId"=$1

If total is not what you intended, stop and fix it.


11. Real example: Orison Migration Covenant

11.1 First pass mistake

The first Terramorpha retrofit prebuilt deck pass landed at:

  • 63 cards, not 60

This happened because the first cut package was incomplete.

11.2 Correct behavior

Do not pretend 63 is close enough. Count it, fix it, rerun.

11.3 Final fixed result

The final prebuilt deck landed at:

  • unique cards: 29
  • total cards: 60

Deck:

  • Orison Migration Covenant
  • Deck ID: 1045ea8d-4f91-4fc0-9be8-6ec9431172e4

This is the correct standard: verify, fix, verify again.


12. How to choose cuts when retrofitting a deck

When adding something like a Terramorpha package later, do not cut randomly.

12.1 Cut philosophy used

Prefer cutting from:

  • slower top-end
  • redundant reactive pieces
  • lower-priority support cards
  • cards whose job is partly replaced by terrain shaping

Avoid cutting heavily from:

  • the ArchSpirit line
  • core low-end glue
  • the deck’s defining payoff cards
  • cards that make the deck’s setting identity obvious

12.2 Example Red Shift retrofit logic

We preserved:

  • ArchSpirit line
  • early glue creatures
  • Marsh payoffs
  • logistics/corridor feel

We cut more from:

  • some slower / redundant support
  • some top-end
  • some extra reactive spell density

13. Recommended verification checklist

Before calling the job done, verify all of this.

13.1 Catalog card verification

  • all expected unique cards exist in catalog.card_definitions
  • no accidental duplicate names
  • top-level card descriptions are depiction text
  • ability descriptions contain readable rules text
  • ArchSpirit tier chain is linked correctly
  • Terramorpha cards have the correct mode
  • AbilitiesJson / EffectsJson landed in the correct field

13.2 Admin verification

  • admin login works
  • cards appear on /cards
  • edit links exist
  • card pages can be opened

13.3 Prebuilt deck verification

  • prebuilt deck row exists in bazaar.prebuilt_decks
  • ArchSpiritCardDefinitionId points to the correct Tier 1 ArchSpirit
  • card rows exist in bazaar.prebuilt_deck_cards
  • unique-card count is expected
  • total-card count is expected
  • deck is marked active/inactive appropriately

14. Common failure modes

14.1 Chat/session blob truncation

Large JSON plans can get truncated if you try to ferry them through assistant/session messages.

Fix

Write them to a real file and use the file.


14.2 Wrong description semantics

Top-level description becoming rules text instead of depiction.

Fix

Patch live cards and update the local plan file.


14.3 Tier chain not linked

Tier 2/3 ArchSpirits inserted without resolving PreviousTierId.

Fix

Resolve previous tier by name before insert.


14.4 Wrong quoted column names

Using lowercase column names in SQL instead of the real quoted PascalCase schema.

Fix

Use the exact schema names.


14.5 Count drift in prebuilt decks

First pass deck total ends up 63, 58, etc.

Fix

Always verify counts and explicitly adjust.


14.6 Pretending browser automation exists when it does not

If browser relay is unavailable, don’t fake UI automation.

Fix

Use:

  • direct auth verification
  • direct DB insertion
  • admin UI as post-fact verification

15. Recommended future improvements

This runbook works, but the process can still be improved.

15.1 Best next tool improvement

Build a proper importer that:

  • reads a validated JSON card plan
  • inserts/updates card definitions safely
  • resolves ArchSpirit previous tiers automatically
  • optionally creates/updates prebuilt decks
  • emits a verification report

That is better than hand-rolled one-off scripts every time.

15.2 Nice second improvement

Add a deck-plan schema file so card plan JSON has a stable documented format.

15.3 Nice third improvement

Add dry-run validation that checks:

  • missing referenced cards
  • malformed ability JSON
  • non-60 card totals
  • duplicate names
  • bad card type / JSON field mismatches

16. Short version

If you only remember the essentials, remember this:

  1. Design the deck in cardgen
  2. Audit and clean the text against the live ability system
  3. Generate one unique-card JSON plan to a real file
  4. Insert cards into catalog.card_definitions using direct DB access
  5. Patch descriptions/abilities if needed
  6. Add missing support cards like Terramorpha
  7. Create/update a prebuilt deck in bazaar.prebuilt_decks
  8. Verify counts and admin visibility

That is the pipeline.


17. Final note

This process is real now, not theoretical. It has already been used successfully to:

  • create live SOR cards
  • patch those cards
  • add Terramorpha support cards
  • assemble a live prebuilt deck

So future-you does not need to rediscover whether this is possible. It is. The main job is just to follow the steps cleanly and avoid the documented mistakes.