# Tetromino Selector System

## Overview
Adds interactive tetromino selection and repositioning during gameplay. Players can select already-
placed tetrominoes, move them, rotate them, and place them in new positions.

## Components

### 1. TetrominoSelector (scripts/tetromino_selector.gd)

Main controller for tetromino selection logic.

**Features:**
- Raycast-based tetromino detection on left-click from camera to world
- Real-time position tracking with mouse movement

- Ghost mode visualization (semi-transparent)
- Placement validation using board manager
- Rotation with spacebar (45° increments)
- Cancellation with right-click or ESC key

**Signals:**
- `tetromino_selected(tetromino: Tetromino)` - Fired when a tetromino is selected
- `tetromino_deselected(tetromino: Tetromino)` - Fired when selection is cancelled
- `selection_placed(tetromino: Tetromino)` - Fired when tetromino is placed

**Controls:**
- **Left Click** - Select tetromino or place selected tetromino
- **Right Click / ESC** - Cancel selection
- **Spacebar** - Rotate selected tetromino 45°
- **Mouse Movement** - Move ghost tetromino (updates position on Y=0 plane)

### 2. Tetromino (scripts/tetromino.gd) - Updated
Added ghost mode support to tetromino script.

**New Methods:**
- `set_ghost_mode(enabled: bool)` - Enables/disables ghost appearance
  - When enabled: tetromino becomes 50% transparent with original color
  - When disabled: tetromino returns to original appearance

**New Variables:**
- `_is_ghost: bool` - Tracks if tetromino is in ghost mode
- `_original_color: Color` - Stores original color for restoration

### 3. Board Scene (scenes/board/board.tscn) - Updated
Added TetrominoSelector node to board hierarchy.

**Changes:**
- Added TetrominoSelector as child of Board node
- Selector has access to BoardManager3D parent
- Integrated into existing board scene structure

### 4. Tetromino Scene (scenes/board/tetromino.tscn) - Updated
Added collision detection for raycast selection.

**Changes:**
- Added SelectionArea (Area3D) node
- Added CollisionShape3D with BoxShape3D for raycast detection
- Enables click detection on tetromino mesh

## Workflow

1. **Selection Phase**
   - Player left-clicks on a placed tetromino
   - Selector raycasts from camera through mouse position
   - If tetromino hit, it enters ghost mode (semi-transparent)
   - Signals emit `tetromino_selected`

2. **Movement Phase**
   - Player moves mouse to new position
   - Ghost tetromino tracks mouse position in real-time
   - Position snaps to grid coordinates
   - Clamped to valid board bounds

3. **Rotation Phase**
   - Player presses spacebar to rotate ghost 45°
   - Rotation applied around Y-axis
   - Updates visual representation

4. **Placement Phase**
   - Player left-clicks to place
   - Selector validates placement using BoardManager3D._can_place_tetromino()
   - If valid:
	 - Updates board manager occupied cells
	 - Tetromino exits ghost mode
	 - Signals emit `selection_placed`
   - If invalid:
	 - Tetromino snaps back to original position
	 - Reverts to original rotation

5. **Cancellation**
   - Player right-clicks or presses ESC
   - Tetromino reverts to original position and rotation
   - Tetromino exits ghost mode
   - Signals emit `tetromino_deselected`

## Integration Points

### Board Manager
- Uses `_can_place_tetromino()` for validation
- Modifies `_occupied_cells` dictionary directly
- Respects grid bounds and collision rules

### Tetromino Script
- Calls `set_ghost_mode()` for visual feedback
- Tracks grid_position and rotation_quat
- Provides `get_grid_cells()` for collision checking

### Input System
- Listens to input events (_input callback)
- Handles mouse clicks, movement, and keyboard input
- Calls `get_tree().root.set_input_as_handled()` to consume inputs

## Notes
- Ghost mode requires material initialization to display transparency
- Position clamping prevents out-of-bounds placement attempts
- Rotation validation happens before placement
- Only one tetromino can be selected at a time
- Original position/rotation saved for cancellation