diff --git a/card_creation_and_prebuilt_deck_runbook.md b/card_creation_and_prebuilt_deck_runbook.md new file mode 100644 index 0000000..c3b9c71 --- /dev/null +++ b/card_creation_and_prebuilt_deck_runbook.md @@ -0,0 +1,642 @@ +# 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/.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: +```bash +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 +```bash +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: +```bash +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: +```python +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':'','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: +```python +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: +- `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/.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: +```sql +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: +```sql +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: +```json +[ + { + "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: +```sql +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.