jass-learner/docs/GETTING_STARTED.md

Getting Started with Card Framework

Complete step-by-step guide to set up and use the Card Framework in your Godot 4.x projects.

Prerequisites

• Godot Engine 4.4+ installed
• Basic knowledge of Godot scenes and nodes
• Understanding of GDScript fundamentals

Installation Methods

Method 1: AssetLib Installation (Recommended)

1. Open Godot Editor and create or open your project
2. Navigate to AssetLib tab in the main editor
3. Search for "Card Framework"
4. Download and import the latest version
5. Verify Installation - Check res://addons/card-framework/ exists

Method 2: Manual Installation

1. Download Card Framework from the repository
2. Extract the contents to your project
3. Copy the addons/card-framework/ folder to res://addons/
4. Refresh the FileSystem dock in Godot

Project Setup

Step 1: Scene Structure

Create your main game scene with this hierarchy:

Main (Node2D)
└── CardManager (CardManager)
	├── Deck (Pile)
	├── PlayerHand (Hand) 
	└── DiscardPile (Pile)

Step 2: CardManager Configuration

1. Add CardManager Scene

   • In your main scene, Add Child Node
   • Instance res://addons/card-framework/card_manager.tscn

2. Configure Basic Properties

   Card Size: (150, 210)          # Standard playing card dimensions
   Debug Mode: false              # Enable for development
   

3. Create Your Card Factory Instead of using the card factory directly, create your own:

   Option A: Inherit from JsonCardFactory (Recommended)

   • Create New Scene → Add Node → JsonCardFactory
   • Save as res://scenes/my_card_factory.tscn
   • Set card_factory_scene to res://scenes/my_card_factory.tscn

   Option B: Create Custom Factory

   • Create New Scene → Add Node → CardFactory
   • Attach Script and implement create_card() method
   • Save as res://scenes/my_card_factory.tscn

Step 3: Directory Structure Setup

Create this folder structure in your project:

res://
├── cards/
│   ├── images/          # Card artwork
│   └── data/           # JSON card definitions
└── scenes/
	└── main.tscn       # Your main scene

Step 4: Card Assets Preparation

4.1 Card Images

• Format: PNG recommended (supports transparency)
• Size: 150x210 pixels for standard cards
• Naming: Use descriptive names (e.g., cardClubs2.png, cardHeartsK.png)
• Location: Store in res://cards/images/

4.2 Card Data Files

Create JSON files in res://cards/data/ for each card:

Example: club_2.json

{
	"name": "club_2",
	"front_image": "cardClubs2.png",
	"suit": "club",
	"value": "2",
	"color": "black"
}

Required Fields:

• name - Unique identifier for the card
• front_image - Filename of the card's front texture

Optional Fields:

• Add any custom properties needed for your game logic

Step 5: Card Factory Configuration

If using JsonCardFactory (Option A from Step 2):

Open your my_card_factory.tscn scene and configure the JsonCardFactory node:

Card Asset Dir: "res://cards/images/"
Card Info Dir: "res://cards/data/"
Back Image: [Assign a card back texture]
Default Card Scene: [Assign custom card scene - required field]

If using Custom Factory (Option B):

• Implement your own card creation logic in the attached script
• No additional configuration needed here

Step 6: Container Setup

6.1 Adding Containers

Add container nodes as children of CardManager:

1. Right-click CardManager in Scene dock
2. Add Child → Choose container type:
   • Pile for stacked cards (decks, discard piles)
   • Hand for fanned card layouts (player hands)
3. Position Containers
   • Select each container in the Scene dock
   • In Inspector → Transform → Position, set appropriate coordinates:
     • Example: Deck at (100, 300), PlayerHand at (400, 500), DiscardPile at (700, 300)
   • Adjust positions based on your game screen size and layout needs

6.2 Pile Configuration

Basic Properties:

Enable Drop Zone: true
Card Face Up: false             # For deck, true for discard
Layout: UP                      # Stack direction
Allow Card Movement: true
Restrict To Top Card: true      # Only top card moveable

Visual Properties:

Stack Display Gap: 8            # Pixel spacing between cards
Max Stack Display: 6           # Maximum visible cards

6.3 Hand Configuration

Layout Properties:

Max Hand Size: 10
Max Hand Spread: 700           # Pixel width of fanned cards
Card Face Up: true
Card Hover Distance: 30        # Hover effect height

Required Curves (Create in Inspector):

• Hand Rotation Curve: 2-point linear curve for card rotation
• Hand Vertical Curve: 3-point curve for arc shape (0→1→0)

Step 7: Basic Scripting

Add this script to your main scene to start using cards:

extends Node2D

@onready var card_manager = $CardManager
@onready var deck = $CardManager/Deck
@onready var player_hand = $CardManager/PlayerHand

func _ready():
    setup_game()

func setup_game():
    # Create a deck of cards
    create_standard_deck()
    
    # Deal initial hand
    deal_cards_to_hand(5)

func create_standard_deck():
    var suits = ["club", "diamond", "heart", "spade"]
    var values = ["A", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K"]
    
    for suit in suits:
        for value in values:
            var card_name = "%s_%s" % [suit, value]
            var card = card_manager.card_factory.create_card(card_name, deck)
            deck.add_card(card)

func deal_cards_to_hand(count: int):
    for i in count:
        if deck.get_card_count() > 0:
            var card = deck.get_top_cards(1).front()
            player_hand.move_cards([card])

Testing Your Setup

Quick Test Checklist

1. Run Your Scene - Press F6 and select your main scene
2. Verify Cards Appear - You should see cards in your containers
3. Test Interactions - Try dragging cards between containers
4. Check Debug Mode - Enable in CardManager to see drop zones
5. Console Errors - Ensure no error messages appear

Common Issues

Cards Not Appearing:

• Verify JSON files exist and match card names
• Check card_asset_dir and card_info_dir paths
• Ensure image files exist in the asset directory

Drag and Drop Issues:

• Confirm enable_drop_zone is true on containers
• Check that can_be_interacted_with is true on cards
• Verify container positions don't overlap incorrectly

JSON Loading Errors:

• Validate JSON syntax using online validator
• Ensure required name and front_image fields exist
• Check for typos in field names

Next Steps

Explore Sample Projects

• example1/ - Basic demonstration of all container types
• freecell/ - Complete game implementation with custom rules

Advanced Customization

• API Reference - Complete class documentation
• Creating Custom Containers
• Custom Card Properties

Performance Optimization

• Use preload_card_data() for better loading performance
• Implement object pooling for frequently created/destroyed cards
• Consider max_stack_display for large piles

---

Need Help? Check the API Documentation or examine the sample projects for working examples.