nt-backupper

Cross-platform backup suite for Nuclear Throne saves with local and cloud (Google Drive) storage

Features

• ✅ Local backups with configurable retention
• ☁️ Cloud backups to Google Drive (or any rclone remote)
• 🔄 Automatic pruning to manage storage
• 🎮 Integrated game launch workflow
• 💾 Cloud save restore with undo capability
• 🔒 Safe operations with locking and validation
• 🖥️ Cross-platform (Windows & macOS)

Prerequisites

Required Before Setup

Nuclear Throne lol

PowerShell 7+

Windows: Direct Download

MacOS: Direct Download

⚠️ Important: You must use pwsh (PowerShell 7), not powershell.exe (Windows PowerShell 5.1) or set PowerShell 7 as default program to open .ps1 files

OR

Windows:

winget install Microsoft.PowerShell

macOS:

brew install powershell/tap/powershell

Auto-Installed During Setup

• rclone - The setup script will install this for you

Installation & Setup

Step 1: Download

Clone the repo or go to Code > Download ZIP

Step 2: Run Setup Script

From the repository folder, run:

pwsh setup/setup.ps1

⚠️ Don't use "Run with PowerShell" from right-click menu - it uses PowerShell 5 installed by default

Step 3: Follow the Setup Wizard

The setup script will:

1. ✅ Check your PowerShell version
2. ✅ Detect your operating system
3. ✅ Install rclone (if missing)
4. ⚙️ Configure rclone for Google Drive
5. 📁 Create backup directories
6. ✅ Verify everything is ready

Step 4 (optional): Make a shortcut for backup-and-run.ps1

For convenience

rclone Configuration Guide

When the setup script runs rclone config, follow these steps:

⚠️ Important: The remote name must match rcloneRemote in your config.json (default: "NTBackups")

Creating a New Google Drive Remote

1. Type: n (New remote)

e/n/d/r/c/s/q> n

2. Enter: NTBackups (or match whatever is in your config.json)

name> NTBackups

3. Type: 24 (Google Drive)

Storage> 24

4. Press Enter (leave empty for default)

client_id>

5. Press Enter (leave empty for default)

client_secret>

6. Type: 1 (Full access - recommended)

scope> 1

7. Press Enter (leave empty)

service_account_file>

8. Type: n (No)

Edit advanced config? y/n> n

9. Type: y (Yes)

Use web browser to automatically authenticate? y/n> y

🌐 10. Your browser will open - Sign in to your Google account and allow access. 11. Type: n (No, unless you specifically want Team Drive)

Configure this as a Shared Drive (Team Drive)? y/n> n

12. Type: y (Yes)

Keep this "NTBackups" remote? y/e/d> y

13. Type: q (Quit)

e/n/d/r/c/s/q> q

✅ Done! The setup will verify your connection.

Configuration

Edit config.json to customize settings:

{
  "localKeep": 5,        // Number of local backups to keep
  "cloudKeep": 10,       // Number of cloud backups to keep
  "downloadKeep": 5,     // Downloaded backup retention
  "mountKeep": 5,        // Mount backup retention
  "rcloneRemote": "NTBackups",      // Your rclone remote name (must match what you created)
  "rcloneFolder": "NTSaveBackups",    // Folder within the remote (will be created automatically)
  "pauseOnError": true   // Wait for keypress on errors
}

⚠️ Important:

• rcloneRemote = Your rclone remote name (e.g., "NTBackups")
• rcloneFolder = Folder name within that remote (e.g., "NTSaveBackups")
• Full path = NTBackups:NTSaveBackups (creates a "NTSaveBackups" folder in your Google Drive)

Usage

Primary Workflow: Backup and Play

Creates local backup, uploads to cloud, then launches the game:

pwsh scripts/backup-and-run.ps1

Individual Operations

Create local backup only:

pwsh scripts/backup-local.ps1

Upload to cloud (after local backup):

pwsh scripts/upload-cloud.ps1

Prune old cloud backups:

pwsh scripts/prune-cloud.ps1

Cloud Save Management

Download and restore cloud save:

pwsh scripts/mount-save.ps1

This will:

1. Download the newest cloud backup
2. Backup your current save to backups/mount/
3. Replace your active save with the cloud backup

Undo cloud restore (revert to previous save):

pwsh scripts/undo-mount.ps1

Restores the save that was backed up before mounting a cloud save.

Directory Structure

nt-save-suite/
├── config.json              # Configuration file
├── .lock                    # Lock file (auto-managed)
├── setup/
│   └── setup.ps1           # Setup wizard
├── scripts/
│   ├── utils.ps1           # Shared utilities
│   ├── backup-local.ps1    # Local backup creation
│   ├── upload-cloud.ps1    # Cloud upload
│   ├── prune-cloud.ps1     # Cloud pruning
│   ├── backup-and-run.ps1  # Full backup + launch
│   ├── mount-save.ps1      # Cloud restore
│   └── undo-mount.ps1      # Restore previous save
└── backups/
    ├── local/              # Local backups
    ├── mount/              # Pre-mount backups
    └── download/           # Downloaded cloud backups

