efd-trading-card-base/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A Unity mod for Escape from Duckov that adds a customizable trading card system with storage solutions. The framework supports user-generated content through simple pipe-separated text files, allowing non-programmers to add their own card sets.

Build Commands

# Build the mod
dotnet build TradingCardMod.csproj

# Build release version
dotnet build TradingCardMod.csproj -c Release

# Output location: bin/Debug/netstandard2.1/TradingCardMod.dll

Important: Before building, update DuckovPath in TradingCardMod.csproj (line 10) to your actual game installation path.

Deployment

# Deploy to game (builds and copies all files)
./deploy.sh

# Deploy release build
./deploy.sh --release

# Remove mod from game
./remove.sh

# Remove with backup
./remove.sh --backup

Project Skills

Two workflow skills are available in this project:

• /build - Build and deploy locally for testing (runs dotnet build + ./deploy.sh)
• /deploy - Build Release and stage for Steam Workshop upload (uses workshop-upload.sh)

Skills are defined in .claude/skills/.

Testing

# Run all unit tests
dotnet test TradingCardMod.Tests.csproj

# Run tests with verbose output
dotnet test TradingCardMod.Tests.csproj --verbosity normal

# Run specific test class
dotnet test TradingCardMod.Tests.csproj --filter "FullyQualifiedName~CardParserTests"

# Run single test
dotnet test TradingCardMod.Tests.csproj --filter "ParseLine_ValidLineWithoutDescription_ReturnsCard"

Test Coverage: Parsing logic, validation, rarity mapping, TypeID generation, and description auto-generation are all tested. Unity-dependent code (item creation, tags) cannot be unit tested.

Architecture

Mod Loading System

The game loads mods from Duckov_Data/Mods/. Each mod requires:

• A DLL with namespace matching info.ini's name field
• A ModBehaviour class inheriting from Duckov.Modding.ModBehaviour
• The info.ini and preview.png files

Key Classes

• ModBehaviour (src/ModBehaviour.cs): Main entry point. Inherits from Duckov.Modding.ModBehaviour (which extends MonoBehaviour). Handles card set loading in Start() and cleanup in OnDestroy().

• Patches (src/Patches.cs): Harmony patch definitions. Uses HarmonyLib for runtime method patching. Patches are applied in Start() and removed in OnDestroy().

• TradingCard (src/TradingCard.cs): Data class representing card properties. Contains GenerateTypeID() for creating unique item IDs (100000+ range to avoid game conflicts).

• CardParser (src/CardParser.cs): Parses card definition files. Pure C# with no Unity dependencies, fully unit tested.

• ItemExtensions (src/ItemExtensions.cs): Reflection helpers for setting private fields on game objects.

• TagHelper (src/TagHelper.cs): Utilities for working with game tags, including creating custom tags.

• PackUsageBehavior (src/PackUsageBehavior.cs): Handles card pack opening mechanics. Implements gacha-style random card distribution based on rarity weights.

• ModConfigApi (src/ModConfigApi.cs): Optional integration with ModConfig mod. Adds card set information (set name, card number, rarity) to item descriptions in inventory. Also displays mod statistics including disabled card sets count.

• StorageHelper (src/StorageHelper.cs): Helper class for creating storage items with multi-tag slot filtering, enabling hierarchical storage systems.

• DisassemblyHelper (src/DisassemblyHelper.cs): Helper class for adding disassembly (deconstruction) formulas to custom items at runtime.

Disassembly System Pattern

The game's disassembly system uses DecomposeDatabase (singleton in Duckov.Economy namespace) to store formulas. Key implementation details:

Types:

• DecomposeFormula: Contains item (TypeID), valid (bool), and result (Cost)
• Cost: A struct with money (long) and items (ItemEntry[])
• Cost+ItemEntry: Nested struct inside Cost with id (int) and amount (long)

Critical Reflection Pattern (Cost is a struct):

// Cost is a VALUE TYPE - must box before reflection, then unbox
Cost result = new Cost { money = 0L };
object boxedResult = result;           // Box the struct
itemsField.SetValue(boxedResult, itemEntries);  // Modify boxed copy
result = (Cost)boxedResult;            // Unbox back
formula.result = result;

Adding a Formula:

1. Get DecomposeDatabase.Instance
2. Access private entries field via reflection
3. Create DecomposeFormula with item TypeID and valid = true
4. Create Cost with money and/or items array
5. For items: Create Cost+ItemEntry[] via reflection (type found from Cost.items field type)
6. Add formula to list, write back via reflection
7. Call private RebuildDictionary() method

Known Material TypeIDs:

• Polyethylene Sheet: 764

Cleanup: Track added item IDs and remove formulas in OnDestroy().

