--- name: cube-builder description: This skill should be used when building cube draft configurations for GEMP-SWCCG from CSV files containing card names. It handles mapping card names to IDs, generating cube configurations with add-on card support, and integrating the cube into the application (swccgDrafts.json registration and frontend dropdown setup). --- # Cube Builder ## Overview Build cube draft configurations for GEMP-SWCCG by mapping CSV files of card names to card IDs and generating properly structured cube configuration JSON files. This skill covers the complete workflow from CSV preparation through deployment, including the critical playtesting card exclusion requirement and add-on card pack structure. ## When to Use This Skill Use this skill when: - Creating a new cube draft configuration from card lists - Updating an existing cube with new cards - Troubleshooting cube draft issues (missing cards, playtesting cards appearing, etc.) - Understanding how multi-column CSVs create add-on card packs ## Workflow **CRITICAL REQUIREMENT:** Unless explicitly told otherwise, you MUST use side-specific databases with defensive shields filtered out when mapping light\/dark side cards. This prevents: 1. Defensive shield versions being mapped instead of effect versions (e.g., "Battle Plan" as shield vs effect) 2. Wrong-side cards appearing in drafts (e.g., DARK "Control" in LIGHT side packs) 3. Slug collision errors See Step 3 for detailed instructions on creating filtered databases. ### Step 1: Prepare CSV Files Create three CSV files in the cube source directory: 1. **default_cards.csv** - Single column of card names (core cards all players start with) 2. **cube_worlds_lightside.csv** - Light side packs (supports multi-column for add-ons) 3. **cube_worlds_darkside.csv** - Dark side packs (supports multi-column for add-ons) **CSV Column Structure:** - **Single column** → Produces flat array: `["card1_id", "card2_id"]` - **Multiple columns** → Produces array of arrays: `[["primary_id", "addon1_id"], ["card2_id"]]` - Column 1 = primary card in the pack - Columns 2+ = add-on cards that come with the primary card - When a player picks a pack, they receive ALL cards in that array - Empty cells are skipped **Example multi-column CSV:** ```csv Admiral Ackbar,Home One Obi-Wan Kenobi,Kenobi's Lightsaber Luke Skywalker,, ``` **Produces:** ```json [ ["admiral_ackbar_id", "home_one_id"], ["obi_wan_id", "lightsaber_id"], ["luke_id"] ] ``` **Directory Structure:** ``` src\/gemp-swccg-server\/src\/main\/resources\/draft\/cube_building\/ └── \/ ├── default_cards.csv ├── cube_worlds_lightside.csv └── cube_worlds_darkside.csv ``` ### Step 2: Update Card Database (Critical) The card mapping process requires an up-to-date card database that EXCLUDES playtesting cards (set 501). ```bash .\/bin\/gemp export-cards src\/gemp-swccg-cards\/src\/main\/resources\/card_blueprint_database.json ``` **Why this matters:** The CardDataExporter automatically excludes set501 cards via a filter. If this step is skipped or uses old data, playtesting cards will appear in the cube. **Verification:** ```bash grep -c '"cardId": "501_' src\/gemp-swccg-cards\/src\/main\/resources\/card_blueprint_database.json # Must output: 0 ``` ### Step 3: Create Side-Specific Databases (CRITICAL) **IMPORTANT:** Unless explicitly told otherwise, you MUST filter out defensive shields from the side-specific databases to prevent slug collisions. Cards like "Battle Plan" exist as both Effect and Defensive Shield with the same slug - without filtering, the defensive shield version will be incorrectly mapped instead of the effect. **Create filtered databases excluding defensive shields:** ```bash bash <<'BASH' cd src\/gemp-swccg-cards\/src\/main\/resources # Create light side database without defensive shields jq '[.[] | select(.side == "LIGHT" and .cardCategory != "DEFENSIVE_SHIELD")]' \ card_blueprint_database.json > \/tmp\/card_blueprint_database_light_no_shields.json # Create dark side database without defensive shields jq '[.[] | select(.side == "DARK" and .cardCategory != "DEFENSIVE_SHIELD")]' \ card_blueprint_database.json > \/tmp\/card_blueprint_database_dark_no_shields.json BASH ``` **Verify filtering worked:** ```bash bash <<'BASH' echo "Light side defensive shields (should be 0):" jq '[.[] | select(.cardCategory == "DEFENSIVE_SHIELD")] | length' \ \/tmp\/card_blueprint_database_light_no_shields.json echo "Dark side defensive shields (should be 0):" jq '[.[] | select(.cardCategory == "DEFENSIVE_SHIELD")] | length' \ \/tmp\/card_blueprint_database_dark_no_shields.json BASH ``` **Why this matters:** - Prevents defensive shields from being mapped when effect versions exist - Prevents side-mixing (e.g., DARK "Control" appearing in LIGHT side packs) - Resolves slug collisions for cards with same names on both sides ### Step 4: Map Card Names to IDs Map each CSV file to card IDs using the `map_card_names_to_ids` script with **side-specific, defensive-shield-filtered databases**: ```bash CUBE_DIR="src\/gemp-swccg-server\/src\/main\/resources\/draft\/cube_building\/" # Map default\/core cards (use main database) .\/bin\/map_card_names_to_ids \ $CUBE_DIR\/default_cards.csv \ $CUBE_DIR\/default_cards_mapped.json \ src\/gemp-swccg-cards\/src\/main\/resources\/card_blueprint_database.json # Map light side packs (use light-only, no shields) .\/bin\/map_card_names_to_ids \ $CUBE_DIR\/cube_worlds_lightside.csv \ $CUBE_DIR\/cube_worlds_lightside_mapped.json \ \/tmp\/card_blueprint_database_light_no_shields.json # Map dark side packs (use dark-only, no shields) .\/bin\/map_card_names_to_ids \ $CUBE_DIR\/cube_worlds_darkside.csv \ $CUBE_DIR\/cube_worlds_darkside_mapped.json \ \/tmp\/card_blueprint_database_dark_no_shields.json ``` **Output Files:** - `*_mapped.json` - Card ID arrays (flat or nested based on CSV structure) - `*_mapped_log.json` - Processing logs with missing cards and warnings **Review the logs** for: - Missing cards (slug shown for debugging) - Multiple matches (script auto-selects first match) - Success rate (should be >95%) **Script Behavior:** - Detects single vs multi-column by checking for non-empty columns - Slugifies card names (lowercase, special chars → `-`) - Tries exact slug match, then slug + set name, then slug with `-v` suffix (virtual fallback) - Logs all issues for review ### Step 5: Generate Cube Configuration Use `create_cube` to build the final configuration: ```bash python3 bin\/create_cube \ src\/gemp-swccg-server\/src\/main\/resources\/draft\/cube_building\/ \ src\/gemp-swccg-server\/src\/main\/resources\/draft\/.json ``` **Required Files in Cube Directory:** - `default_cards_mapped.json` - `cube_worlds_lightside_mapped.json` - `cube_worlds_darkside_mapped.json` **Configuration Parameters (hardcoded in script):** - `count: 9` - Pack choices shown per round - `repeat: 56` - Number of draft rounds - `objChoiceCountPerSide: 0` - No objective picks (standard cube) **Output Structure:** ```json { "format": "cube", "fixedCount": 0, "objChoiceCountPerSide": 0, "choiceCountPerSide": 56, "lightObjCards": [], "darkObjCards": [], "startingPool": { "type": "cubeDraftRun", "data": { "coreCards": ["5_164", "12_164", ...] } }, "choices": [ { "type": "cubePackObjPick", "repeat": 56, "data": { "count": 9, "packs": [ ["110_6", "107_5"], ["213_31"], ... ] } }, { \/* dark side choice with same structure *\/ } ] } ``` ### Step 6: Register Draft Format Add the cube to the draft registry: **File:** `src\/gemp-swccg-server\/src\/main\/resources\/swccgDrafts.json` ```json [ { "type": "c7_draft", "location": "\/draft\/cube7Draft.json" }, { "type": "_draft", "location": "\/draft\/.json" } ] ``` **Important:** - `type` - Format identifier (used in code and database) - `location` - Path relative to resources directory ### Step 7: Update Frontend Add the cube to the league admin dropdown: **File:** `src\/gemp-swccg-async\/src\/main\/web\/includes\/admin\/leagueAdmin.html` **Location:** Around line 459 in the solo draft form ```html