jass-learner/CLAUDE.md

Card Framework - Claude Code Project Guide

Project Overview

Card Framework is a professional-grade Godot 4.x addon for creating 2D card games. This lightweight, extensible toolkit supports various card game genres from classic Solitaire to complex TCGs and deck-building roguelikes.

Key Characteristics

• Target Engine: Godot 4.4.1
• Architecture: Modular addon with factory patterns and inheritance hierarchy
• License: Open source with CC0 assets
• Status: Production-ready (v1.1.3) with comprehensive examples

Architecture Overview

Core Components

CardManager (Root orchestrator)
├── CardFactory (Abstract) → JsonCardFactory (Concrete)
├── CardContainer (Abstract) → Pile/Hand (Specialized containers)
├── Card (extends DraggableObject)
└── DropZone (Interaction handling)

Design Patterns in Use

• Factory Pattern: Flexible card creation via CardFactory/JsonCardFactory
• Template Method: CardContainer with overridable methods for game-specific logic
• Observer Pattern: Event-driven card movement and interaction callbacks
• Strategy Pattern: Pluggable drag-and-drop via DraggableObject inheritance

File Structure

• addons/card-framework/ - Core framework code
• example1/ - Basic demonstration project
• freecell/ - Complete FreeCell game implementation
• project.godot - Godot 4.4+ project configuration

Development Guidelines

Code Standards

1. GDScript Best Practices

   • Use strong typing: func create_card(name: String) -> Card
   • Follow naming conventions: card_container, front_face_texture
   • Document public APIs with ## comments
   • Use @export for designer-configurable properties

2. Godot 4.x Compliance

   • Use class_name declarations for reusable classes
   • Prefer @onready for node references
   • Use signals for decoupled communication
   • Leverage Resource system for configuration (Curve resources)

3. Framework Architecture Rules

   • Inherit from CardContainer for new container types
   • Extend CardFactory for custom card creation logic
   • Use CardManager as the central orchestrator
   • Maintain JSON compatibility for card data when using JsonCardFactory

Extension Patterns

Creating Custom Card Containers

class_name MyCustomContainer
extends CardContainer

func check_card_can_be_dropped(cards: Array) -> bool:
	# Implement game-specific rules
	return true

func add_card(card: Card, index: int = -1) -> void:
	# Custom card placement logic
	super.add_card(card, index)

Extending Card Properties

class_name GameCard
extends Card

@export var power: int
@export var cost: int
@export var effect: String

func _ready():
	super._ready()
	# Initialize custom properties from card_info

Claude Code Usage Patterns

Quick Commands for Development

Analysis and Exploration

# Analyze specific components
/godot-analyze Card
/godot-analyze CardContainer
/godot-analyze "drag and drop system"

# Review architecture
/analyze addons/card-framework/ --focus architecture

Implementation Tasks

# Add new features
/godot-implement "deck shuffling animation"
/godot-implement "card effect system" 

# Create custom containers
/godot-implement "discard pile with auto-organize"

Testing and Validation

# Create tests
/godot-test unit Card
/godot-test integration "hand reordering"
/godot-test performance "large deck handling"

Development Workflow

1. Understanding Existing Code

• Start with /godot-analyze [component] to understand structure
• Use /analyze for deeper architectural investigation
• Read example implementations in freecell/ for complex patterns

2. Planning New Features

• Create task breakdown using TodoWrite
• Consider compatibility with existing CardContainer interface
• Plan JSON schema changes if extending card properties

3. Implementation Best Practices

• Always extend base classes rather than modifying core framework
• Test with both example1 and freecell projects
• Maintain backwards compatibility with existing JSON card data

4. Quality Assurance

• Run both example scenes to verify functionality
• Check performance with large card collections
• Validate proper cleanup and memory management

Key Configuration Areas

CardManager Setup

• card_size: Default dimensions for all cards
• card_factory_scene: Factory responsible for card creation
• debug_mode: Enable visual debugging for drop zones

CardFactory Configuration

• card_asset_dir: Location of card image assets
• card_info_dir: Directory containing JSON card definitions
• back_image: Default card back texture

JSON Card Schema

{
	"name": "card_identifier",
	"front_image": "texture_filename.png",
	"suit": "optional_game_data",
	"value": "additional_properties"
}

Common Implementation Patterns

Card Movement and Animation

• Use card.move(target_position, rotation) for programmatic movement
• Leverage moving_speed property for consistent animation timing
• Handle movement completion via on_card_move_done() callbacks

Game Rules Implementation

• Override check_card_can_be_dropped() in custom containers
• Use move_cards() with history tracking for undo/redo support
• Implement game state validation in container logic

Performance Optimization

• Preload card data using factory.preload_card_data()
• Limit visual card display with max_stack_display in Pile containers
• Use debug_mode to identify performance bottlenecks

Integration Points

Asset Pipeline

• Card images in card_asset_dir (typically PNG format)
• JSON metadata in card_info_dir matching image filenames
• Support for Kenney.nl asset packs (included in examples)

Scene Structure

• CardManager as root node in card-enabled scenes
• CardContainers as children of CardManager
• Cards instantiated dynamically via factory pattern

Extensibility Hooks

• Virtual methods in CardContainer for custom behavior
• Card property extensions via inheritance
• Factory pattern for alternative card creation strategies

Task Master AI Integration

This project includes Task Master AI for advanced project management:

# Initialize task tracking
task-master init

# Create tasks from project requirements
task-master parse-prd .taskmaster/docs/prd.txt

# Track development progress
task-master next    # Get next task
task-master show <id>    # View task details
task-master set-status --id=<id> --status=done

See .taskmaster/CLAUDE.md for detailed Task Master workflows.

Troubleshooting Guide

Common Issues

• Cards not appearing: Check card_asset_dir path and file naming
• JSON loading errors: Verify JSON syntax and required fields
• Drag-and-drop issues: Ensure CardContainer has enable_drop_zone = true
• Performance problems: Use debug_mode to visualize sensor areas

Debug Tools

• Enable debug_mode in CardManager for visual debugging
• Use Godot's remote inspector for runtime state examination
• Check console output for framework-specific error messages

---

This project demonstrates professional Godot addon development with comprehensive documentation, clean architecture, and production-ready examples. It serves as an excellent foundation for 2D card game development.

Task Master AI Instructions

Import Task Master's development workflow commands and guidelines, treat as if import is in the main CLAUDE.md file. @./.taskmaster/CLAUDE.md