See DisassemblyHelper.cs for complete implementation.

Dependencies

• HarmonyLoadMod (Workshop ID: 3589088839): Required mod dependency providing Harmony 2.4.1. Referenced at build time but not bundled to avoid version conflicts.

• ModConfig (Workshop ID: 3592433938): Optional mod dependency. When installed, enhances card descriptions with set information in the inventory UI.

Card Definition Format

Cards are defined in CardSets/{SetName}/cards.txt using pipe-separated values:

CardName | SetName | SetNumber | ImageFile | Rarity | Weight | Value | Description (optional)

The Description field is optional. If provided, it will be displayed in the item's in-game description/tooltip.

Images go in CardSets/{SetName}/images/.

Disabling Card Sets: Prefix a card set folder name with _ (underscore) to exclude it from loading. For example, _TestSet/ will be skipped. This is useful for work-in-progress sets or seasonal content. The count of disabled sets is displayed in ModConfig.

Game API Reference

Key namespaces and APIs from the game:

• ItemStatsSystem.ItemAssetsCollection.AddDynamicEntry(Item prefab) - Register custom items
• ItemStatsSystem.ItemAssetsCollection.RemoveDynamicEntry(Item prefab) - Remove on unload
• SodaCraft.Localizations.LocalizationManager.SetOverrideText(string key, string value) - Localization
• ItemStatsSystem.ItemUtilities.SendToPlayer(Item item) - Give items to player

Development Notes

• Target framework: .NET Standard 2.1
• C# language version: 8.0
• All logging uses Debug.Log() with [TradingCardMod] prefix
• Custom items need unique TypeIDs to avoid conflicts with base game and other mods

Testing

1. Copy build output to {GamePath}/Duckov_Data/Mods/TradingCardMod/
2. Include: TradingCardMod.dll, info.ini, preview.png, CardSets/ folder
3. Launch game and enable mod in Mods menu
4. Check game logs for [TradingCardMod] messages

Current Project Status

Phase: 3 - Storage System ✅ Status: Ready for first release Project Plan: .claude/scratchpad/PROJECT_PLAN.md Technical Analysis: .claude/scratchpad/item-system-analysis.md

Completed Features

• Cards load from CardSets/*/cards.txt files with optional descriptions
• Custom PNG images display as item icons
• Cards register as game items with proper TypeIDs
• Custom tags for slot filtering:
  • "TradingCard": Identifies trading cards
  • "BinderSheet": Identifies binder sheet items
  • "CardBinderContent": Parent tag for both cards and binder sheets (enables hierarchical storage)
• Hierarchical storage system:
  • Binder Sheet (9 slots, weight 0.1): Holds trading cards only
  • Card Binder (12 slots, weight 1.5): Holds trading cards OR binder sheets
  • Nested storage: Cards → Binder Sheets → Card Binders
• Card set exclusion: Prefix folders with _ to disable loading
• ModConfig integration:
  • Enhanced card info display (set name, number, rarity)
  • Mod statistics display (total cards, disabled sets)
• Debug spawn window with F10 key (for testing):
  • Spawn storage items (Card Binder, Binder Sheet)
  • Spawn random cards by rarity
  • Draggable OnGUI window interface
• Disassembly support for storage items:
  • Binder Sheet → 2x Polyethylene Sheet
  • Card Binder → 4x Polyethylene Sheet
  • Cards intentionally have no disassembly (collectibles)
• Deploy/remove scripts for quick iteration
• Unit tests for parsing logic

Implementation Approach: Clone + Reflection

Based on analysis of the AdditionalCollectibles mod:

1. Clone existing game items as templates (base item ID 135)
2. Use reflection to set private fields (typeID, weight, value, etc.)
3. Create custom tags by cloning existing ScriptableObject tags
4. Parent tag pattern for slot filtering (Unity's requireTags uses AND logic, so parent tags enable OR-like behavior)
5. Load sprites from user files in CardSets/*/images/
6. Attach custom behaviors for pack opening mechanics

Upcoming Features

• Card packs with gacha-style mechanics (weighted random distribution) - disabled pending fix
• Additional storage variants or customization options (e.g., larger binders, themed storage boxes)

Future Considerations

• Investigate new ItemBuilder API (added in recent game update) as potential replacement for reflection-based approach

Log File Location

Unity logs (for debugging):

/mnt/NV2/SteamLibrary/steamapps/compatdata/3167020/pfx/drive_c/users/steamuser/AppData/LocalLow/TeamSoda/Duckov/Player.log

Research References

• Decompiled game code: .claude/scratchpad/decompiled/
• Item system analysis: .claude/scratchpad/item-system-analysis.md
• AdditionalCollectibles mod: Workshop ID 3591453758 (reference implementation)