# CLAUDE.md

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

## Project Overview

This is a Godot 4.5 game project for "time-is-mana", a prototype for a roguelike deckbuilder with team-based, spatial combat system.

## Development Environment

**Engine:** Godot 4.5 with GL Compatibility rendering

**Project Structure:**
- `project.godot` - Main Godot project configuration file
- `icon.svg` - Project icon
- `.godot/` - Godot-generated files (ignored by git)

## Common Commands

**Running the game:**
Open the project in Godot Editor and press F5, or run:
```
godot --path .
```

**Exporting the game:**
Use the Godot Editor's Project > Export menu, or:
```
godot --export-release <preset_name> <output_path>
```

**Editing scenes/scripts:**
The project should be opened and edited through the Godot Editor. GDScript files (.gd) and scene files (.tscn) are text-based and can be edited externally, but the Godot Editor provides essential tooling for scene composition and resource management.

## Game Design

**Genre:** Tactical roguelike deckbuilder with spatial combat
**Prototype Focus:** Combat system (meta-progression deferred to later)
**Core Mechanics:** Encounter-based, timeline-driven card combat on a free-form spatial combat field

### Heroes & Card Colors

The game features three heroes, each associated with a specific card color:
- **Red**: Phoenix, tank, dps
- **Green**: Blob, tank, summoner
- **Black**: Vampire, offensive healer

Cards in the player's hand correspond to these hero colors, determining which character executes the card's action.

### Combat System

**Spatial Field:**
- Free-form tactical positioning (similar to Fire Emblem, XCOM)
- Characters and enemies occupy space on combat field (circle colliders for now)
- Cards have different ranges, effect patterns, and area-of-effect shapes

**Targeting System:**
- Proximity-based targeting with cursor/crosshair
- Drag cards from hand to initiate targeting
- Valid targets highlighted based on card range and effect area
- Close-range cards (e.g., Strike) require adjacent positioning

**Timeline Execution:**
Cards do not execute instantaneously. Instead, they follow a three-phase timeline system (similar to Caligula Effect Overdose's imaginary chain):
1. **Wind-up**: Preparation phase before effect
2. **Effect**: Active execution of the card's ability
3. **Recover**: Cooldown phase after effect

**Action Queuing:**
- Players can queue multiple cards for a single character
- Queued cards are added to that character's timeline in sequence
- Queuing preserves cards beyond the hand refresh cycle

**Time Progression:**
Time advances under two conditions:
1. All characters have queued actions/effects
2. Player presses the "progress time" button

During time progression, all queued actions execute based on their timeline positions.

### Hand Management

- Hand refreshes automatically every ~4 seconds
- Unplayed cards move to discard pile
- New cards drawn from deck to replace discarded cards
- Queuing cards preserves them beyond refresh cycles

### Enemy System

- Multiple enemies per encounter
- **Predictive Attacks**: Enemies show their intentions before acting
  - Display action type
  - Show timing on timeline
  - Indicate target(s)
- This enables tactical counterplay and planning

### Design Philosophy

Focus on tactical depth through:
- Spatial positioning and movement
- Timeline-based action sequencing
- Hand management and card preservation
- Predicting and countering enemy actions

Strategic meta-progression (roguelike elements between runs) is deferred for this prototype.

## System Architecture

### Core Systems

1. **Card System**
   - Card Resources with properties: color, wind-up/effect/recover durations, range, effect patterns
   - Hand manager with auto-refresh timer
   - Deck and discard pile management

2. **Combat Field System**
   - Free-form spatial field
   - Position tracking and movement validation
   - Range and distance calculations
   - Effect area visualization

3. **Character System**
   - Hero base class for three hero types
   - Enemy base class with AI behavior
   - Stats, health, positioning

4. **Timeline System** (Core Mechanic)
   - Per-character or global action queue
   - Phase tracking (wind-up/effect/recover)
   - Time progression logic
   - Timeline visualization

5. **Targeting System**
   - Proximity detection
   - Cursor/crosshair control
   - Valid target highlighting
   - Effect area preview

6. **AI/Enemy Intent System**
   - Enemy decision-making
   - Predictive attack display (action, timing, targets)

7. **UI System**
   - Hand visualization
   - Timeline visualization
   - Targeting cursor
   - Progress time button
   - Enemy intent indicators

8. **Encounter System**
   - Setup/initialization
   - Victory/defeat conditions
   - State management

### Godot Implementation Patterns

- **Resources** for card definitions (serializable, reusable)
- **Signals** for timeline events, card plays, time progression
- **Area2D** for proximity detection
- **AnimationPlayer** for card phase timing
- **Tween** for smooth visual transitions
- Scene inheritance for character variants

### Suggested Directory Structure

```
scripts/
  cards/          - Card system and hand management
  combat/         - Combat field, targeting, timeline systems
  characters/     - Hero and enemy scripts
  ui/             - UI components
scenes/
  characters/     - Hero and enemy scenes
  combat/         - Combat encounter scenes
resources/
  cards/          - Card definitions
```