| # Troubleshooting Guide |
|
|
| ## Common Issues |
|
|
| ### Game doesn't load / Black screen |
|
|
| 1. **Check browser console** (F12) for errors |
| 2. **Verify assets are generated**: |
| ```bash |
| npm run generate-assets |
| ``` |
| 3. **Clear browser cache** and reload (Cmd+Shift+R or Ctrl+Shift+R) |
|
|
| ### Audio doesn't play |
|
|
| - **Browser autoplay policy**: Most browsers block audio until user interaction |
| - The game requires you to press SPACE to start, which should enable audio |
| - Check browser console for audio-related errors |
| - Verify music files exist in `public/assets/music/level-X/track.mp3` |
|
|
| ### Blocks don't appear or wrong colors |
|
|
| - **Color extraction issue**: Make sure backdrop images are valid PNG files |
| - **Texture generation**: Check browser console for WebGL errors |
| - Try refreshing the page |
|
|
| ### Controls not working |
|
|
| - Make sure the game window has focus (click on it) |
| - Check that you're using arrow keys and spacebar |
| - Verify no browser extensions are intercepting keyboard events |
|
|
| ### Performance issues |
|
|
| - The game uses pixel-perfect rendering which is GPU-intensive |
| - Try closing other browser tabs |
| - Check if hardware acceleration is enabled in browser settings |
|
|
| ## Development Issues |
|
|
| ### Canvas module installation fails |
|
|
| If `npm install canvas` fails on your system: |
|
|
| 1. The placeholder generation will skip backdrop creation |
| 2. You can manually create 256×224 PNG files and place them in: |
| ``` |
| public/assets/backdrops/level-X/backdrop.png |
| ``` |
|
|
| ### Vite build errors |
|
|
| - Make sure you're using Node.js version 14 or higher |
| - Delete `node_modules` and `package-lock.json`, then run `npm install` again |
|
|
| ### Module import errors |
|
|
| - Verify `"type": "module"` is in package.json |
| - Check that all import paths use `.js` extensions |
|
|
| ## Testing Checklist |
|
|
| - [ ] Game loads and shows "LOADING..." then "PRESS SPACE TO START" |
| - [ ] Pressing SPACE starts the game |
| - [ ] Backdrop is visible |
| - [ ] Tetris pieces appear and are colored |
| - [ ] Arrow keys move pieces left/right |
| - [ ] Up arrow rotates pieces |
| - [ ] Down arrow soft drops |
| - [ ] Space bar hard drops |
| - [ ] Lines clear when complete |
| - [ ] Score updates |
| - [ ] Level increases after 20 lines |
| - [ ] Backdrop, music, and colors change on level up |
| - [ ] Ghost piece shows on level 1 only |
| - [ ] Game over screen appears when pieces stack to top |
|
|
| ## Browser Compatibility |
|
|
| Tested on: |
| - Chrome/Edge (recommended) |
| - Firefox |
| - Safari |
|
|
| Requires: |
| - WebGL support |
| - ES6 module support |
| - Web Audio API |
|
|
| ## Getting Help |
|
|
| If you encounter issues: |
|
|
| 1. Check the browser console (F12) for error messages |
| 2. Verify all files are in the correct locations |
| 3. Make sure the dev server is running (`npm run dev`) |
| 4. Try a different browser |
| 5. Check that all dependencies are installed (`npm install`) |
|
|
|
|
