Start encounter feature

TETROMINO_SELECTOR.md

@@ -0,0 +1,116 @@
+# 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
+- Ghost mode visualization (semi-transparent)
+- Real-time position tracking with mouse movement
+- Rotation with spacebar (45° increments)
+- Placement validation using board manager
+- 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