# 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`)