Save File Locations

• Windows: %LOCALAPPDATA%\nuclearthrone\nuclearthrone.sav
• macOS: ~/Library/Application Support/com.vlambeer.nuclearthrone/nuclearthrone.sav

How It Works

Lock File System

Scripts use a .lock file to prevent concurrent operations. If a script crashes and leaves the lock file behind, manually delete it:

Remove-Item .lock

Backup Naming

All backups use ISO timestamp format:

nuclearthrone_2026-02-13_14-30-45.sav

Automatic Pruning

• Local and cloud backups are automatically pruned to configured limits
• Newest files are kept based on creation/modification time
• Pruning happens after each backup/upload operation

Troubleshooting

"rclone remote 'NTBackups' is not configured"

The remote name in your rclone config doesn't match what's in config.json.

Check what remotes you have:

rclone listremotes

Then update config.json to match. For example, if you see NTBackups:, change:

"rcloneRemote": "NTBackups"

Where is the rclone config file?

Windows:

%APPDATA%\rclone\rclone.conf

(Usually: C:\Users\YourName\AppData\Roaming\rclone\rclone.conf)

macOS/Linux:

~/.config/rclone/rclone.conf

View your config:

rclone config file

Using the same remote on multiple computers (PC + Mac)

You have two options:

Option 1: Configure separately on each machine (Recommended)

Run rclone config on both machines using the same Google account. Each machine will have its own authentication but access the same Google Drive.

Option 2: Copy the config file

1. On your first machine, find the config:

   rclone config file

2. Copy rclone.conf to the same location on your second machine

3. Make sure config.json has the same rcloneRemote name on both machines

⚠️ Important: Both machines will share the same cloud folder, so backups from both will be in the same location. The suite will keep the newest cloudKeep backups total (not per machine).

"ERROR: PowerShell 7+ Required"

You're using Windows PowerShell 5.1 (the default on Windows). You need PowerShell 7+.

Install it:

winget install Microsoft.PowerShell

Then run with pwsh (not powershell.exe):

pwsh setup/setup.ps1

Script Window Closes Immediately

Don't right-click and "Run with PowerShell". Instead, open a terminal and run:

pwsh setup/setup.ps1

"Lock file exists" Error

Another operation may be running, or a previous operation crashed. Manually delete .lock:

Remove-Item .lock -Force

"Save file not found"

Ensure you've played Nuclear Throne at least once. The save file is created after first launch.

"rclone not found"

Install rclone and ensure it's in your PATH:

• rclone downloads
• Add to PATH or use full path to rclone executable

"Failed to access rclone remote"

Configure your rclone remote:

rclone config

Verify connection:

rclone lsd NTBackups:

Game Running Detection

Mount and undo operations will fail if Nuclear Throne is running. Close the game first.

Configuration Reference

Setting	Description	Default
localKeep	Local backups to retain	5
cloudKeep	Cloud backups to retain	10
downloadKeep	Downloaded backups to retain	5
mountKeep	Mount backups to retain	5
rcloneRemote	rclone remote name	"NTBackups"
rcloneFolder	Folder within the remote	"NTSaveBackups"
pauseOnError	Wait for keypress on error	true

Advanced Usage

Custom Backup Workflow

Create your own automation by importing the utility library:

# Import utilities
. "scripts/utils.ps1"

try {
    Lock-Operation
    
    # Your custom logic here
    $config = Get-Config
    $savePath = Get-SavePath
    
    # Use utility functions...
    
} finally {
    Unlock-Operation
}

Scheduled Backups

Windows Task Scheduler:

pwsh -File "C:\path\to\ntbackupper\scripts\backup-local.ps1"

macOS cron/launchd:

/usr/local/bin/pwsh /path/to/ntbackupper/scripts/backup-local.ps1

Multiple Cloud Remotes

To use different cloud providers:

1. Configure additional rclone remotes
2. Create separate config files (e.g., config-onedrive.json)
3. Modify scripts to accept config path parameter

Safety Features

• ✅ Lock file prevents concurrent operations
• ✅ Game running detection for mount/undo operations
• ✅ Save file validation (existence + non-zero size)
• ✅ Upload verification after cloud sync
• ✅ Automatic backup before mounting cloud saves
• ✅ Configurable error pause for debugging

License

This project is licensed under the MIT License - see the LICENSE file for details.

Nuclear Throne is a trademark of Vlambeer. This project is not affiliated with or endorsed by Vlambeer.

Support

For issues or questions:

1. Run setup to validate configuration: pwsh setup/setup.ps1
2. Check lock file status: Test-Path .lock
3. Verify rclone connection: rclone lsd <your-remote>:
4. Review script output for specific error messages