16 KiB
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 Covenantprebuilt deck
0. Goal
The full pipeline is:
- design the deck
- audit the deck against the current ability system
- redesign any awkward card text to fit the current engine cleanly
- generate machine-usable card definitions
- insert card definitions into the live catalog
- patch card/ability descriptions if needed
- create any missing supporting cards (e.g. Terramorpha package)
- assemble a real prebuilt deck
- 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_*.mddecks-r1/*.mddecks-r1_residual_gap_redesigns.mdsor_ability_system_gaps_found_via_deck_conversion.mddecks-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.mdSOR/Shared/context-files/abilities.mdSOR/Server/src/SOR.Game/Abilities/*SOR/Server/src/SOR.Database/Entities/Catalog/CardDefinition.csSOR/Server/src/SOR.Database/Entities/Bazaar/PrebuiltDeck.csSOR/Server/src/SOR.Database/Entities/Bazaar/PrebuiltDeckCard.csSOR/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:ArchSpiritSpiritRuin
EffectsJson→ for:RepentanceInstinctTerramorpha
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 = TerramorphaTerramorphaMode = Mono | Di | TriEffectsJsoncontaining 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 Tenderonce 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
7.1 Recommended insertion path
Use direct Postgres insertion via Node.js and the pg package.
Why:
psqlmay not be installeddotnetSDK 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
- load
cardgen/<plan>.json - 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
- when inserting Tier 2/3 ArchSpirits:
- resolve
previousTierName→PreviousTierId
- resolve
- serialize
abilitiesJson/effectsJsoninto 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
- rewrite the local plan JSON file
- run SQL updates against existing
catalog.card_definitions - update:
"Description""abilities""effects""UpdatedAt"
8.2 Example of what we fixed live
Wrong
- card
Descriptioncontained rules summary
Correct
- card
Descriptionbecame visual depiction text - ability
Descriptionbecame 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 = TerramorphaAffinity = Lake / Field / etc.SpCostStCostTerramorphaMode = Mono | Di | TriEffectsJsonRarityDescription
9.3 Example package used
For the Red Shift deck, we added:
Lake MonomorphaField MonomorphaLake DimorphaField DimorphaLake TrimorphaField 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.csSOR/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:
NameDescriptionIsActiveIsStarterDeckIsAvailableInShopArchSpiritCardDefinitionIdArchSpiritName
Card rows need:
PrebuiltDeckIdCardDefinitionIdCardNameQuantity
10.3 Workflow
- decide the final 60-card list
- resolve each card name to its live
CardDefinitionId - create or update the prebuilt deck row
- delete existing deck-card rows if rebuilding
- insert the fresh
PrebuiltDeckCardrows - 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/EffectsJsonlanded 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 ArchSpiritCardDefinitionIdpoints 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:
- Design the deck in
cardgen - Audit and clean the text against the live ability system
- Generate one unique-card JSON plan to a real file
- Insert cards into
catalog.card_definitionsusing direct DB access - Patch descriptions/abilities if needed
- Add missing support cards like Terramorpha
- Create/update a prebuilt deck in
bazaar.prebuilt_decks - 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.