trenchlock/TETROMINO_SELECTOR.md

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