init

2026-03-09 19:18:47 +01:00
commit ade3d0fb01
240 changed files with 12324 additions and 0 deletions
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@@ -0,0 +1,254 @@
+# 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`**
+```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:
+
+```gdscript
+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](API.md) - Complete class documentation
+- [Creating Custom Containers](API.md#extending-cardcontainer)
+- [Custom Card Properties](API.md#extending-card)
+
+### 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](API.md) or examine the sample projects for working examples.