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

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.

Dependencies

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

Card Definition Format

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

CardName | SetName | SetNumber | ImageFile | Rarity | Weight | Value

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

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: 2 Complete - Core Card Framework ✅ Next Phase: 3 - Storage System (Binders) Project Plan: .claude/scratchpad/PROJECT_PLAN.md Technical Analysis: .claude/scratchpad/item-system-analysis.md

Completed Features

• Cards load from CardSets/*/cards.txt files
• Custom PNG images display as item icons
• Cards register as game items with proper TypeIDs
• Custom "TradingCard" tag for filtering
• Debug spawn with F9 key (for testing)
• Deploy/remove scripts for quick iteration

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. Load sprites from user files in CardSets/*/images/

Next Implementation Steps

Phase 3 - Storage System:

1. Research existing storage items in game
2. Create binder item with Inventory component
3. Implement slot-based filtering for "TradingCard" tag
4. Create card box variant with higher capacity

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)