Troubleshooting Guide

Below are some of the common asked and faced problems in various forum and official GitHub repo. so we have gathered and provided detailed answer to it.

Question 1: What are the system requirements for SA Mod Manager?

Answer:
To run SA Mod Manager, you must have a computer running Windows 7 or later. In addition, the following runtimes are required:

  • .NET Desktop Runtime 8.0 (for the application itself)
  • Visual C++ Redistributable Runtimes (32-bit) – necessary for the Mod Loader component.

SA Mod Manager supports the following games:

  • Sonic Adventure DX PC, 2004 version (US release; other versions can be converted)
  • Sonic Adventure 2 (Battle) PC
    These requirements ensure that both the manager and the underlying mod loader function properly.

Question 2: How do I add my game if it isn’t automatically detected?

Answer:
If SA Mod Manager does not automatically detect your Sonic Adventure game folder, simply use the “Add…” button in the game list within the manager. Navigate to your game’s installation directory and select it. The manager will then install (or re-install) the Mod Loader into that folder automatically. This process ensures the proper integration of mods with your game files.

Question 3: Why does SA Mod Manager sometimes fail to launch Sonic Adventure 2 properly?

Answer:
Several users have reported that when attempting to launch Sonic Adventure 2 (SA2) using the mod manager, clicking “Save & Play” results in the game not launching (instead simply reloading the mods). This issue appears related to a bug where the manager’s check for installed mods returns true when no mod is installed.
Workarounds include:

  • Installing at least one mod: Installing even a simple mod (for example, “Chao World Extended”) can bypass the check, allowing SA2 to launch correctly.
  • GitHub Issue Reference: In GitHub issue #192 users discussed that if no mod is present, the manager fails to launch SA2; this was later identified as a bug that is scheduled for a fix in an upcoming update.
  • Additional Tips for Linux/Steam Deck users: On platforms like the Steam Deck, some additional steps (using tools such as Protontricks) may be necessary.

Question 4: How can I fix the “Error loading BASS” issue in Sonic Adventure 2?

Answer:
When using SA Mod Manager for SA2, you might encounter an error message stating:
“Error loading BASS. Make sure the mod loader is installed properly.”
To resolve this:

  • Copy the Executable: Copy the SAModManager.exe file from your Sonic Adventure DX folder into the Sonic Adventure 2 folder.
  • Run via Protontricks (for Linux/Steam Deck): If you are running the game under Proton (for example, on a Steam Deck), run the copied executable through Protontricks (or your preferred compatibility tool) with Sonic Adventure DX as the target. This process forces the installation of the missing BASS libraries that SA2 relies on.
  • Reinstall Required Runtimes: Also ensure that you have the latest .NET runtime and Visual C++ redistributables installed.

Question 5: How do I update SA Mod Manager to the latest version?

Answer:
SA Mod Manager is actively maintained on GitHub. To update:

  1. Visit the Releases Page: Download the latest release ZIP file.
  2. Extract the Files: Unzip the package to a convenient folder.
  3. Replace the Old Version: Replace your existing SA Mod Manager executable and related files with those from the new release.
  4. Reconfigure if Necessary: In some cases, you may need to reconfigure your game paths if the update changes certain settings.
    Always check the changelog (often provided in the release notes) for any specific upgrade instructions or new prerequisites.

Question 6: My mods are not appearing in the mod library—what should I do?

Answer:
If your installed mods do not appear in the SA Mod Manager library, consider the following troubleshooting steps:

  • Verify File Format: Ensure that your mod archives are in supported formats (such as ZIP or RAR) and that the mod files follow the proper directory structure expected by the manager.
  • Rescan the Directory: Use the “Rescan” or “Refresh” function within the manager to force a new scan of your mods folder.
  • Check Mod Metadata: Some mods include metadata files that help SA Mod Manager recognize them. If these files are missing or corrupted, the mod might not display properly.
  • Update the Manager: Make sure you are running the latest version of SA Mod Manager, as bugs affecting mod detection may have been fixed in updates.

These steps should help ensure that all installed mods are correctly detected and listed in the interface.

Question 7: How do I create and switch between multiple mod profiles?

Answer:
SA Mod Manager allows you to create separate profiles to manage different sets of mods for various gameplay experiences. Here’s how:

  1. Creating a Profile: In the Profile Manager section, click “Create New Profile.” Give it a descriptive name (e.g., “High-Res Graphics” or “SA2 Experimental Mods”).
  2. Customizing the Profile: Enable or disable mods as needed for that profile. You can also adjust the load order manually to optimize compatibility.
  3. Switching Profiles: Use the profile drop-down menu to switch between your different profiles. When you select a profile, SA Mod Manager automatically enables the mods configured for that profile and disables others.
    This feature is especially useful for testing new mods without affecting your stable setup.

Question: Why does SA Mod Manager require a mod to be installed to launch Sonic Adventure 2?

Answer:
A known bug in SA Mod Manager causes Sonic Adventure 2 (SA2) not to launch if no mods are installed. In this case, the manager’s internal check mistakenly prevents the game from starting.
Temporary workaround:

  • Install a Dummy Mod: Simply install any mod (even a minor one) so that the check passes and SA2 can launch.
    This bug has been acknowledged by the developers and is expected to be fixed in an upcoming update.

Question 9: How do I resolve input issues (such as the jump/confirm button pausing the game) with SA Mod Manager?

Answer:
Some users have reported that when using SA Mod Manager with Sonic Adventure DX, the game misinterprets the jump/confirm button input—often pausing the game instead of confirming an action. This is typically due to issues with the Input Mod configuration.
Steps to fix input issues:

  • Check Input Mapping: Open the Input Mod configuration (usually accessible via the mod manager’s settings or by navigating to the “Input-Mod” folder) and verify that your controller’s buttons are mapped correctly.
  • Reassign the Action: Manually change the action associated with the jump/confirm button from “Start” to the intended action, then save the configuration.
  • Enable/Update the Input Mod: Ensure that the latest version of the Input Mod is installed, as updates may have corrected these mapping issues.
    Some users found that enabling a dedicated Input Mod resolved the issue permanently.

Question 10: What should I do if I encounter a JSON parsing error (e.g., “JSON integer is too large for an Int32”) on startup?

Answer:
Some users have experienced errors related to JSON parsing when SA Mod Manager attempts to fetch update artifacts or configuration data from GitHub. This error is typically thrown by Newtonsoft.Json when an artifact ID exceeds the size of a 32-bit integer.
Recommended solutions:

  • Update to the Latest Dev Build: The issue has been addressed in recent development builds. Updating to the latest version should resolve the error.
  • Wait for the Next Stable Release: If you’re using a stable release, check the GitHub issues page (for example, issue #265) to see if a fix is scheduled for the next release.
  • Temporary Workaround: In some cases, manually editing configuration files or forcing a re-download of artifact data may clear the error. However, it is best to rely on an official update.
    (Reference: GitHub Issue #265)

Question 11: How can I contribute a new language translation for SA Mod Manager?

Answer:
SA Mod Manager supports multiple languages for its user interface. If you’d like to contribute a translation:

  1. Follow the Translation Guide: Check the documentation or tutorial linked in the GitHub repository (often referenced in the README) for instructions on adding a new language.
  2. Update Resource Files: You will need to create or modify the language resource files with your translations.
  3. Submit a Pull Request: Once your translation is complete, submit a pull request on the GitHub repository for review by the developers.
    Contributions like these are highly appreciated and help make the tool accessible to a broader audience.