|
| 1 | +# Static Chess - Architecture Documentation |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +Static Chess is a pure vanilla implementation of chess using HTML, CSS, and JavaScript without any frameworks or libraries. This document outlines the architecture, component interactions, and guidelines for implementing future features. |
| 6 | + |
| 7 | +## Project Structure |
| 8 | + |
| 9 | +``` |
| 10 | +Static_Chess/ |
| 11 | +├── index.html # Main HTML entry point |
| 12 | +├── css/ # CSS styles |
| 13 | +│ ├── style.css # General page styles |
| 14 | +│ ├── board.css # Chessboard specific styles |
| 15 | +│ └── pieces.css # Chess pieces styles |
| 16 | +├── js/ # JavaScript logic |
| 17 | +│ ├── config.js # Game configuration and feature flags |
| 18 | +│ ├── utils.js # Utility functions |
| 19 | +│ ├── pieces.js # Piece definitions and movement rules |
| 20 | +│ ├── board.js # Board rendering and interaction |
| 21 | +│ ├── game.js # Core game logic |
| 22 | +│ ├── main.js # Application entry point |
| 23 | +│ ├── drag.js # Skeleton for drag and drop functionality |
| 24 | +│ ├── ai.js # Skeleton for AI opponent |
| 25 | +│ └── promotion.js # Skeleton for pawn promotion UI |
| 26 | +├── assets/ # SVG files for chess pieces |
| 27 | +│ ├── wp.svg, bp.svg # Pawns |
| 28 | +│ ├── wr.svg, br.svg # Rooks |
| 29 | +│ ├── wn.svg, bn.svg # Knights |
| 30 | +│ ├── wb.svg, bb.svg # Bishops |
| 31 | +│ ├── wq.svg, bq.svg # Queens |
| 32 | +│ └── wk.svg, bk.svg # Kings |
| 33 | +└── docs/ # Documentation |
| 34 | + ├── ARCHITECTURE.md # This document |
| 35 | + └── ROADMAP.md # Development roadmap |
| 36 | +``` |
| 37 | + |
| 38 | +## Component Interaction Flow |
| 39 | + |
| 40 | +1. **main.js**: Application entry point |
| 41 | + - Initializes settings and event listeners |
| 42 | + - Calls `initializeGame()` from game.js |
| 43 | + |
| 44 | +2. **game.js**: Core game logic |
| 45 | + - Manages game state, turn management, move validation |
| 46 | + - Delegates rendering to board.js |
| 47 | + - Uses piece movement rules from pieces.js |
| 48 | + |
| 49 | +3. **board.js**: UI representation of the chess board |
| 50 | + - Renders the board and pieces |
| 51 | + - Handles interactions (clicks, drags) |
| 52 | + - Updates visual state (highlighting, animations) |
| 53 | + |
| 54 | +4. **pieces.js**: Chess piece definitions |
| 55 | + - Defines piece types and their basic movement patterns |
| 56 | + - Provides functions for initial board setup |
| 57 | + |
| 58 | +5. **utils.js**: Helper functions |
| 59 | + - Coordinate conversions (algebraic notation) |
| 60 | + - localStorage management |
| 61 | + - General utility functions |
| 62 | + |
| 63 | +6. **config.js**: Centralized configuration |
| 64 | + - Feature flags for enabling/disabling features |
| 65 | + - Game constants and settings |
| 66 | + - Default user preferences |
| 67 | + |
| 68 | +## Data Flow |
| 69 | + |
| 70 | +1. User interacts with the board (clicks a square) |
| 71 | +2. `board.js` captures the event and calls the appropriate handler in `game.js` |
| 72 | +3. `game.js` validates the move using rules from `pieces.js` |
| 73 | +4. If valid, `game.js` updates the game state and calls `renderPieces()` in `board.js` |
| 74 | +5. `board.js` updates the visual representation |
| 75 | + |
| 76 | +## State Management |
| 77 | + |
| 78 | +The game state is primarily managed in `game.js` and consists of: |
| 79 | + |
| 80 | +- Current board state (2D array of pieces) |
| 81 | +- Current turn (white or black) |
| 82 | +- Move history |
| 83 | +- Game status (in progress, check, checkmate, stalemate) |
| 84 | +- Selected piece and possible moves |
| 85 | + |
| 86 | +## Skeleton Implementations |
| 87 | + |
| 88 | +Several planned features already have skeleton implementations that provide a foundation for full implementation: |
| 89 | + |
| 90 | +- **drag.js**: Basic structure for drag and drop functionality |
| 91 | +- **ai.js**: Framework for implementing the AI opponent |
| 92 | +- **promotion.js**: UI components for pawn promotion |
| 93 | + |
| 94 | +These skeleton files include commented code with clear TODOs and integration points, so they're ready to be expanded upon when implementing the features. |
| 95 | + |
| 96 | +## Implementing Future Features |
| 97 | + |
| 98 | +### 1. Drag and Drop |
| 99 | + |
| 100 | +> **Skeleton Implementation Available: `js/drag.js`** |
| 101 | +
|
| 102 | +To implement drag and drop for pieces: |
| 103 | + |
| 104 | +1. Update `config.js` to enable the DRAG_AND_DROP feature flag |
| 105 | +2. Add the `drag.js` script to `index.html`: |
| 106 | + ```html |
| 107 | + <script src="js/drag.js"></script> |
| 108 | + ``` |
| 109 | +3. Call `initDragAndDrop()` in `main.js` after initializing the game |
| 110 | +4. Complete the TODOs in `drag.js` to integrate with game logic: |
| 111 | + - Update `handleDragStart` to check if the piece can be moved |
| 112 | + - Update `handleDragEnd` to call into game.js for move validation |
| 113 | + - Implement visual feedback for possible moves during drag |
| 114 | + |
| 115 | +The skeleton already includes: |
| 116 | +- Event listeners for mouse and touch events |
| 117 | +- Drag state management |
| 118 | +- Basic visual feedback during dragging |
| 119 | + |
| 120 | +### 2. AI Opponent |
| 121 | + |
| 122 | +> **Skeleton Implementation Available: `js/ai.js`** |
| 123 | +
|
| 124 | +To implement the AI opponent: |
| 125 | + |
| 126 | +1. Update `config.js` to enable the AI_OPPONENT feature flag |
| 127 | +2. Add the `ai.js` script to `index.html`: |
| 128 | + ```html |
| 129 | + <script src="js/ai.js"></script> |
| 130 | + ``` |
| 131 | +3. Implement in `game.js`: |
| 132 | + ```javascript |
| 133 | + // Initialize AI |
| 134 | + const ai = new ChessAI(CONFIG.DEFAULT_SETTINGS.AI_DIFFICULTY); |
| 135 | + |
| 136 | + // Call AI after player move |
| 137 | + if (CONFIG.FEATURES.AI_OPPONENT && currentTurn === 'b') { |
| 138 | + ai.findBestMove(boardState, currentTurn).then(move => { |
| 139 | + // Execute AI move |
| 140 | + }); |
| 141 | + } |
| 142 | + ``` |
| 143 | +4. Complete the TODOs in `ai.js`: |
| 144 | + - Implement the `_getAllLegalMoves` method to get valid moves |
| 145 | + - Implement the `_minimax` algorithm for move evaluation |
| 146 | + - Improve the position evaluation function |
| 147 | + |
| 148 | +The skeleton already includes: |
| 149 | +- AI configuration with difficulty levels |
| 150 | +- Material-based evaluation |
| 151 | +- Promise-based API for "thinking" delays |
| 152 | +- Piece-square tables for positional evaluation |
| 153 | + |
| 154 | +### 3. Promotion Choice UI |
| 155 | + |
| 156 | +> **Skeleton Implementation Available: `js/promotion.js`** |
| 157 | +
|
| 158 | +To implement the promotion choice UI: |
| 159 | + |
| 160 | +1. Update `config.js` to enable the PROMOTION_UI feature flag |
| 161 | +2. Add the `promotion.js` script to `index.html`: |
| 162 | + ```html |
| 163 | + <script src="js/promotion.js"></script> |
| 164 | + ``` |
| 165 | +3. Call `initPromotionUI()` in `main.js` after initializing the game |
| 166 | +4. Modify pawn promotion logic in `game.js` to use the UI: |
| 167 | + ```javascript |
| 168 | + // When a pawn reaches the opposite rank |
| 169 | + if (isPawnPromotion(move)) { |
| 170 | + showPromotionModal(currentTurn, move.to.row, move.to.col) |
| 171 | + .then(promotionPiece => { |
| 172 | + // Complete the move with the chosen piece |
| 173 | + }); |
| 174 | + } |
| 175 | + ``` |
| 176 | + |
| 177 | +The skeleton already includes: |
| 178 | +- Modal dialog creation and styling |
| 179 | +- Piece selection UI |
| 180 | +- Promise-based API for waiting for user selection |
| 181 | + |
| 182 | +### 4. Game Timer |
| 183 | + |
| 184 | +To implement the chess clock: |
| 185 | + |
| 186 | +1. Add timer UI elements to the HTML |
| 187 | +2. Create a new `js/timer.js` file to manage clock state |
| 188 | +3. Integrate with `game.js` to switch active timer on move |
| 189 | +4. Add timer settings to the UI |
| 190 | +5. Update `config.js` to enable the GAME_TIMER feature flag |
| 191 | + |
| 192 | +### 5. Sound Effects |
| 193 | + |
| 194 | +To implement sound effects: |
| 195 | + |
| 196 | +1. Create an `assets/sounds/` directory with sound files |
| 197 | +2. Update `utils.js` to use the existing `playSound()` function |
| 198 | +3. Trigger sounds for key events: |
| 199 | + - Piece movement |
| 200 | + - Captures |
| 201 | + - Check/checkmate |
| 202 | + - Game end |
| 203 | +4. Update `config.js` to enable the SOUND_EFFECTS feature flag |
| 204 | + |
| 205 | +### 6. Undo Move |
| 206 | + |
| 207 | +To implement undo functionality: |
| 208 | + |
| 209 | +1. Track detailed move history in `game.js` including captured pieces |
| 210 | +2. Implement `undoLastMove()` function in `game.js` |
| 211 | +3. Add undo button to UI |
| 212 | +4. Update `config.js` to enable the UNDO_MOVE feature flag |
| 213 | + |
| 214 | +### 7. Multiple Saved Games |
| 215 | + |
| 216 | +To implement multiple saved games: |
| 217 | + |
| 218 | +1. Modify save/load functions to support named game slots |
| 219 | +2. Create a game selection/management UI |
| 220 | +3. Implement `saveCurrentGame(name)` and `loadGame(name)` functions |
| 221 | +4. Update `config.js` to define the saved games storage structure |
| 222 | + |
| 223 | +### 8. Advanced Draw Detection |
| 224 | + |
| 225 | +To implement advanced draw detection: |
| 226 | + |
| 227 | +1. Enhance `game.js` to track: |
| 228 | + - Threefold repetition (same position 3 times) |
| 229 | + - Fifty-move rule (50 moves without captures or pawn moves) |
| 230 | + - Insufficient material (e.g., K vs K, K+B vs K) |
| 231 | +2. Add draw detection to the move validation logic |
| 232 | +3. Update UI to show draw conditions |
| 233 | + |
| 234 | +### 9. Full SAN Implementation |
| 235 | + |
| 236 | +To implement complete Standard Algebraic Notation: |
| 237 | + |
| 238 | +1. Enhance the existing `formatSAN()` function in `utils.js` |
| 239 | +2. Add disambiguation (which piece moved when multiple can) |
| 240 | +3. Add support for all special moves notation |
| 241 | +4. Update move history display |
| 242 | + |
| 243 | +## Coding Standards |
| 244 | + |
| 245 | +1. **Naming Conventions**: |
| 246 | + - camelCase for variables and functions |
| 247 | + - UPPER_CASE for constants |
| 248 | + - Classes should be PascalCase (if any) |
| 249 | + |
| 250 | +2. **Documentation**: |
| 251 | + - Use JSDoc comments for functions |
| 252 | + - Document parameters, return values, and descriptions |
| 253 | + |
| 254 | +3. **Code Organization**: |
| 255 | + - Keep files small and focused on a single responsibility |
| 256 | + - Use clear separation of concerns between modules |
| 257 | + |
| 258 | +4. **Error Handling**: |
| 259 | + - Use input validation |
| 260 | + - Provide fallbacks for errors |
| 261 | + - Use console.error for important errors |
| 262 | + |
| 263 | +## Performance Considerations |
| 264 | + |
| 265 | +1. **Rendering**: Minimize DOM operations |
| 266 | +2. **Move Calculation**: Cache possible moves when possible |
| 267 | +3. **Event Handlers**: Use event delegation |
| 268 | +4. **Local Storage**: Limit the size of saved games |
| 269 | + |
| 270 | +## Testing Approach |
| 271 | + |
| 272 | +- Manual testing for core gameplay |
| 273 | +- Use debugLog() for debugging |
| 274 | +- Test across different browsers |
| 275 | +- Test responsive layout on different devices |
0 commit comments