117 lines
4.0 KiB
Markdown
117 lines
4.0 KiB
Markdown
# 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
|