Portable ScummVM Troubleshooting: Fixes for Common Issues

Portable ScummVM Troubleshooting: Fixes for Common Issues

1. Won’t launch / crashes on startup

• Cause: Missing runtime libraries or wrong executable build.
• Fixes:
  1. Use the official portable build matching your OS/architecture (32-bit vs 64-bit).
  2. Ensure required runtimes are present (e.g., Visual C++ redistributable on Windows).
  3. Run from a local drive (some builds fail on network/locked drives).
  4. Start with default config: move or delete portable_config (.ini) to let ScummVM recreate it.
  5. Check logs: run scummvm from a terminal/command prompt to capture error output.

2. Games not detected or “No supported engine”

• Cause: Wrong game files, incorrect directory structure, or missing data files.
• Fixes:
  1. Point ScummVM to the folder containing the game’s original data files (not shortcuts).
  2. Verify files are proper originals (e.g., .AGI, .SCI, .GOB, .DAT, or game-specific folders).
  3. For CD-based games, mount or extract the CD image and point ScummVM to the mounted folder.
  4. Enable “Show unsupported games” only for debugging—prefer matching supported versions.

3. Audio problems (no sound, crackling, wrong music)

• Cause: Incorrect audio backend, sample rate mismatch, or missing codecs.
• Fixes:
  1. In ScummVM Audio settings, switch between backends (SDL, OpenAL, DirectSound) and test.
  2. Adjust sample rate and buffer size; increase buffer if crackling.
  3. Ensure volume isn’t muted at OS level and that output device is correct.
  4. For games using MIDI, install a General MIDI synth (or set SoundFont) on your OS.

4. Graphics glitches or wrong palette

• Cause: Video driver issues, scaling filters, or incorrect game settings.
• Fixes:
  1. Change video renderer (OpenGL, Direct3D, SDL) in ScummVM settings.
  2. Toggle scaling filters (nearest, linear) and disable shaders to test.
  3. Update GPU drivers; try running with integrated GPU if discrete causes issues.
  4. Use game-specific settings: adjust palette, color depth, or compatibility options.

5. Controls not responding or wrong mappings

• Cause: Input device conflicts, wrong mapping file, or focus issues.
• Fixes:
  1. Reconfigure input in ScummVM Inputs menu; set mouse/keyboard/gamepad explicitly.
  2. Disable other input managers (Steam Input, XBox Accessories) that may intercept events.
  3. Run ScummVM with elevated privileges if device access is restricted.
  4. For mouse problems, enable/disable “Relative mouse mode” depending on game.

6. Save/load failures or corrupted saves

• Cause: Read-only media, permission issues, or incompatible save formats.
• Fixes:
  1. Ensure portable folder is writable; avoid running from write-protected USB in read-only mode.
  2. Run ScummVM as a user with write permissions for the portable directory.
  3. Use ScummVM’s “Export saved games” before moving between versions; import if needed.
  4. Keep backups of save folders; try loading with an older ScummVM only as last resort.

7. Performance slow or stuttering

• Cause: High CPU usage from scaling, shaders, or emulation overhead.
• Fixes:
  1. Disable shaders and set scaling to nearest neighbor.
  2. Lower CPU/GPU load by closing background apps and power-saving modes.
  3. Use a build optimized for low-end systems (no debugging features).
  4. Enable frame limiting or VSync options appropriately.

8. Problems on mobile (Android/iOS)

• Cause: File paths, storage permissions, or incompatible builds.
• Fixes:
  1. Use official or community-recommended portable APKs/ports for your platform.
  2. Grant storage permissions and place game files in accessible folders (e.g., /sdcard/ScummVM).
  3. For iOS, use apps that support document sharing or jailbreak-friendly file access methods.
  4. Check input settings for touch mapping; use external controllers if needed.

9. Network/cloud save or sync issues

• Cause: Portable setups lack integrated cloud support or path differences.
• Fixes:
  1. Use manual sync: copy the “saves” and “config” files between devices.
  2. Use third-party sync (Dropbox, Syncthing) pointed to your portable folder, ensuring ScummVM isn’t running during sync.
  3. Avoid simultaneous access from multiple devices to prevent corruption.

Quick troubleshooting checklist

• Use correct OS/arch build.
• Verify original game data files and folder paths.
• Ensure portable folder is writable.
• Test different audio/video backends and input mappings.
• Check logs by running from terminal; keep backups of saves/config.

If you want, I can generate step-by-step commands/log locations for your specific OS (Windows/macOS/Linux/Android).