broadfield-dev/stack-overflow-game

1# Troubleshooting Guide2 3## Common Issues4 5### Game doesn't load / Black screen6 71. **Check browser console** (F12) for errors82. **Verify assets are generated**:9   ```bash10   npm run generate-assets11   ```123. **Clear browser cache** and reload (Cmd+Shift+R or Ctrl+Shift+R)13 14### Audio doesn't play15 16- **Browser autoplay policy**: Most browsers block audio until user interaction17- The game requires you to press SPACE to start, which should enable audio18- Check browser console for audio-related errors19- Verify music files exist in `public/assets/music/level-X/track.mp3`20 21### Blocks don't appear or wrong colors22 23- **Color extraction issue**: Make sure backdrop images are valid PNG files24- **Texture generation**: Check browser console for WebGL errors25- Try refreshing the page26 27### Controls not working28 29- Make sure the game window has focus (click on it)30- Check that you're using arrow keys and spacebar31- Verify no browser extensions are intercepting keyboard events32 33### Performance issues34 35- The game uses pixel-perfect rendering which is GPU-intensive36- Try closing other browser tabs37- Check if hardware acceleration is enabled in browser settings38 39## Development Issues40 41### Canvas module installation fails42 43If `npm install canvas` fails on your system:44 451. The placeholder generation will skip backdrop creation462. You can manually create 256×224 PNG files and place them in:47   ```48   public/assets/backdrops/level-X/backdrop.png49   ```50 51### Vite build errors52 53- Make sure you're using Node.js version 14 or higher54- Delete `node_modules` and `package-lock.json`, then run `npm install` again55 56### Module import errors57 58- Verify `"type": "module"` is in package.json59- Check that all import paths use `.js` extensions60 61## Testing Checklist62 63- [ ] Game loads and shows "LOADING..." then "PRESS SPACE TO START"64- [ ] Pressing SPACE starts the game65- [ ] Backdrop is visible66- [ ] Tetris pieces appear and are colored67- [ ] Arrow keys move pieces left/right68- [ ] Up arrow rotates pieces69- [ ] Down arrow soft drops70- [ ] Space bar hard drops71- [ ] Lines clear when complete72- [ ] Score updates73- [ ] Level increases after 20 lines74- [ ] Backdrop, music, and colors change on level up75- [ ] Ghost piece shows on level 1 only76- [ ] Game over screen appears when pieces stack to top77 78## Browser Compatibility79 80Tested on:81- Chrome/Edge (recommended)82- Firefox83- Safari84 85Requires:86- WebGL support87- ES6 module support88- Web Audio API89 90## Getting Help91 92If you encounter issues:93 941. Check the browser console (F12) for error messages952. Verify all files are in the correct locations963. Make sure the dev server is running (`npm run dev`)974. Try a different browser985. Check that all dependencies are installed (`npm install`)99 100