Add card creation and prebuilt deck runbook

This commit is contained in:
Prime
2026-03-28 03:03:47 +00:00
parent b41fc22642
commit 88916c43db
+642
View File
@@ -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/<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:
```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':'<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:
```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/<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:
```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.