TTS Mod Vault: Deployment & Usage Guide

A comprehensive guide for deploying, building, and using the TTS Mod Vault application.

1. Prerequisites

Before you begin, ensure you have the following installed:

Flutter SDK: Version 3.38.10 (as specified in the project's README). Follow the official Flutter installation guide for your operating system.
Git: For cloning the repository.
Tabletop Simulator (TTS): The application must be installed to locate your local mod and save folders. You do not need to be running it, but the directories must exist.
Platform-Specific Build Tools:
- Windows: Visual Studio 2022 with the "Desktop development with C++" workload.
- Linux: clang, libgtk-3-dev, pkg-config, and other dependencies as per the Flutter Linux docs.
- macOS: Xcode and the macOS SDK. Building for Apple Silicon (ARM64) is supported.

2. Installation (from Source)

Clone the Repository

git clone https://github.com/markomijic/TTS-Mod-Vault.git
cd TTS-Mod-Vault

Install Dependencies

Fetch all Dart/Flutter packages:

flutter pub get

3. Configuration

TTS Mod Vault requires paths to your Tabletop Simulator data folders. This is configured within the application after first launch.

Launch the Application (see Build & Run section below).
Navigate to Settings (gear icon).
Set the following paths:
- Mods Folder: Typically located at:
  - Windows: C:\Users\[YourUsername]\Documents\My Games\Tabletop Simulator\Mods
  - Linux: ~/.local/share/Tabletop Simulator/Mods
  - macOS: ~/Library/Application Support/Tabletop Simulator/Mods
- Saves Folder: Typically located at:
  - Windows: C:\Users\[YourUsername]\Documents\My Games\Tabletop Simulator\Saves
  - Linux: ~/.local/share/Tabletop Simulator/Saves
  - macOS: ~/Library/Application Support/Tabletop Simulator/Saves
(Optional) Configure other settings like Custom Asset URL font size, Exclude lists (audio, subfolders, domains), and URL replacement presets.

Note: The application does not use external environment variables or API keys. All configuration is managed through its GUI.

4. Build & Run

Development (Hot Reload)

Run the app in debug mode with hot reload capability:

flutter run

To target a specific platform:

flutter run -d windows
flutter run -d linux
flutter run -d macos

Production Build

Create a release executable for your current platform:

Windows:

flutter build windows --release

Output: build/windows/runner/Release/tts_mod_vault.exe

Linux:

flutter build linux --release

Output: build/linux/x64/release/bundle/tts_mod_vault

macOS:

flutter build macos --release

Output: build/macos/Build/Products/Release/tts_mod_vault.app (a .dmg can be created from this bundle).

To build for all supported platforms from a single machine (requires respective SDKs/IDEs):

flutter build windows --release
flutter build linux --release
flutter build macos --release

5. Deployment

Deployment involves distributing the built release artifacts.

For End Users (Pre-built Binaries)

Build the release executable for the target platform(s) as shown above.
Package the application:
- Windows: Zip the .exe file and any required DLLs from build/windows/runner/Release/.
- Linux: Zip the entire bundle directory.
- macOS: Create a .dmg disk image from the .app bundle using create-dmg or similar tool.
Upload the packaged release to:
- GitHub Releases: Create a new release in your repository and attach the platform-specific archives.
- NexusMods: As listed in the project's README.

For Developers (Source Distribution)

The source code is publicly available. Users can build from source by following the Prerequisites and Installation sections.

6. Troubleshooting

Common Issues & Solutions

Issue	Likely Cause	Solution
`flutter: command not found`	Flutter SDK not in PATH.	Add Flutter's `bin` directory to your system's PATH environment variable and restart your terminal.
Build fails on macOS with code signing errors.	macOS requires apps to be signed for distribution.	For local testing, you can run without signing. For distribution, configure code signing in Xcode or use `flutter build macos --release --no-codesign` for unsigned builds (users will need to bypass Gatekeeper).
Application cannot find Mods/Saves folders.	Incorrect paths set in Settings, or Tabletop Simulator has never been run.	1. Ensure Tabletop Simulator has been launched at least once to create default folders. 2. Manually set the correct paths in Settings as described in the Configuration section.
Asset downloads fail or time out.	Network issues, Steam Cloud rate limits, or invalid URLs.	Check your internet connection. The tool handles Steam Cloud URLs automatically. Use the "Check for invalid asset URLs" feature to identify broken links.
"No connected devices" when running `flutter run`.	No emulator/simulator running, or physical device not authorized.	For desktop, ensure you have the desktop development environment set up (see Prerequisites). Start the app with `flutter run -d windows` (or `linux`/`macos`).
Permission denied on Linux/macOS when running the built binary.	The executable lacks execute permissions.	Run `chmod +x <path_to_executable>` in the terminal. For the Linux bundle, execute `./tts_mod_vault` inside the `bundle` directory.
App crashes on startup (macOS).	macOS Gatekeeper blocking an unsigned app.	Right-click the `.app` bundle and select Open, then confirm. Alternatively, use `sudo spctl --add <app_path>` to bypass.

Getting Help

Check the GitHub Issues for known problems.
Ensure you are using the exact Flutter version (3.38.10) specified in the README. Use flutter downgrade 3.38.10 if needed.
For platform-specific Flutter desktop issues, consult the official Flutter desktop documentation.

How to Deploy & Use TTS-Mod-Vault